Sphinx

PyTorch など有名ライブラリは sphinx を利用していることが多い。
doxygen よりも良いと思う。色々とできるはず。

nbsphinx とか使えば ipynb をより見やすい感じにできそう。
- デバッグなどの様子を見せるのに使う

始め方

環境構築

色々なやり方がありそう。 conda で環境に入れてしまうのが良さげ。

sudo apt install python3-sphinx

conda install sphinx

pip install -U sphinx

sphinx ファイル作成

リポジトリにドキュメントを追加するときに何から始めるか。

以下のコマンドで対話が始まって自動で作成される。とりあえず build のディレクトリは分ける設定で良さそう？

sphinx-quickstart

対話の詳細 ↓ (クリックで展開可能) <html><details><summary>対話内容</summary><pre>

Sphinx 2.1.2 クイックスタートユーティリティへようこそ。

以下の設定値を入力してください（Enter キーのみ押した場合、かっこで囲まれた値をデフォルト値として受け入れます）。

選択されたルートパス: .

Sphinx 出力用のビルドディレクトリを配置する方法は2つあります。ルートパス内にある “_build” ディレクトリを使うか、ルートパス内に “source” と “build” ディレクトリを分ける方法です。

ソースディレクトリとビルドディレクトリを分ける（y / n） [n]: y

以下の設定値を入力してください（Enter キーのみ押した場合、かっこで囲まれた値をデフォルト値として受け入れます）。

選択されたルートパス: .

Sphinx 出力用のビルドディレクトリを配置する方法は2つあります。ルートパス内にある “_build” ディレクトリを使うか、ルートパス内に “source” と “build” ディレクトリを分ける方法です。

ソースディレクトリとビルドディレクトリを分ける（y / n） [n]: y

プロジェクト名は、ビルドされたドキュメントのいくつかの場所にあります。

プロジェクト名: hogehoge
著者名（複数可）: fugafuga
プロジェクトのリリース []: piyopiyo

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.

プロジェクトの言語 [en]: en

ファイル ./source/conf.py を作成しています。ファイル ./source/index.rst を作成しています。ファイル ./Makefile を作成しています。ファイル ./make.bat を作成しています。

終了：初期ディレクトリ構造が作成されました。

マスターファイル ./source/index.rst を作成して他のドキュメントソースファイルを作成します。次のように Makefile を使ってドキュメントを作成します。 make builder “builder” はサポートされているビルダーの 1 つです。例: html, latex, または linkcheck。 </pre></details></html>

ディレクトリ構成など

sphinx-quickstart で生成されるファイル

実行したディレクトリを . とすると

- ./
    - ./build/
    - ./source/
      - ./source/_static/
      - ./source/_templates/
      - ./source/conf.py
      - ./source/index.rst
    - ./make.bat
    - ./Makefile

となった。

ページの生成 (make html) で生成されるファイル

生成

. で

make html

すればよい。

結果

実行したディレクトリを . とすると

- ./
    - ./build/            : gh-pages を別ブランチで公開するならこれごと .gitignore してよい。
      - ./build/doctrees  : .gitignore しても良い。ビルド時のキャッシュ
      - ./build/html      : gh-pages として公開すれば良いディレクトリ
    - ./source/
      - ./source/_static/
      - ./source/_templates/
      - ./source/conf.py
      - ./source/index.rst
    - ./make.bat
    - ./Makefile

となった。

開発

build/html/ の中で python -m http.server すれば良い。
なので、 build/html/ さえ gh-pages で公開すれば良さそう。
→ github pages は jekyll というソフトで実装されているため相対リンクなどを有効にするために特殊な設定が必要。
→ 拡張機能を入れるべし。

設定の変更など

メモ

github-pages で公開する場合はすべてのファイルを相対リンク？するように拡張機能を入れるのが良さそう。 https://kuma8.hatenablog.jp/entry/20110925/1316937363

拡張機能
- ./source/conf.py の extensions という listオブジェクトの中に以下の文字列を追加。
  特にインストール操作など必要ない。書き込むだけ。
  - “sphinx.ext.githubpages”

メモ2

.. hoge::

みたいな感じで hoge 機能を使える。使える機能としては toctree や index note warning などある。

.. fuga fuga piyo piyo

で単純にコメントを書く。

メモ3

よく使われているテーマ。 https://qiita.com/ganyariya/items/543e5bc55ef0777cbd0c

pip install sphinx-rtd-theme

conf.py

extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.viewcode',
    'sphinx.ext.todo',
    'sphinx.ext.napoleon',
    'sphinx_rtd_theme'
]
html_theme = 'sphinx_rtd_theme'

yuuho.wiki

目次