Pylons/pylons-sphinx-themes

Name: pylons-sphinx-themes

Owner: Pylons Project

Description: Sphinx themes for projects under the Pylons Project, but in a Python package instead of git submodule.

Created: 2015-04-14 16:34:59.0

Updated: 2017-04-18 21:01:08.0

Pushed: 2017-09-22 20:48:37.0

Homepage:

Size: 165

Language: CSS

GitHub Committers

User	Most Recent Commit	# Commits

Other Committers

User	Email	Most Recent Commit	# Commits

README

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.

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

   rt pylons_sphinx_themes
   

2. Activate the theme.

   _theme = 'pyramid'
   _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.

   d and use Pylons theme
   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.

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

   your_project_directory>
   rm .gitmodules
   

2. Deinitialize the submodule.

   ocs/_themes
   submodule deinit .
   

3. Remove the submodule's directory.

   .
   rm _themes/
   

4. Edit your Sphinx's Makefile. The following is an example diff from Pyramid.

   l: themes
   l:
   .
   lhelp: themes
   lhelp:
   
   mes:
    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.

_extras = [
'Sphinx >= 1.3.1',
'docutils',
'repoze.sphinx.autointerface',
'pylons_sphinx_latesturl',
'pylons-sphinx-themes',
]

.

as_require = {
'testing':testing_extras,
'docs':docs_extras,
},

Otherwise you can repeat yourself and edit your tox.ini. The following example is from waitress.

 =
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:

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

[docs]

Available themes

• pylons - the generic Pylons Project documentation theme
• pyramid - the specific Pyramid documentation theme
• pylonsfw - the specific Pylons Framework documentation theme