Skip to content

Latest commit

 

History

History
226 lines (151 loc) · 6.43 KB

configuring.rst

File metadata and controls

226 lines (151 loc) · 6.43 KB
Raw

Configuration

Theme options

The following options can be defined in your project's conf.py file, using the html_theme_options <sphinx:html_theme_options> configuration option.

For example:

html_theme_options = {
    'analytics_id': 'UA-XXXXXXX-1',  #  Provided by Google in your dashboard
    'logo_only': False,
    'display_version': True,
    'prev_next_buttons_location': 'bottom',
    'style_external_links': False,
    'vcs_pageview_mode': '',
    'style_nav_header_background': 'white',
    # Toc options
    'collapse_navigation': True,
    'sticky_navigation': True,
    'navigation_depth': 4,
    'includehidden': True,
    'titles_only': False
}

Table of contents options

The following options change how :rstsphinx:toctree directives generate documentation navigation.

collapse_navigation

type

boolean

default

True

With this enabled, navigation entries are not expandable -- the [+] icons next to each entry are removed.

sticky_navigation

type

boolean

default

True

Scroll the navigation with the main page content as you scroll the page.

navigation_depth

type

integer

default

4

The maximum depth of the table of contents tree. Set this to -1 to allow unlimited depth.

includehidden

type

boolean

default

True

Specifies if the navigation includes hidden table(s) of contents -- that is, any :rstsphinx:toctree directive that is marked with the :hidden: option.

titles_only

type

boolean

default

False

When enabled, page subheadings are not included in the navigation.

Note

Setting collapse_navigation to False and using a high value for navigation_depth on projects with many files and a deep file structure can cause long compilation times and can result in HTML files that are significantly larger in file size.

Miscellaneous options

analytics_id

type

string

If specified, Google Analytics' javascript is included in your pages. Set the value to the ID provided to you by google (like UA-XXXXXXX).

canonical_url

type

URL

This will specify a canonical URL meta link element to tell search engines which URL should be ranked as the primary URL for your documentation. This is important if you have multiple URLs that your documentation is available through. The URL points to the root path of the documentation and requires a trailing slash.

0.6.0

Use sphinx:html_baseurl instead.

display_version

type

boolean

default

True

If True, the version number is shown at the top of the sidebar.

logo_only

type

boolean

default

False

Only display the logo image, do not display the project name at the top of the sidebar

prev_next_buttons_location

type

string

default

bottom

Location to display Next and Previous buttons. This can be either bottom, top, both , or None.

style_external_links

type

boolean

default

False

Add an icon next to external links.

vcs_pageview_mode

type

string

default

blob or view

Changes how to view files when using display_github, display_gitlab, etc. When using GitHub or GitLab this can be: blob (default), edit, or raw. On Bitbucket, this can be either: view (default) or edit.

style_nav_header_background

type

string

default

#2980B9

Changes the background of the search area in the navigation bar. The value can be anything valid in a CSS background property.

File-wide metadata

The following options can be used as file-wide metadata <sphinx:metadata>:

github_url

Force the Edit on GitHub button to use the configured URL.

bitbucket_url

Force the Edit on Bitbucket button to use the configured URL.

gitlab_url

Force the Edit on GitLab button to use the configured URL.

Other configuration

Using the Sphinx standard option :pyhtml_logo <sphinx:html_logo>, you can set an image file to be used as a logo at the top of the sidebar. The theme option :pylogo_only also allows for only the logo to be shown at the top of the sidebar.

Adding custom CSS or Javascript

Adding custom CSS or Javascript can help you alter the look and feel of this theme without forking the theme for local use.

In order to add custom CSS or Javascript without disrupting the existing theme files, you can add files to be included in your documentation output <rtd:guides/adding-custom-css>.

How the table of contents displays

Currently the left menu will build based upon any toctree directives defined in your source files. It outputs 4 levels of depth by default, to allow for quick navigation through topics. If no TOC trees are defined, Sphinx's default behavior is to use the page headings instead.

It's important to note that if you don't follow the same styling for your reST headings across your documents, the TOC tree will build incorrectly, and the resulting menu might not show the correct depth when it renders.

Also note that by default the table of contents is set with includehidden=True. This allows you to set a hidden TOC in your index file with the :hidden: <sphinx:toctree-directive> property that will allow you to build a TOC without it rendering in your index.

By default, the navigation will "stick" to the screen as you scroll. However if your TOC is not tall enough, it will revert to static positioning. To disable the sticky navigation altogether, change the sticky_navigation theme option.