Metadata-Version: 2.1
Name: pylons-sphinx-themes
Version: 1.0.13
Summary: Sphinx themes for Pylons Project documentation.
Home-page: https://pylonsproject.org
Author: Steve Piercy
Author-email: pylons-discuss@googlegroups.com
License: BSD-derived (http://www.repoze.org/LICENSE.txt)
Project-URL: Documentation, https://github.com/Pylons/pylons-sphinx-themes#pylons-sphinx-themes
Project-URL: Issue Tracker, https://github.com/Pylons/pylons-sphinx-themes/issues
Keywords: pyramid pylons web sphinx documentation
Platform: UNKNOWN
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Web Environment
Classifier: Framework :: Sphinx :: Theme
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: Repoze Public License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Topic :: Documentation
Classifier: Topic :: Documentation :: Sphinx
Classifier: Topic :: Software Development :: Documentation
License-File: LICENSE.txt

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.


