目次

makeコマンドを使ったり，pipだったりする方法が検索すると引っかかるが，出力されるファイル構成が変わったりしてうまくいかなかったので，自分の環境でのやり方をメモする．

sw_vers
ProductName:	macOS
ProductVersion:	11.5.1
BuildVersion:	20G80

python==3.7.10
sphinx==4.1.2


環境構築 (Python)

conda install sphinx sphinx_rtd_theme

もちろん別々にインストールすることもできる．

conda install sphinx            # sphinx系コマンドが使えるようになる
conda install sphinx_rtd_theme  # sphinxのテーマを使えるようにする．

html作成の作業ディレクトリを作成

docs_srcという作業用のディレクトリを作成．

sphinx-quickstart docs_src

質問されるので答える．（必須）

すると，docs_srcというディレクトリが生成され，その中に様々なファイルが作成される．これを編集していく必要がある．

conf.pyを編集

パスを通す．

docs_src/source/conf.pyを編集する．

# import os
# import sys
# sys.path.insert(0, os.path.abspath('.'))

とコメントアウトされている部分があるので，これをプロジェクトのルートディレクトリになるようにパスを変えてアンコメント．自分の場合では以下．

import os
import sys
sys.path.insert(0, os.path.abspath('../..'))    # project_name/docs_src/srouce/conf.py だから．

拡張機能を加える．

extensions = [
]

となっている部分に拡張機能の名前を指定する．

extensions = [
    'sphinx.ext.autodoc',       # docstringからドキュメントを作成してくれる．
    'sphinx.ext.napoleon',      # google式・numpy式docstringを整形してくれる．
    'sphinx.ext.githubpages'    # github-pages用のファイルを生成してくれる．
]
  • autodocの使い方
    • クラスの場合，__init__はデフォルトではドキュメントに入らないので，:special-members: __init__を追加してあげるとドキュメントに入るようになる．

versionを自動で取得できるようにする．

最初の質問で聞かれたversionが文字列で入力されている．これを自動で取得できるようにする．

release = "v1.0.0"

これはおそらく__init__.pyのなかで__version__を指定しているため，これでできる．PyPI登録を前提．

from XXX import __version__
release = __version__

テーマを変更する．

html_theme = 'alabaster'

今回はこれを以下に変更した．（conda install xxxでインストールしたやつ）

html_theme = 'sphinx_rtd_theme'

標準テーマはここで確認できる．（公式ドキュメント）

ファイルを生成

.rstファイルの生成

sphinx-apidoc -f -o ./docs_src/source .

modules.rstを書き換え

index.rstを書き換える．

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

modules.rstが生成されているのでそれを読み込む，みたいな意味．
:numbered:は，章にナンバリングするかどうか．

.. toctree::
   :maxdepth: 4
   :caption: Contents:
   :numbered:

   modules.rst

rstをhtmlに変換

docsディレクトリにhtmlやcss，javascriptを生成．

sphinx-build -b html ./docs_src/source ./docs

生成されたindex.htmlをブラウザで開けばきちんとできているか確認できる．

あとはGithub-pagesで公開するだけ．

Markdownで文章を付け足す．

環境構築

必要なパッケージをインストール．

conda install recommonmark sphinx-markdown-tables

commonmarkを明示してインストールしているサイトもあるが，少なくともcondaにおいては，recommonmarkをインストールする時のrequirementsに入っているようで同時にインストールされる．

conf.pyのextensionをさらに追加して，

extensions = [
   'sphinx.ext.autodoc',       # docstringからドキュメントを作成してくれる．
   'sphinx.ext.napoleon',      # google式・numpy式docstringを整形してくれる．
   'sphinx.ext.githubpages',   # github-pages用のファイルを生成してくれる．
   'recommonmark',             # markdownで書けるようにする．
   'sphinx_markdown_tables',   # markdownの表を書けるようにする．
]

markdownも読んで，みたいな意味のコードをconf.pyに追加．

# markdown
source_suffix = ['.rst', '.md']
source_parsers = {
   '.md': 'recommonmark.parser.CommonMarkParser',
}

これでOK.

調べていると，こうやって↓書くやり方もあるみたいだけどどちらが推奨なのかは不明．importのパス的に文字列で指定しているかオブジェクトを指定しているかの違いだけな気がする．

source_suffix = ['.rst', '.md']

from recommonmark.parser import CommonMarkParser

source_parsers = {
    '.md': CommonMarkParser,
}

試しに，index.rstと同じ階層に何か適当なMarkdownファイルを作成して，

.. toctree::
   :maxdepth: 4
   :caption: Contents:
   :numbered:

   modules.rst
   XXX.md

ってすれば追加される．

このときの注意点は，見出しを一つでもつけること．
Markdownファイル内に見出しが一つもないと「tocを生成できません！」って怒られる．

あとは，

sphinx-build -b html ./docs_src/source ./docs

をすれば，htmlに変換してくれる．編集した後もこの繰り返し．

本当は同じ階層に作らなくてもできるみたい．けど，そんな巨大なプロジェクトのドキュメントを作るわけでもないし，パスの整理が大変だったりするので，これでいいかなと思う．

調子に乗ってmarkdownをindex.rstの中でincludeしようとするとmarkdownとして認識してくれない．
あくまで，toctreeの中でしかうまく変換してくれないみたい．なので，自分は以下のコードを追加して，ビルドのたびにREADME.mdをコピーするスクリプトを追加した．

from shutil import copyfile
fname_readme = 'README.md'
path_readme = os.path.join(os.path.abspath('../..'), 'README.md')
if os.path.isfile(path_readme):
    copyfile(path_readme, fname_readme)
else:
    print(path_readme)

こうすれば，読み込みたいところで，

.. toctree::
   :maxdepth: 4

   README.md

と書けばOK．もちろん他のtoctreeにREADME.mdの記述を追加するのみでもできた．

コメント

こういう自動化のインフラが整っていることが本当にすごいと思って，感動しっぱなしだった．
rstの記法も覚えた方が良さそうな気もして，Markdownの機能を入れるか悩んだが，覚えなくてはならなくならない限りは覚えられないと思うので無理せずmarkdownで書くことにした．

これ以上高度なことは望まない方が沼にハマらないのでいいのではないかとすら思うくらいやれることがたくさんある，おもしろいものだと思う．

やりたいこととしては，docstring内にテストを書いて，云々のようなものがあるはずなので，それを使いこなせばよりdocumentationも充実するし，楽にパッケージ管理ができると思うので試してみたい．

参考