Sphinx theme for documentation sites

Sphinx is commonly used for documentation sites, but there is a lack of simple and elegant themes. This small theme tries to fix that through a minimalist approach, offering a great way to build a small documentation without great expectations that distract from the site’s actual use: documenting a project.

Features

The main features offered by the theme are:

Minimalist and reactive look
HTML5
Bootstrap 3
Font Awesome icons
Prepared for Facebook’s Open Graph and Twitter Cards

Acquiring the project

The project files are hosted on Pypi, allowing them to be acquired with pip.

For this, just use the following command:

$ pip install sphinx-docs-theme

Usage

This project is meant to be used with a Sphinx project, as it is a UI theme for it.

There are two ways to apply the theme, which are nearly the same. It can be installed in the local repository and then be used as a dependency, or the project code (the ‘sphinx_docs_theme’ folder) can be copied to the Sphinx project themes folder.

Setting up the theme

Using it as a dependency

If the project has been installed in the local libraries repository, it can be used just by adding the following lines to the conf.py file of any Sphinx project:

import sphinx_docs_theme

html_theme = 'sphinx_docs_theme'
html_theme_path = sphinx_docs_theme.get_html_theme_path()

Using it from the Sphinx themes folder

Another possibility is just adding the project code, contained int the ‘sphinx_docs_theme’ folder, to the themes folder of your Sphinx project, which is:

docs\_themes\

And then it is just needed to add the following files to the conf.py file:

html_theme = 'sphinx_docs_theme'
html_theme_path = ["_themes", ]

Theme variables

After setting up the theme the theme variables should be configured. To find more about them check the configuration section.

Theme configuration

The theme includes a series of variables which can be configured to adapt the data shown.

Actually for the theme to work as expected, showing the project’s full data, it is recommended filling up as much information as possible.

The data is added to the ‘html_theme_options’ map variable on the Sphinx project ‘conf.py’ file. As these are theme options they are also stored on the ‘theme.conf’ file.

Links

Variable	Usage
general_info_links	List of links to show on the general info column in the folder.
navbar_links	Map of links to generate the navbar menu.

How are the links lists built?

The links list and map follow a simple structure where each link is a tuple made up of a name and a URL, just as follows:

('Usage', './usage.html')

These are given to the theme’s configuration on the ‘conf.py’ file of the Sphinx project, and as such a list of links would be like this:

'general_info_links': [('Acquire', './acquire.html'),
                       ('Usage', './usage.html')]

The map in similar way is just a list of tuples, containing a name and a list of links:

'navbar_links': [('Documentation', [('Acquire', './acquire.html'),
                 ('Usage', './usage.html'),
                 ('Configuration', './configuration.html')])]

Metadata variables

Variable	Usage	Example
keywords	Content for the keywords field on the header	‘Sphinx, theme, Bootstrap, documentation’
twitter_id	Id for the twitter card on the header	'@BernardoMartG‘

Author info

Variable	Usage
author_name	The author to show on the footer
author_url	Webpage for the shown author

Release info

Variable	Usage	Example
years	The years range in which the project was published, as a string	‘2014-2015’
publish_date	Date in which the Sphinx-created page has been published	datetime.datetime.now().date()
license_name	Name of the license under which the project has been released	‘MIT’
license_url	URL for the license	‘http://www.opensource.org/licenses/mit-license.php‘

Repositories info

Variable	Usage
scm_name	Name of the source code repository being used
scm_url	URL for the source code repository being used
ci_name	Name of the source continuous integration service being used
ci_url	URL for the source continuous integration service being used
issues_name	Name of the issues service being used
issues_url	URL for the issues integration service being used
releases_repos	List of releases repositories containing the project. It is a list of tuples containing the name and URL for each repository.

How are the releases repositories links lists built?

Just like he previously mentioned links list:

'releases_repos': [('Pypi', 'https://pypi.python.org/pypi/sphinx-docs-theme')]