Sphinxを使ったHTMLドキュメント作成

※記事内に商品プロモーションを含むことがあります。

はじめに

ドキュメント生成ツールSphinxを導入し、HTMLファイルを生成するまでの方法をまとめました。

SphinxはPython上で実行できるツールであり、reStructuredText (reST) という形式のテキストファイルからHTMLやPDFなどのドキュメントを作成できます。HTMLファイルを生成できるため、静的サイト公開サービス（Cloudflare PagesやNetlifyなど）を利用して、ウェブサイトを無料で公開できます。

また、この記事では触れませんが、Sphinxの拡張機能を用いることで、Markdownファイルの変換、MathJaxによる数式の記述、Mermaidによるグラフ生成なども可能です。

この記事では、Sphinxのインストール、プロジェクトテンプレートの作成、HTMLファイルの生成について解説します。

リンク

環境

OSはWindows 10 Home Ver. 21H1です。

Python v3.9.7
Sphinx v4.2.0

Sphinxのインストール

Pythonは既にインストールされているものとして、Sphinxパッケージをインストールします。

Conda環境では以下を実行します。-c anacondaによって、パッケージの検索先をanacondaのチャンネルに指定します。

1

conda install -c anaconda sphinx

pipの場合は以下を実行します。

1

pip install sphinx

プロジェクトテンプレートの作成

適当な空フォルダを作成し、その中でPowerShellを起動します（エクスプローラ上でshiftキーを押しながら右クリック→「PowerShellウィンドウをここで開く」）。次に、sphinx-quickstartというコマンドを実行します。このコマンドは対話形式でSphinxプロジェクトのテンプレートを作成するものです。

> sphinx-quickstart
Welcome to the Sphinx 4.2.0 quickstart utility.

Please enter values for the following settings (just press Enter to
accept a default value, if one is given in brackets).

Selected root path: .

You have two options for placing the build directory for Sphinx output.
Either, you use a directory "_build" within the root path, or you separate
"source" and "build" directories within the root path.
> Separate source and build directories (y/n) [n]:

ソースとビルド結果のフォルダを分離するか確認されます。分離しない場合、分離した場合のそれぞれのフォルダ構造を以下に示します。

分離しない場合

root/
├── _build/
├── _static/
├── _templates/
├── conf.py
├── index.rst
├── make.bat
└── Makefile

分離した場合

root/
├── build/
├── source/
|   ├── _static/
|   ├── _templates/
|   ├── conf.py
|   └── index.rst
├── make.bat
└── Makefile

分離した場合、sourceというフォルダが作られ、ソースファイルはその中で管理します。そのため、ルートフォルダをすっきりとさせることができます。

ここではフォルダを分離することにしますので、yと入力します。

> Separate source and build directories (y/n) [n]: y

The project name will occur in several places in the built documentation.
> Project name: MyDoc
> Author name(s): Helve
> Project release []: 1.0.0

If the documents are to be written in a language other than English,
you can select a language here by its language code. Sphinx will then
translate text that it generates into that language.

For a list of supported codes, see
https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language.
> Project language [en]: ja

続いて、プロジェクトの名前、著者名、プロジェクトのバージョン、言語を入力します。日本語の場合はjaとします。

以上でドキュメントのテンプレートが生成されました。

HTMLファイルの生成

続いて、HTMLファイルを生成します。
テンプレートにはindex.rstというReSTファイルがあるので、これをHTMLに変換します。

Windowsの場合、.\make.bat htmlというコマンドを実行します。これは、make.batというバッチファイルにhtmlという引数を与えて実行することを意味します。

> .\make.bat html
Running Sphinx v4.2.0
loading translations [ja]... done
making output directory... done
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 1 source files that are out of date
updating environment: [new config] 1 added, 0 changed, 0 removed
reading sources... [100%] index
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] index
generating indices... genindex done
writing additional pages... search done
copying static files... done
copying extra files... done
dumping search index in Japanese (code: ja)... done
dumping object inventory... done
build succeeded.

The HTML pages are in build\html.

実行すると、build/html/フォルダにHTMLファイルが出力されます。index.htmlをウェブブラウザで開いてみます。

index.html

サイトのタイトルやフッターの著者名に、sphinx-quickstartで設定した項目が反映されています。

参考

sphinx でドキュメント作成からWeb公開までをやってみた - Qiita