[PYTHON] Explanation from installation of Sphinx to use of external theme (Bootswatch)

This article is about the Python module "Sphinx"

--How to install --How to create a project --How to change the standard theme --How to change the external theme (Bootswatch)

I will explain about.

Please see the following site for detailed explanations about Sphinx. Sphinx Japan User Association

usage environment

• Mac OSX El Capitan
• Python3.5.1
• VirtualEnv

This time I created and installed a virtual environment, This step is not necessary unless you use your own virtual environment module or are particular about it.

Installation method

Create a virtual environment in any location and start it.

$ mkdir Sphinx
$ virtualenv --no-site-packages Sphinx
$ cd Sphinx
$ source bin/activate
(Sphinx)$ 

Then install the Sphinx module using pip.

(Sphinx)$ pip install sphinx

At this point, the Sphinx installation is complete.

Project creation

Create a folder dedicated to the project in any location and Execute the sphinx-quickstart command in it.

(Sphinx)$ mkdir MyProject
(Sphinx)$ cd MyProject
(Sphinx)$ sphinx-quickstart

When I run the command, I'm asked about all the options, but if I press the basic Enter key, it's okay,

• ProjectName
• Author Name
• Version

Only three items are required to be entered, so enter them appropriately. There is one item language setting, but if you want to use Japanese, enter ja to continue.

After project creation is completed

(Sphinx)$ make html

Will generate HTML in _build / html in the current directory. If you view _build / html / index.html in your browser, you can see that the document has been generated.

Change standard theme

Settings related to theme change are in the project folder (MyProject this time) Do it in conf.py.

conf.py

html_theme = 'default'

You can change the standard theme by changing the character string part of.

Don't forget after the change

(Sphinx)$ make html

Let's do.

There are nine standard themes as follows.

• default
• basic
• sphinxdoc
• scrolls
• agogo
• nature
• pyramid
• haiku
• traditional
• epub

The standard theme images that can be used are posted on the following site. Standard theme collection

Use of external themes

You can also use external themes with Sphinx. This time, I will explain using the Bootswatch theme. Bootswatch

・ Installation of Bootswatch Continue to work in the virtual environment.

(Sphinx)$ pip install shpinx_bootstrap_theme

· Bootswatch theme settings for Sphinx This is also set in conf.py in the project folder.

First of all, import the module in the first line of conf.py. Please be careful not to comment.

conf.py

import sphinx_bootstrap_theme

Continue to the directory where the theme is stored And set the theme name.

conf.py

html_theme = 'bootstrap'
html_theme_path = ['../lib/python3.5/site-packages/sphinx_bootstrap_theme']

~~ The official Bootwatch documentation stated that a dedicated function was provided for setting html_theme_path, but since an error occurred in my environment, it is described as a relative path to the module ~~

** Addendum: pointed out by yuntas ** It seems to be solved by uncommenting the following in conf.py.

conf.py

import os
import sys
sys.path.insert(0, os.path.abspath('.'))

...

html_theme_path = sphinx_bootstrap_theme.get_html_theme_path()

Then specify which Bootwatch theme to use, just below the code above. Click here for the types of themes. Bootswatch

conf.py

html_theme_options = {'bootswatch_theme': "cosmo"}

Don't forget this after the change

(Sphinx)$ make html

Let's do.

This completes the setting of the external theme.