Sphinxを使って簡単なドキュメントを作成してみました。
SphinxはreSTというマークアップ言語を利用して、HTML、PDFなどのドキュメントをジェネレートできるプログラムです。
論文を書くときに利用する、Texぽい感じでした。
今回利用した環境は以下です。
- macOS Big Sur 11.2
- sphinx 3.4.3
- pip3 19.2.3
sphinxのインストール
# pip3 install sphinx
sphinxプロジェクトの作成
% sphinx-quickstart
Sphinx 3.4.3 クイックスタートユーティリティへようこそ。
以下の設定値を入力してください（Enter キーのみ押した場合、
かっこで囲まれた値をデフォルト値として受け入れます）。
選択されたルートパス: .
Sphinx 出力用のビルドディレクトリを配置する方法は2つあります。
ルートパス内にある "_build" ディレクトリを使うか、
ルートパス内に "source" と "build" ディレクトリを分ける方法です。
> ソースディレクトリとビルドディレクトリを分ける（y / n） [n]: y
プロジェクト名は、ビルドされたドキュメントのいくつかの場所にあります。
> プロジェクト名: TEST
> 著者名（複数可）: Araya
> プロジェクトのリリース []: 0.0.1
ドキュメントを英語以外の言語で書く場合は、
言語コードで言語を選択できます。Sphinx は生成したテキストをその言語に翻訳します。
サポートされているコードのリストについては、
https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language を参照してください。
> プロジェクトの言語 [en]: ja
ファイル /Users/araya/Desktop/work/source/conf.py を作成しています。
ファイル /Users/araya/Desktop/work/source/index.rst を作成しています。
ファイル /Users/araya/Desktop/work/Makefile を作成しています。
ファイル /Users/araya/Desktop/work/make.bat を作成しています。
終了：初期ディレクトリ構造が作成されました。
マスターファイル /Users/araya/Desktop/work/source/index.rst を作成して
他のドキュメントソースファイルを作成します。次のように Makefile を使ってドキュメントを作成します。
make builder
"builder" はサポートされているビルダーの 1 つです。 例: html, latex, または linkcheck
以下のようなファイル構成でプロジェクト学生されました。
% tree
.
├── Makefile
├── build
├── make.bat
└── source
├── _static
├── _templates
├── conf.py
└── index.rst
HTMLドキュメントのジェネレート
% make html
% open ./build/html/index.html
ブラウザで開くと以下のようになります。
 |
|---|
PDFドキュメントのジェネレート
$ make latexpdf
$ open build/latex/test.pdf
プレビューで開くと以下のようになります。
作成できるドキュメントの種類
こちらにまとまっていました。
https://www.sphinx-doc.org/ja/master/man/sphinx-build.html
プレインテキストやXMLなどいろいろありますね。