自分の Python パッケージに MkDocs + Read the Docs によるドキュメントを用意する

ドキュメント作成ツール Sphinx を使用すると、自分の Python パッケージの Docstrings から素敵なドキュメントを作成できますが (こちらおよびリンクされている GitHub リポジトリを参照)、reST で記述しなければならず、久しぶりに書くとき文法が思い出せないと思います。
そこで、マークダウンで記述できる MkDocs を使用してみました。使用例が以下です。

• リポジトリ： https://github.com/CookieBox26/shirotsubaki/tree/ce12f0b
• ドキュメント： https://shirotsubaki.readthedocs.io/en/latest/

リポジトリは以下のようになっています。(1)～(5) を実施すれば Read the Docs でドキュメントを公開できます。

shirotsubaki/  # 適当なパッケージ
├── src/
│   └── shirotsubaki/  # パッケージ本体
│       ├── __init__.py
│       └── utils.py  # (1) 適宜 Docstrings を書いておく
├── tests/
│   └── test_color.py  # 単体テスト
├── pyproject.toml  # (2) optional-dependencies を追加する
├── LICENSE
├── README.md
│
│  # ここから下はドキュメント用ファイル群
│
├── docs/  # (3) ドキュメントを記述する
│   ├── index.md
│   └── reference.md
├── mkdocs.yml  # (4) mkdocs.yml を記述する
└── .readthedocs.yaml  # (5) .readthedocs.yaml を記述する

参考文献

1. https://squidfunk.github.io/mkdocs-material/setup/changing-the-colors/
   • material テーマで選択可能なプライマリカラーなどがあります。
2. https://mkdocstrings.github.io/python/usage/
   • mkdocstrings の使い方やオプションがあります。

手順

(1) 適宜 Docstrings を書いておく

適宜書いておいてください。Google スタイルで書いてみました。
https://github.com/CookieBox26/shirotsubaki/blob/ce12f0b/shirotsubaki/utils.py#L2-L16

(2) optional-dependencies を追加する

今回、以下のパッケージが必要です。

pip install mkdocs  # マークダウンからドキュメントをビルドしてくれる
pip install mkdocs-material  # モダンでシンプルなテーマ (検索機能やレスポンシブ対応もあり)
pip install mkdocstrings-python  # Python コード内の Docstrings をパースしてくれる

ローカルにこれらを入れればよいですが、Read the Docs でのビルド時にも必要なので、依存性を指定できるように optional-dependencies に docs などと名付けて追加しておきます。

[project.optional-dependencies]
docs = [
    "mkdocs",
    "mkdocs-material",
    "mkdocstrings-python",
]

(3) ドキュメントを記述する

以下のように、用意したいページたちをマークダウンで記述すればよいです。
https://github.com/CookieBox26/shirotsubaki/tree/ce12f0b/docs

Docstrings を吸い上げたい関数は以下のように ::: に続けてパスを指定しておきます。

# Reference

## shirotsubaki.utils

::: shirotsubaki.utils.lighten_color

(4) mkdocs.yml を記述する

以下のように mkdocs.yml を記述します。
https://github.com/CookieBox26/shirotsubaki/blob/ce12f0b/mkdocs.yml

site_name: "Shirotsubaki"
theme:
  name: material
  palette:
    primary: white
nav:
  - Home: index.md
  - Reference: reference.md
extra:
  social:
    - icon: fontawesome/brands/github
      link: https://github.com/CookieBox26/shirotsubaki
plugins:
  - search
  - mkdocstrings:
      handlers:
        python:
          options:
            heading_level: 3
            show_root_heading: true
            docstring_section_style: list
            show_source: false

記述内容の意味は以下です。

• シンプルなデザインで高機能なテーマ material を採用し、私はプライマリカラーを white にしました。他にもいくつかの色名が指定できますし、スタイルシートを用意することを厭わなければまったく好きなプライマリカラーにもできます (参考文献1.)。
• nav: には (3) で用意したドキュメントを、サイドバーにどんな文字列でリンクするかを指定します。
• extra: のように記述するとドキュメントの右下に GitHub のアイコンが表示されて自分のリポジトリにリンクできます。無論リンクしなくてもよいです。
• options: に指定している mkdocstrings のオプションの意味は以下です (参考文献2.)。
  • show_root_heading: true： 関数名を表示する (デフォルトでは表示してくれない)。
  • heading_level: 3： 表示する関数名はレベル 3 の見出しにする。
  • docstring_section_style: list： パラメータはリスト形式で表示する (デフォルトではテーブル形式になるがシンプルにしたかったので)。
• show_source: false： ソースコードを表示しない (デフォルトでは展開すると関数のソースコードがみられるようになっていてそれはそれで親切だがそこまで要らないので)。

ここまで用意できたら、リポジトリ直下で以下を実行すると、ローカル 8000 番 http://localhost:8000/ に素敵なドキュメントが表示されると思います。思ったようになっていなかったら設定を見直したりドキュメントを見直したり Docstrings を見直したりします。

mkdocs serve

(5) .readthedocs.yaml を記述する

ドキュメントを公開したい場合であって Read the Docs を利用して公開する場合は .readthedocs.yaml を記述します。
https://github.com/CookieBox26/shirotsubaki/blob/ce12f0b/.readthedocs.yml

(1) で optional-dependencies に docs と名付けたので、extra_requirements: に docs と指定しています。その他注意すべき点としては、.readthedocs.yaml に記述した Python バージョン (上では 3.10) であなたのパッケージがインストールできなければなりません¹。

.readthedocs.yaml まで用意できて GitHub にコミットしたら、Read the Docs であなたのドキュメントを公開できるはずです。

• Read the Docs Community のアカウントを取得してください。
• ログインしてプロジェクト画面の「Add project」から対象のリポジトリを追加してください。

1. このため、Read the Docs サーバが未対応の Python バージョンのパッケージをつくれないという制約が存在します。他方、Read the Docs に頼らずに GitHub Pages でドキュメントを公開しようとするのもリポジトリを汚す恐れがある気がしています。よくわかりません。 ↩