はじめに

a. 本記事の目的

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

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

b. 動作確認環境

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

# Python
% python --version
Python 3.7.6

手順

1. プロジェクトの作成

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

% mkdir sample_docs && cd sample_docs

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

% pip install sphinx sphinx-rtd-theme sphinx_fontawesome

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

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

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

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

# 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 を編集する。
以降、「ルートインデックス」と呼ぶ。

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 を編集する。ルートインデックスから参照されている必要がある。
以降、「章インデックス」と呼ぶ。

contents/sample_content/chapter01/index.rst

Chapter01
============================================================

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

   section01

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

contents/sample_content/chapter01/section01.md

# Titele of "section01"

contents

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

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

通常ビルド

% make html

自動ビルド

% make livehtml

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