skip to navigation
skip to content

pylons-sphinx-themes 1.0.6

Sphinx themes for Pylons Project documentation.

Pylons Sphinx Themes

This repository is a Python package that contains Sphinx themes for Pylons related projects. This project is based on Pylons Sphinx Theme (singular), but uses a package implementation instead of git submodules and manual steps.

To use a theme in your Sphinx documentation, follow this guide.

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

Change log for pylons-sphinx-themes

1.0.6 (2017-09-22)

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

1.0.5 (2017-09-22)

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)

 
File Type Py Version Uploaded on Size
pylons-sphinx-themes-1.0.6.tar.gz (md5) Source 2017-09-22 137KB
pylons_sphinx_themes-1.0.6-py2.py3-none-any.whl (md5) Python Wheel py2.py3 2017-09-22 136KB