Edit your project’s setup.py

1. Add pylons-sphinx-themes to your project’s requirements in its setup.py. Here’s an example from Pyramid.

   docs_extras = [
       'Sphinx >= 1.7.5', # Read The Docs minimum version
       'docutils',
       'repoze.sphinx.autointerface',
       'pylons-sphinx-themes',
   ]

Edit your Sphinx’s conf.py

1. Near the top, add the following.

   import pylons_sphinx_themes

2. Activate the theme.

   html_theme = 'pyramid'
   html_theme_path = pylons_sphinx_themes.get_html_themes_path()

3. (Recommended) Enable Ethical Ads. Doing so supports both Read the Docs and the Python Software Foundation with ad revenue.

   # Control display of sidebars
   html_sidebars = { '**': [
       'localtoc.html',
       'ethicalads.html',
       'relations.html',
       'sourcelink.html',
       'searchbox.html',
   ] }

4. If you were previously using the git submodule method to use the Pylons theme, then comment or delete the block of code under the following statement.

   # Add and use Pylons theme
   if 'sphinx-build' in ' '.join(sys.argv):  # protect against dumb importers

5. (Optional) Set a canonical root URL. The URL points to the root of the documentation, and requires a trailing slash.

   html_theme_options = dict(
       canonical_url='http://the_root_domain/latest/docs/'
   )

Undo git submodule method

If you were previously using the git submodule method to use the Pylons theme, then perform the following additional steps.

1. Remove .gitmodules.

   cd <your_project_directory>
   git rm .gitmodules

2. Deinitialize the submodule.

   cd docs/_themes
   git submodule deinit .

3. Remove the submodule’s directory.

   cd ..
   git rm _themes/

4. Edit your Sphinx’s Makefile. The following is an example diff from Pyramid.

   -html: themes
   +html:
   # ...
   -htmlhelp: themes
   +htmlhelp:
   #...
   -themes:
   -    cd ..; git submodule update --init --recursive; cd docs;

Update tox.ini

If you use tox, you can specify dependencies for building your docs either in your setup.py (preferred) or in your tox.ini (duplicitous). See the example from Pyramid.

docs_extras = [
    'Sphinx >= 1.7.5',
    'docutils',
    'repoze.sphinx.autointerface',
    'pylons_sphinx_latesturl',
    'pylons-sphinx-themes',
]

# ...

extras_require = {
    'testing':testing_extras,
    'docs':docs_extras,
},

Otherwise you can repeat yourself and edit your tox.ini. The following example is from waitress.

deps =
    Sphinx
    repoze.sphinx.autointerface
    pylons-sphinx-themes

Update Read the Docs configuration

If you specify package requirements for Read the Docs, specify dependencies in your rtd.txt. You can either name them explicitly, which might be duplicitous:

pylons-sphinx-themes

or you can rely on your setup.py configuration, specifying dependencies in only one place, by simply using this in your rtd.txt.

-e .[docs]

Available themes

• pylons - the generic Pylons Project documentation theme

• pyramid - the specific Pyramid documentation theme

• pylonsfw - the specific Pylons Framework documentation theme

1.0.13 (2020-11-30)

• Revert fix of linenos in tables. Sphinx fixed this issue in v3.0. RTD rolled it out as a feature flag in April 2020, and it now appears to be rolling out in more projects.

• Add padding to the top of linenodiv to align with code in tables and its extra 2px top border.

1.0.12 (2020-11-28)

• Added style .wy-table-responsive { overflow-x: scroll; } to prevent tables from blowout by long dotted method names.

1.0.11 (2020-01-13)

• Fix the width of linenos table column when used in code-blocks.

1.0.10 (2018-09-25)

• Add Read the Docs to the recipients of ad revenue.

1.0.9 (2018-09-23)

• Remove hyphenation because it sometimes hyphenates inappropriately, such as in code.

1.0.8 (2018-09-21)

• Fix support for Ethical Ads.

1.0.7 (2018-09-21)

• Added support for Ethical Ads for Read The Docs. See https://github.com/Pylons/pylons-sphinx-themes/pull/12

1.0.6 (2017-09-22)

• Update zest.releaser in order to release to PyPI.

1.0.5 (2017-09-22)

• Clean up licensing https://github.com/Pylons/pylons-sphinx-themes/issues/8

1.0.4 (2017-06-20)

• Specify line spacing for list items for only within the .body class.

1.0.3 (2017-06-20)

• Add line spacing for list items. Closes #4.

1.0.2 (2017-06-16)

• Remove HTTPS protocol to allow either HTTPS or HTTP.

1.0.1 (2017-06-16)

• Use HTTPS for protocol of stylesheets.

1.0 (2017-04-18)

• Use zest.releaser for releasing.

• Improve documentation.

0.3.1 (2015-04-15)

• Improve documentation.

0.3 (2015-04-15)

• Convert from using git submodule used in https://github.com/Pylons/pylons_sphinx_theme to a package. See https://github.com/Pylons/pyramid/issues/1614

• Initial commit.