pylons-sphinx-themes 1.0

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.3.1', # 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. 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

4. (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.3.1',
    '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 (2017-04-16)

• 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.