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.
Raw data
{
"_id": null,
"home_page": "https://pylonsproject.org",
"name": "pylons-sphinx-themes",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "pyramid pylons web sphinx documentation",
"author": "Steve Piercy",
"author_email": "pylons-discuss@googlegroups.com",
"download_url": "https://files.pythonhosted.org/packages/49/8d/723d5d3ec0a469f3ebc381990d08dc4bf8932257ccb02ca5883a3fc9d978/pylons-sphinx-themes-1.0.13.tar.gz",
"platform": "",
"description": "Pylons Sphinx Themes\n====================\n\nThis 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.\n\nTo use a theme in your Sphinx documentation, follow this guide.\n\n\nEdit your project's ``setup.py``\n--------------------------------\n#. Add ``pylons-sphinx-themes`` to your project's requirements in its ``setup.py``.\n Here's an example from Pyramid.\n\n .. code-block:: python\n\n docs_extras = [\n 'Sphinx >= 1.7.5', # Read The Docs minimum version\n 'docutils',\n 'repoze.sphinx.autointerface',\n 'pylons-sphinx-themes',\n ]\n\n\nEdit your Sphinx's ``conf.py``\n------------------------------\n#. Near the top, add the following.\n\n .. code-block:: python\n\n import pylons_sphinx_themes\n\n#. Activate the theme.\n\n .. code-block:: python\n\n html_theme = 'pyramid'\n html_theme_path = pylons_sphinx_themes.get_html_themes_path()\n\n#. (Recommended) Enable `Ethical Ads <https://docs.readthedocs.io/en/latest/advertising/ethical-advertising.html>`_.\n Doing so supports both `Read the Docs <https://readthedocs.org/>`_ and the `Python Software Foundation <https://www.python.org/psf-landing/>`_ with ad revenue.\n\n .. code-block:: python\n\n # Control display of sidebars\n html_sidebars = { '**': [\n 'localtoc.html',\n 'ethicalads.html',\n 'relations.html',\n 'sourcelink.html',\n 'searchbox.html',\n ] }\n\n#. 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.\n\n .. code-block:: python\n\n # Add and use Pylons theme\n if 'sphinx-build' in ' '.join(sys.argv): # protect against dumb importers\n\n#. (Optional) Set a canonical root URL.\n The URL points to the root of the documentation, and requires a trailing slash.\n\n .. code-block:: python\n\n html_theme_options = dict(\n canonical_url='http://the_root_domain/latest/docs/'\n )\n\n\nUndo git submodule method\n-------------------------\nIf you were previously using the git submodule method to use the Pylons theme, then perform the following additional steps.\n\n#. Remove ``.gitmodules``.\n\n .. code-block:: bash\n\n cd <your_project_directory>\n git rm .gitmodules\n\n#. Deinitialize the submodule.\n\n .. code-block:: bash\n\n cd docs/_themes\n git submodule deinit .\n\n#. Remove the submodule's directory.\n\n .. code-block:: bash\n\n cd ..\n git rm _themes/\n\n#. Edit your Sphinx's ``Makefile``. The following is an `example diff <https://github.com/Pylons/pyramid/pull/1636/files>`_ from Pyramid.\n\n .. code-block:: diff\n\n -html: themes\n +html:\n # ...\n -htmlhelp: themes\n +htmlhelp:\n #...\n -themes:\n - cd ..; git submodule update --init --recursive; cd docs;\n\n\nUpdate ``tox.ini``\n------------------\nIf 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>`_.\n\n.. code-block:: ini\n\n docs_extras = [\n 'Sphinx >= 1.7.5',\n 'docutils',\n 'repoze.sphinx.autointerface',\n 'pylons_sphinx_latesturl',\n 'pylons-sphinx-themes',\n ]\n\n # ...\n\n extras_require = {\n 'testing':testing_extras,\n 'docs':docs_extras,\n },\n\nOtherwise 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>`_.\n\n.. code-block:: ini\n\n deps =\n Sphinx\n repoze.sphinx.autointerface\n pylons-sphinx-themes\n\n\nUpdate Read the Docs configuration\n----------------------------------\nIf you specify package requirements for Read the Docs, specify dependencies in your ``rtd.txt``. You can either name them explicitly, which might be duplicitous:\n\n.. code-block:: text\n\n pylons-sphinx-themes\n\nor you can rely on your ``setup.py`` configuration, specifying dependencies in only one place, by simply using this in your ``rtd.txt``.\n\n.. code-block:: text\n\n -e .[docs]\n\n\nAvailable themes\n----------------\n\n- **pylons** - the generic Pylons Project documentation theme\n- **pyramid** - the specific Pyramid documentation theme\n- **pylonsfw** - the specific Pylons Framework documentation theme\n\n\nChange log for pylons-sphinx-themes\n===================================\n\n1.0.13 (2020-11-30)\n-------------------\n\n- Revert fix of linenos in tables. Sphinx fixed this issue in v3.0. RTD rolled\n it out as a feature flag in April 2020, and it now appears to be rolling out\n in more projects.\n- Add padding to the top of `linenodiv` to align with code in tables and its\n extra 2px top border.\n\n\n1.0.12 (2020-11-28)\n-------------------\n\n- Added style ``.wy-table-responsive { overflow-x: scroll; }`` to prevent\n tables from blowout by long dotted method names.\n\n\n1.0.11 (2020-01-13)\n-------------------\n\n- Fix the width of linenos table column when used in code-blocks.\n\n\n1.0.10 (2018-09-25)\n-------------------\n\n- Add Read the Docs to the recipients of ad revenue.\n\n\n1.0.9 (2018-09-23)\n------------------\n\n- Remove hyphenation because it sometimes hyphenates inappropriately, such as\n in code.\n\n\n1.0.8 (2018-09-21)\n------------------\n\n- Fix support for Ethical Ads.\n\n\n1.0.7 (2018-09-21)\n------------------\n\n- Added support for Ethical Ads for Read The Docs. See\n https://github.com/Pylons/pylons-sphinx-themes/pull/12\n\n\n1.0.6 (2017-09-22)\n------------------\n\n- Update zest.releaser in order to release to PyPI.\n\n\n1.0.5 (2017-09-22)\n------------------\n\n- Clean up licensing\n https://github.com/Pylons/pylons-sphinx-themes/issues/8\n\n\n1.0.4 (2017-06-20)\n------------------\n\n- Specify line spacing for list items for only within the .body class.\n\n\n1.0.3 (2017-06-20)\n------------------\n\n- Add line spacing for list items. Closes #4.\n\n\n1.0.2 (2017-06-16)\n------------------\n\n- Remove HTTPS protocol to allow either HTTPS or HTTP.\n\n\n1.0.1 (2017-06-16)\n------------------\n\n- Use HTTPS for protocol of stylesheets.\n\n\n1.0 (2017-04-18)\n------------------\n\n- Use zest.releaser for releasing.\n- Improve documentation.\n\n\n0.3.1 (2015-04-15)\n------------------\n\n- Improve documentation.\n\n\n0.3 (2015-04-15)\n----------------\n\n- Convert from using git submodule used in\n https://github.com/Pylons/pylons_sphinx_theme to a package. See\n https://github.com/Pylons/pyramid/issues/1614\n\n- Initial commit.",
"bugtrack_url": null,
"license": "BSD-derived (http://www.repoze.org/LICENSE.txt)",
"summary": "Sphinx themes for Pylons Project documentation.",
"version": "1.0.13",
"project_urls": {
"Documentation": "https://github.com/Pylons/pylons-sphinx-themes#pylons-sphinx-themes",
"Homepage": "https://pylonsproject.org",
"Issue Tracker": "https://github.com/Pylons/pylons-sphinx-themes/issues"
},
"split_keywords": [
"pyramid",
"pylons",
"web",
"sphinx",
"documentation"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "498d723d5d3ec0a469f3ebc381990d08dc4bf8932257ccb02ca5883a3fc9d978",
"md5": "13770aecbd941294552da7bbc7e26470",
"sha256": "cbc4061bd2412ae38dc636284275bc3ad431051fb8a0102173aa50cbaac89ea6"
},
"downloads": -1,
"filename": "pylons-sphinx-themes-1.0.13.tar.gz",
"has_sig": false,
"md5_digest": "13770aecbd941294552da7bbc7e26470",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 143056,
"upload_time": "2020-11-30T11:28:25",
"upload_time_iso_8601": "2020-11-30T11:28:25.940834Z",
"url": "https://files.pythonhosted.org/packages/49/8d/723d5d3ec0a469f3ebc381990d08dc4bf8932257ccb02ca5883a3fc9d978/pylons-sphinx-themes-1.0.13.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2020-11-30 11:28:25",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Pylons",
"github_project": "pylons-sphinx-themes#pylons-sphinx-themes",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "pylons-sphinx-themes"
}
JSON
