mirror of
https://github.com/readthedocs/sphinx_rtd_theme.git
synced 2025-02-25 18:55:21 -06:00
102 lines
4.1 KiB
ReStructuredText
102 lines
4.1 KiB
ReStructuredText
|
|
*************
|
|
Configuration
|
|
*************
|
|
|
|
You can configure different parts of the theme.
|
|
|
|
Project-wide Configuration
|
|
==========================
|
|
|
|
HTML Theme Options
|
|
------------------
|
|
|
|
The theme's project-wide options are defined in the ``sphinx_rtd_theme/theme.conf``
|
|
file of this repository, and can be defined in your project's ``conf.py`` via
|
|
``html_theme_options``. For example:
|
|
|
|
.. code:: python
|
|
|
|
html_theme_options = {
|
|
'canonical_url': '',
|
|
'analytics_id': '',
|
|
'logo_only': False,
|
|
'display_version': True,
|
|
'prev_next_buttons_location': 'bottom',
|
|
'style_external_links': False,
|
|
'vcs_pageview_mode': '',
|
|
# Toc options
|
|
'collapse_navigation': False,
|
|
'sticky_navigation': True,
|
|
'navigation_depth': 4,
|
|
'includehidden': True,
|
|
'titles_only': False
|
|
}
|
|
|
|
The following options are available:
|
|
|
|
Base options
|
|
~~~~~~~~~~~~
|
|
|
|
* ``canonical_url`` String. This will specify a `canonical url <https://en.wikipedia.org/wiki/Canonical_link_element>`__
|
|
to let search engines know they should give higher ranking to latest version of the docs.
|
|
The url points to the root of the documentation and requires a trailing slash.
|
|
* ``analytics_id`` String. Change the Google Analytics ID that is included on pages.
|
|
* ``display_version`` Bool. With this disabled, the version number isn't shown at the top of the sidebar.
|
|
* ``prev_next_buttons_location`` String. can take the value ``bottom``, ``top``, ``both`` , or ``None``
|
|
and will display the "Next" and "Previous" buttons accordingly.
|
|
* ``style_external_links`` Bool. Add an icon next to external links. Defaults to ``False``.
|
|
* ``vcs_pageview_mode`` String. 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`.
|
|
|
|
TOC Options
|
|
~~~~~~~~~~~
|
|
|
|
These effect how we display the Table of Contents in the side bar. You can read more about them here: http://www.sphinx-doc.org/en/stable/templating.html#toctree
|
|
|
|
* ``collapse_navigation`` Bool. With this enabled, you will lose the ``[+]`` drop downs next to each section in the sidebar.
|
|
This is useful for *very large* documents.
|
|
* ``sticky_navigation`` Bool. This causes the sidebar to scroll with the main page content as you scroll the page.
|
|
* ``navigation_depth`` Int. Indicate the max depth of the tree; by default, all levels are included.
|
|
* ``includehidden`` Bool. Specifies if the sidebar includes toctrees marked with the ``:hidden:`` option
|
|
* ``titles_only`` Bool. If True, removes headers within a page from the sidebar.
|
|
|
|
HTML Context Options
|
|
--------------------
|
|
|
|
TODO.
|
|
|
|
|
|
Page-level Configuration
|
|
========================
|
|
|
|
Pages support metadata that changes how the theme renders.
|
|
You can currently add the following:
|
|
|
|
* ``:github_url:`` This will force the "Edit on GitHub" to the configured URL
|
|
* ``:bitbucket_url:`` This will force the "Edit on Bitbucket" to the configured URL
|
|
* ``:gitlab_url:`` This will force the "Edit on GitLab" to the configured URL
|
|
|
|
|
|
How the Table of Contents builds
|
|
================================
|
|
|
|
Currently the left menu will build based upon any ``toctree(s)`` defined in your ``index.rst`` file.
|
|
It outputs 2 levels of depth, which should give your visitors a high level of access to your
|
|
docs. If no toctrees are set the theme reverts to sphinx's usual local toctree.
|
|
|
|
It's important to note that if you don't follow the same styling for your rST headers across
|
|
your documents, the toctree will misbuild, 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: <hidden_>`_ 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 vertically too large, it will revert to static positioning. To disable the sticky nav
|
|
altogether change the setting in ``conf.py``.
|
|
|
|
.. _hidden: http://sphinx-doc.org/markup/toctree.html
|