Sphinxを使ってドキュメント整理

ドキュメント整理

ドキュメントを整理するのにSphinxが良さそうだったので、インストールからビルドまでの流れを紹介する

Sphinxを使用する

Pythonのモジュールのドキュメントでも使用されていることが多く、そのドキュメントもきれいだったためSphinxを使用する

インストール

pip install sphinx

バージョンを確認してインストールされているかを確認する

sphinx-quickstart --version

プロジェクトの作成

まずはdocs_sphinxという作業ディレクトリを作成し、このディレクトリ上で作業していく

mkdir docs_sphinx
cd docs_sphinx

作業ディレクトリに移動した後、sphinx-quickstart xxxを実行する。xxxというプロジェクトを作成している。対話式で質問されるため、それぞれ回答していく

ドキュメントのテンプレートを作成

以下を実行して成功すると、_build配下にhtml/index.htmlが作成されるため、それをブラウザで開く

./make html

「Welcome to xxx's documentation!」が表示されれば成功

テンプレートをオリジナルにしていく

テンプレートを確認した後、自分のものとして編集していくにはdocs_sphinx/xxx配下にあるindex.rstを編集していけばよい

docstringを反映させる

docs_sphinx/xxx配下にあるconf.pyを修正する

以下を追記すればよい。os.path.abspath(__file__)の__file__の中にはconf.pyからみてdocstringを表示したいディレクトリへのパスを記載する

import os
import sys
sys.path.insert(0, os.path.abspath(__file__))

また、docstringを読み込むために拡張機能を設定する。conf.pyに以下を追加する

extensions = ['sphinx.ext.autodoc', 'sphinx.ext.napoleon']

pythonファイルからrstファイルの作成

pythonファイルをrstファイルに変換することでpythonファイルに書いたdocstringを反映することができる

sphinx-apidoc -e -f -o <ouput dir> <modules dir>

• <output dir>には、pythonファイルからrstファイルに変換した際に作成されるrstファイルを格納するディレクトリパスを入力する
• <modules dir>には、rstファイルに変換したいpythonファイルがあるディレクトリパスを入力する

index.rstを編集していく

toctreeの部分に/src/test/testpyを追加すると、その部分にdocstringが反映される

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

   /src/test/testpy

ビルド

ビルドしてhtmlで出力する。以下のどちらか、もしくは両方実行すればよい。./make htmlの場合はリンクを追っていく形式で出力されるが、./make singlehtmlの場合は単一ページで出力される。こだわりに合わせて使用すればよい

./make html

or

./make singlehtml

Appendix

テーマを変える

pip install sphinx_rtd_theme

を実行した後、conf.pyのhtml_themeの部分を

html = "sphinx_rtd_theme

とするとテーマを変えることができる。上記は一例であり、他にもさまざまなテーマがある。テーマについては「https://sphinx-themes.org/」が参考になる

数式の反映

数式を反映させるために以下のconf.pyを作成した。TeX記法で数式を書く人は参考になると思う

conf.py

# Configuration file for the Sphinx documentation builder.
#
# For the full list of built-in configuration values, see the documentation:
# https://www.sphinx-doc.org/en/master/usage/configuration.html

import os
import sys

# srcフォルダにあるpyファイル（関数など）を読み込むために以下を設定する
sys.path.insert(0, os.path.abspath("../src/"))

# -- Project information -----------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information

project = 'Your project'
copyright = 'Your copyright'
author = 'Author'

# -- General configuration ---------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration

extensions = [
    'sphinx.ext.autodoc', 
    'sphinx.ext.viewcode',
    'sphinx.ext.napoleon',
    'myst_parser',
    'sphinx.ext.imgmath',
    'sphinx.ext.mathjax',
    'sphinx_math_dollar',
    ]

mathjax_path = 'https://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML'

mathjax_config = {
    'TeX': {'equationNumbers': {'autoNumber': 'AMS'}},
    'extensions': ['tex2jax.js'],
    'jax': ['input/TeX', 'output/HTML-CSS'],
    'HTML-CSS': {'availableFonts': ['TeX'], 'preferredFont': 'TeX', 'webFont': 'TeX'},
}

templates_path = ['_templates']
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']

language = 'ja'

html_theme = 'sphinx_rtd_theme'
html_static_path = ['_static']

source_suffix = {
    '.rst': 'restructuredtext',
    '.txt': 'markdown',
    '.md': 'markdown',
}

myst_enable_extensions = [
    "dollarmath", 
    "amsmath", 
    "smartquotes",
    ]

imgmath_image_format = 'svg'
imgmath_font_size = 14
imgmath_latex_preamble = r'''
    \usepackage{amsmath}
    \usepackage{mathtools}
'''

html_use_mathjax = True
imgmath_use_preview = False