yuuho.wiki

この文書は読取専用です。文書のソースを閲覧することは可能ですが、変更はできません。もし変更したい場合は管理者に連絡してください。
====== Sphinx ======

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

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

===== 始め方 =====
==== 環境構築 ====

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

<code bash>sudo apt install python3-sphinx</code>

<code bash>conda install sphinx</code>

<code bash>pip install -U sphinx</code>

==== sphinx ファイル作成 ====

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

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

  * 対話の詳細 ↓ (クリックで展開可能) <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 で生成されるファイル ====

実行したディレクトリを ''.'' とすると
<code>
- ./
    - ./build/
    - ./source/
      - ./source/_static/
      - ./source/_templates/
      - ./source/conf.py
      - ./source/index.rst
    - ./make.bat
    - ./Makefile
</code>
となった。

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

=== 生成 ===
''.'' で <code bash>make html</code> すればよい。

=== 結果 ===
実行したディレクトリを ''.'' とすると
<code>
- ./
    - ./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
</code>
となった。

===== 開発 =====

''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 ===

<code>
.. hoge::
</code>
みたいな感じで hoge 機能を使える。
使える機能としては ''toctree'' や ''index'' ''note'' ''warning'' などある。
<code>
.. fuga fuga piyo piyo
</code>
で単純にコメントを書く。

=== メモ3 ===

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

<code bash>pip install sphinx-rtd-theme</code>

<code python conf.py>
extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.viewcode',
    'sphinx.ext.todo',
    'sphinx.ext.napoleon',
    'sphinx_rtd_theme'
]
html_theme = 'sphinx_rtd_theme'
</code>