Sphinx ドキュメンテーション開発


# はじめに

## a. 本記事の目的

* Sphinx ドキュメント開発の手順を示す。
* 階層構造情報を reStructuredText で記述し、ドキュメント本文は Markdown で執筆する方針とする。
* 手順実施後のディレクトリ構成は以下の通り。

```sh
sample_docs/
├── Makefile
├── _build
├── _static
├── _templates
├── conf.py
├── index.rst
└── contents
   └── sample_content 
        └── chapter01
             ├── index.rst
             └── section01.md
```

## b. 動作確認環境

```sh
# OS
% sw_vers 
ProductName:    macOS
ProductVersion: 12.0.1
BuildVersion:   21A559

# Python
% python --version
Python 3.7.6
```


# 手順

## 1. プロジェクトの作成

適当なディレクトリを作成する。

```sh
% mkdir sample_docs && cd sample_docs
```

必要な Python ライブラリをインストールする。

```
% pip install sphinx sphinx-rtd-theme sphinx_fontawesome
```

Sphinx プロジェクトを作成する。

```sh
% sphinx-quickstart \
    --no-sep \
    --project="sample docs" \
    --author="roki18d" \
    --v 0.1 \
    --release=0.1 \
    --language=en \
    --no-batchfile
```

## 2. 設定ファイル等の編集

```python:conf.py
# Configuration file for the Sphinx documentation builder.

# -- Path setup --------------------------------------------------------------
# import os
# import sys
# sys.path.insert(0, os.path.abspath('.'))
import sphinx_rtd_theme
import sphinx_fontawesome

# -- Project information -----------------------------------------------------
project = 'sample docs'
copyright = '2022, roki18d'
author = 'roki18d'
version = '0.1'
release = '0.1'

# -- General configuration ---------------------------------------------------
extensions = [
    'sphinx.ext.autodoc', 
    'sphinx.ext.napoleon', 
    'sphinx_rtd_theme', 
    'sphinx_fontawesome', 
    'myst_parser', 
]
source_suffix = {
    '.rst': 'restructuredtext',
    '.md': 'markdown',
}
templates_path = ['_templates']
language = 'ja'
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']

# -- Options for HTML output -------------------------------------------------
html_theme = "sphinx_rtd_theme"
html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
html_show_sourcelink = False
html_static_path = ['_static']
```

```Makefile:Makefile
# Minimal makefile for Sphinx documentation
#

# You can set these variables from the command line, and also
# from the environment for the first two.
SPHINXOPTS    ?=
SPHINXBUILD   ?= sphinx-build
SOURCEDIR     = .
BUILDDIR      = _build

# Put it first so that "make" without argument is like "make help".
help:
	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

.PHONY: help Makefile

# Catch-all target: route all unknown targets to Sphinx using the new
# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
%: Makefile
	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

livehtml:
	sphinx-autobuild "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

```

## 3. ドキュメントソースの開発

ドキュメント全体の起点となる `index.rst` を編集する。
以降、「ルートインデックス」と呼ぶ。

```rst:index.rst
sample docs
============================================================

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

   contents/sample_content/chapter01/index.rst
```

ドキュメントソースのリソースを作成する。

```
$ mkdir -p contents/sample_content/chapter01
$ touch contents/sample_content/chapter01/index.rst
$ touch contents/sample_content/chapter01/section01.md
```

章ごとに `index.rst` を編集する。ルートインデックスから参照されている必要がある。
以降、「章インデックス」と呼ぶ。

```rst:contents/sample_content/chapter01/index.rst
Chapter01
============================================================

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

   section01
```

節にあたる Markdown ファイルを編集する。章インデックスから参照されている必要がある。

```markdown:contents/sample_content/chapter01/section01.md
# Titele of "section01"

contents
```

ルートインデックスから参照関係をたどることができれば、より深い階層構造を作成することも可能である。

## 4. ドキュメントソースのビルド

**通常ビルド**

```sh
% make html
```

**自動ビルド**

```sh
% make livehtml
```