mirror of
https://github.com/readthedocs/sphinx_rtd_theme.git
synced 2025-02-25 18:55:21 -06:00
Sphinx theme for readthedocs.org
1f7bdc1c36
- You can see a practical demonstration of the problem, fully seeing the effect if it is not fixed, here (though that example uses the alabaster theme, the effect is the same here): https://github.com/executablebooks/sphinx-copybutton/issues/110 - This is a copy of a fix from Sphinx. The sphinx pull request is https://github.com/sphinx-doc/sphinx/pull/8524 Detailed description: - url_root is set to `#` on the index page, which layout.html tries to change back to `''` (the empty string). - But, this updated url_root wasn't used in the actual location, as an argument to `documentation_options.js`. - Thus, clever enough templates, which tried to use `$DOCUMENTATION_OPTIONS.URL_ROOT` inside javascript would fail. This was manifested as broken links, which led to this issue: https://github.com/executablebooks/sphinx-copybutton/issues/110 - I have eventually traced that back to sphinx itself, and found that layout.html tried to fix the problem, but the fixed value wasn't used. - This fix works in my basic test, but I will continue with more tests. - Review: - someone more clever should examine this and make sure it makes sense - This does not have tests. Should it? |
||
|---|---|---|
| .circleci | ||
| .github | ||
| .tx | ||
| bin | ||
| docs | ||
| sphinx_rtd_theme | ||
| src | ||
| tests | ||
| .gitattributes | ||
| .gitignore | ||
| .readthedocs.yml | ||
| Apache-License-2.0.txt | ||
| babel.cfg | ||
| LICENSE | ||
| MANIFEST.in | ||
| OFL-License.txt | ||
| package-lock.json | ||
| package.json | ||
| README.rst | ||
| setup.cfg | ||
| setup.py | ||
| tox.ini | ||
| webpack.common.js | ||
| webpack.dev.js | ||
| webpack.prod.js | ||
**************************
Read the Docs Sphinx Theme
**************************
.. image:: https://img.shields.io/pypi/v/sphinx_rtd_theme.svg
:target: https://pypi.python.org/pypi/sphinx_rtd_theme
:alt: Pypi Version
.. image:: https://circleci.com/gh/readthedocs/sphinx_rtd_theme.svg?style=svg
:alt: Build Status
:target: https://circleci.com/gh/readthedocs/sphinx_rtd_theme
.. image:: https://img.shields.io/pypi/l/sphinx_rtd_theme.svg
:target: https://pypi.python.org/pypi/sphinx_rtd_theme/
:alt: License
.. image:: https://readthedocs.org/projects/sphinx-rtd-theme/badge/?version=latest
:target: http://sphinx-rtd-theme.readthedocs.io/en/latest/?badge=latest
:alt: Documentation Status
This Sphinx_ theme was designed to provide a great reader experience for
documentation users on both desktop and mobile devices. This theme is used
primarily on `Read the Docs`_ but can work with any Sphinx project. You can find
a working demo of the theme in the `theme documentation`_
.. _Sphinx: http://www.sphinx-doc.org
.. _Read the Docs: http://www.readthedocs.org
.. _theme documentation: https://sphinx-rtd-theme.readthedocs.io/en/latest/
Installation
============
This theme is distributed on PyPI_ and can be installed with ``pip``:
.. code:: console
$ pip install sphinx-rtd-theme
To use the theme in your Sphinx project, you will need to add the following to
your ``conf.py`` file:
.. code:: python
import sphinx_rtd_theme
extensions = [
...
"sphinx_rtd_theme",
]
html_theme = "sphinx_rtd_theme"
For more information read the full documentation on `installing the theme`_
.. _PyPI: https://pypi.python.org/pypi/sphinx_rtd_theme
.. _installing the theme: https://sphinx-rtd-theme.readthedocs.io/en/latest/installing.html
Configuration
=============
This theme is highly customizable on both the page level and on a global level.
To see all the possible configuration options, read the documentation on
`configuring the theme`_.
.. _configuring the theme: https://sphinx-rtd-theme.readthedocs.io/en/latest/configuring.html
Contributing
============
If you would like to help modify or translate the theme, you'll find more
information on contributing in our `contributing guide`_.
.. _contributing guide: https://sphinx-rtd-theme.readthedocs.io/en/latest/contributing.html