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 <https://github.com/Pylons/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`

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

.. code-block:: python

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

Edit your Sphinx's `conf.py`

#. Near the top, add the following.

.. code-block:: python

    import pylons_sphinx_themes

#. Activate the theme.

.. code-block:: python

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

#. (Recommended) Enable Ethical Ads <https://docs.readthedocs.io/en/latest/advertising/ethical-advertising.html>.
Doing so supports both Read the Docs <https://readthedocs.org/> and the Python Software Foundation <https://www.python.org/psf-landing/>_ with ad revenue.

.. code-block:: python

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

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

.. code-block:: python

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

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

.. code-block:: python

    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.

#. Remove .gitmodules.

.. code-block:: bash

    cd <your_project_directory>
    git rm .gitmodules

#. Deinitialize the submodule.

.. code-block:: bash

    cd docs/_themes
    git submodule deinit .

#. Remove the submodule's directory.

.. code-block:: bash

    cd ..
    git rm _themes/

#. Edit your Sphinx's Makefile. The following is an example diff <https://github.com/Pylons/pyramid/pull/1636/files>_ from Pyramid.

.. code-block:: diff

   -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 <https://github.com/Pylons/pyramid/blob/master/setup.py#L58-L64>_.

.. code-block:: ini

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 <https://github.com/Pylons/waitress/blob/master/tox.ini#L28>_.

.. code-block:: ini

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:

.. code-block:: text

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.

.. code-block:: text

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

Package profile

pylons-sphinx-themes

Releases

Release table

PyPI Downloads

Dependencies

Details

Project URLs

Dependencies

Package description