Sphinx themes for Pylons Project documentation.
Project description
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
Add pylons-sphinx-themes to your project’s requirements in its setup.py. Here’s an example from Pyramid.
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.
import pylons_sphinx_themes
Activate the theme.
html_theme = 'pyramid' html_theme_path = pylons_sphinx_themes.get_html_themes_path()
(Recommended) Enable Ethical Ads. Doing so supports the Python Software Foundation with ad revenue.
# 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.
# 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.
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.
cd <your_project_directory> git rm .gitmodules
Deinitialize the submodule.
cd docs/_themes git submodule deinit .
Remove the submodule’s directory.
cd .. git rm _themes/
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.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.
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.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.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Hashes for pylons-sphinx-themes-1.0.9.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | b2cc0771dc28e959e1b0789d09c8c9d0ee3549f32683b49af405ae21c1a65642 |
|
MD5 | 15cb8a7c9a294f15ba3b15805a7dcae8 |
|
BLAKE2b-256 | bd7a8d63f24000d58c60c251c2235aba888b7ce164eb1b3e5317ebd7fb50765b |