Skip to content

Latest commit

 

History

History
80 lines (59 loc) · 3.98 KB

README.md

File metadata and controls

80 lines (59 loc) · 3.98 KB
Raw

Manipulate Sphinx config to keep old Read the Docs' behavior

Note

This extension is a temporary workaround to allow authors/theme developers to keep the old build behavior while they perform the required changes in their documentation/themes to not depend on it.

Read the Docs used to manipulate the Sphinx's conf.py file to:

  • Inject different variables into the html_context
  • Add some extra JavaScript and CSS files (via readthedocs-sphinx-ext extension)
  • Configure canonical URL
  • Define latex_elements and latex_engine
  • Add _build to exclude_patterns
  • ... and others

All this behavior was originally hardcoded on Read the Docs builders (doc_builder/conf.py.tmpl) and users weren't able to opt-out. Read the Docs has deprecated this behavior and moved out from its core, making a Sphinx project to build exactly in the same way that it would build locally. However, projects requiring the old and deprecated behavior may want to install this extension as a workaround while they perform the migration. This migration may include updating Sphinx templates and hitting an API from their conf.py to get some data.

Installation

  1. Install the package using pip

    pip install git+https://github.com/readthedocs/sphinx-build-compatibility#egg=sphinx-build-compatibility

  2. Add the extension in your Sphinx's conf.py file:

    extensions = [
    # ... other extensions
    "sphinx_build_compatibility.extension",
]

Differences with the deprecated behavior

There are some small differences with the old/deprecated behavior that we may implement in a future iteration in case we receive some feedback from the users and we are not able to work with them in a workaround.

The following variables are not injected in the html_context:

Variable Old value for reference
MEDIA_URL https://media.readthedocs.org/
STATIC_URL https://assets.readthedocs.org/static/
analytics_code UA-123456
api_host https://readthedocs.org
name My project
programming_language words
proxied_api_host /_
proxied_static_path /_/static/
single_version False

Note that all these variables were used internally by Read the Docs and should probably not be required for regular users. However, if you need any of these variables, read the following "Feedback" section.

Feedback

We are happy to receive any feedback you may have regarding the Sphinx context injecting performed by Read the Docs. This will help us to understand more your use case and adapt this extension to keep that compatibility; or suggest you a potential solution/workaround for it.

If you want to share anything with us, or are unsure about whether or not your need this extension, please open a new issue in this repository.

Reference