[PYTHON] Get started with the documentation tool Sphinx

Introduction

Explain in this entry

--From the introduction of the Python document creation tool "Sphinx" to simple document generation --Installation and usage of the hot reload module "sphinx-autobuild" --How to change the theme

Not explained in this entry

--How to install python3 and pip --Detailed description of reStructuredText --Comparison with other documentation tools like MkDocs --Detailed options of Sphinx, etc.

Premise

--Installing python3 system

Writer's environment

• macOS Catalina 10.15.3
• Python 3.7.4

Create a virtual environment for Sphinx with venv

Create a virtual environment directory for Sphinx. Directory name is arbitrary

$ mkdir sphinx

Go to the directory you created and create a virtual environment The virtual environment name is sphinx-venv here.

$ cd sphinx
# 「python3 -You can create a virtual environment by using "m venv virtual environment name".
$ python3 -m venv sphinx-venv

Go to the virtual environment directory and enable the virtual environment

$ cd sphinx-venv
$ source bin/acitvate

Install sphinx with pip

$ pip install sphinx

Create a sphinx project

When you hit sphinx-quickstart, you'll hear a sloppy message and you'll be asked a few interactively. If you are not particular about it for the time being, you can set it as follows.

$ sphinx-quickstart
>Separate source directory and build directory (y/ n） [n]:y
>Project name: test-project
>Author name (s): test-author
>Project release[]: 1.0.0
>Project language[en]: ja

In my execution environment, I was asked in Japanese as above, Depending on the environment, you will be asked in English as follows.

$ sphinx-quickstart
> Separate source and build directories (y/N) [n]:y
> Project name: test-project
> Author name(s): test-author
> Project version []: 1.0.0
> Project language [en]: ja

Generate html file

First, generate an html file in the default state. To generate an html file, type the following command where the Makefile is located

$ make html

This will generate a file called index.html under the build directory. Please display it with any browser.

Add content

In Sphinx, to add content,

--Create a new file and --Register on the top page

is needed.

Create a new file

Create a file with an appropriate name under "source". Here, the file name is "test.rst".

Write the contents appropriately.

test.rst

===================
Put the title here
===================

Put a big headline
---------------
-It's a bullet point
-It's a bullet point

Register on the top page

"Index.rst" under "source" is the top page. Edit this file and register the "test.rst" created earlier. For editing, add the same name as the file name as shown below.

index.rst (before editing)

.. toctree::
   :maxdepth: 2
   :caption: Contents:

index.rst (after editing)

.. toctree::
   :maxdepth: 2
   :caption: Contents:

   test

Now, if you execute "make html" again, you will see the top page. "Put a title here" will be displayed with a link. If you click this link, you can see the contents described in test.rst.

[Bonus] Allow hot reload

In Sphinx, you usually have to edit the document and then type "make html" to reload the browser. This is awkward, so when you edit the document, it will automatically generate an html file so that it will be reloaded automatically.

$ pip install sphinx-autobuild

After installation, type the following command in the directory where "Makefile" is located.

# sphinx-autobuild [xxx.Directory with rst] [Directory where html files are generated]
#In this entry, it looks like this:
$ sphinx-autobuild source build

Then, the server will start locally, so if you display the URL (http : // localhost: 8080) with a browser, you can view the created html file.

[Bonus] Change the theme

There is the following description at the bottom of "conf.py" under the "source" directory.

conf.py

html_theme = 'alabaster'

You can change the theme by rewriting'alabaster'. Note that'alabaster'is the default theme.

The following standard themes are available in Sphix.

• alabaster
• default
• sphinxdoc
• scrolls
• agogo
• nature
• pyramid
• haiku
• traditional
• bizstyle

You can also set a third-party theme. For example, if you want to set the theme of Material Design, install the theme as follows.

$ pip install sphinx-theme-material

After installing the theme, set conf.py as follows: After setting, the theme has changed to Material Design.

conf.py

html_theme = 'material'