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

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,

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.

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.

Recommended Posts

Explanation from installation of Sphinx to use of external theme (Bootswatch)
Introduction to Scapy ① (From installation to execution of Scapy)
[Ansible installation procedure] From installation to execution of playbook
From Elasticsearch installation to data entry
How to use SWIG from waf
Summary of how to use pandas.DataFrame.loc
Summary of how to use pyenv-virtualenv
Use Flask to run external files
OpenMPI installation from download to pass-through
Summary of how to use csvkit
Supplement to the explanation of vscode
From the introduction of GoogleCloudPlatform Natural Language API to how to use it
[Python] Summary of how to use pandas
[TF] How to use Tensorboard from Keras
[python] How to use __command__, function explanation
I want to use jar from python
How to calculate Use% of df command
[Python2.7] Summary of how to use unittest
From Attention of Zero Tsuku 2 to Transformer
Jupyter Notebook Basics of how to use
Basics of PyTorch (1) -How to use Tensor-
Flask tutorial (from installation to hello world)
Summary of vtkThreshold (updated from time to time)
Summary of how to use Python list
[Python2.7] Summary of how to use subprocess
How to use TouchDesigner Python's external module
API explanation to touch mastodon from python
[Question] How to use plot_surface of python
I want to get / execute variables / functions / classes of external files from Python