Documentation

Python製のドキュメント生成ツール。 Python 3.8.5 Sphinx 3.4.2 Sphinx · PyPI pip3 install Sphinx reST（reStructuredText） SphinxではデフォルトでreStructuredTextというマークアップ言語を使う。 https://www.sphinx-doc.org/ja/master/usage/restructuredtext/basics.html https://atom.io/packages/language-restructuredtext 既存Pythonプロジェクトにドキュメントを追加する setup.py などが存在するPyPIパッケージプロジェクトを想定する。 プロジェクトのルートに docs ディレクトリを作成し、 インタラクティブツール sphinx-quickstart を実行する。 mkdir docs cd docs/ sphinx-quickstart Separate source and build directories (y/n) と聞かれるので、 y 。 プロジェクト名、著者名、言語などを答える。 source ディレクトリ、 build ディレクトリ、 Makefile が生成される。 make html 以上のコマンドで build/html ディレクトリにHTMLが生成される。 python3 -m http.server -b localhost -d build/html などで確認する。 次はPythonモジュールのdocstringからドキュメントを自動生成する。 Sphinx でPythonのAPIドキュメントを自動作成 - Qiita python書くなら絶対に使いたい2つのドキュメント生成ツール - Qiita #!/bin/bash SCRIPT_DIR=$(cd $(dirname $0); pwd) cd "${SCRIPT_DIR}" sphinx-apidoc -f -o "./source/api" "../mymodule" make html docs/mkdocs.sh を以上のように作成し、実行する（TODO：Makefileへの入れ込み）。 ここでは、以下のように docs ディレクトリと並んで、パッケージとして提供するPythonモジュール mymodule のディレクトリがあることを想定している。 なお、 docs/source/conf.py は設定ファイルであり、 例えば html_theme = 'sphinx_rtd_theme' のような設定を追加し、 pip3 install sphinx-rtd-theme してから make html することで、Read the Docsスタイルのドキュメントを生成できる。 ...