nikkie-ftnextの日記

イベントレポートや読書メモを発信

Python公式ドキュメントをローカルでビルドする

Sphinx

はじめに

venvの--upgrade-depsをよろしくね！ nikkieです。

みなさん、Pythonのドキュメントを手元でビルドしたくなることってありますよね？？
ということでやってみましょう！

※本記事はすぐどこかで役に立つことはない部類の一本と思われます

目次

手順

$ git clone git@github.com:python/cpython.git
$ cd cpython/Doc
$ make venv
$ make html

Doc/README.rst

このREADMEにすべて書いてあります1。
https://github.com/python/cpython/blob/main/Doc/README.rst

Pythonの公式ドキュメントはSphinxでビルドされています。
『Sphinxをはじめよう 第3版』によると

Sphinxは、もともとPythonの公式ドキュメントを作成するツールとして開発されました。（1.1）

Docディレクトリ以下はSphinxのプロジェクトの趣がありますね（Makefileやconf.py）

Doc/Makefile

Makefileにコマンドがまとまっています。
make helpで確認できます。

make venv

creates a virtual environment with all necessary tools installed.

https://github.com/python/cpython/blob/ffd79bea0f032df5a2e7f75e8c823a09cdc7c7a2/Doc/Makefile#L166-L168

標準ライブラリのvenvを使って仮想環境を作り、requirements.txtに挙げられた依存ライブラリをインストールしています。
なお、make clean-venvでvenvディレクトリを消せます

make html

原稿をhtmlでビルドします。

builds standalone HTML files for offline viewing.

仮想環境をPATHに追加して、sphinx-buildコマンドを呼び出しています。
https://github.com/python/cpython/blob/ffd79bea0f032df5a2e7f75e8c823a09cdc7c7a2/Doc/Makefile#L9 これならsourceせずに書けるわけですね（sourceしてもいいかもですが、私はこちらの書き方が好み）

Makefileの書き方が上手いと思いました。
https://github.com/python/cpython/blob/ffd79bea0f032df5a2e7f75e8c823a09cdc7c7a2/Doc/Makefile#L78-L80

html: BUILDER = html
html: build
    @echo "..."

html target用に変数を指定することで、関数に引数を渡すみたいな書き方ができています（もっと理解したい事項）

Python公式ドキュメントはすごい情報量ですよね。
sphinx-buildコマンドには-jを指定して、ビルドを並列化しています。
https://github.com/python/cpython/blob/ffd79bea0f032df5a2e7f75e8c823a09cdc7c7a2/Doc/Makefile#L22-L27

https://www.sphinx-doc.org/ja/master/man/sphinx-build.html#cmdoption-sphinx-build-j

Distribute the build over N processes in parallel, to make building on multiprocessor machines more effective.

こうしてドキュメントがビルドできます！
make htmlviewもあり、これはmake htmlの後にブラウザが立ち上がります！
https://github.com/python/cpython/blob/ffd79bea0f032df5a2e7f75e8c823a09cdc7c7a2/Doc/Makefile#L144-L145

公式ドキュメント用Sphinx拡張

tools/extensionsの下に2Sphinx拡張（setup()関数を持つPythonモジュール）が置かれています。
https://github.com/python/cpython/tree/main/Doc/tools/extensions

これらの拡張を覗くと、setup()関数が返す辞書（＝拡張のメタデータ）でparallel_read_safeがTrueに指定されています。
https://www.sphinx-doc.org/ja/master/extdev/index.html#extension-metadata

sphinx-build -j autoと並列にビルドしている3ので、どの拡張でもソースを並列に読み込めると明示する必要があるわけですね。
一貫しています。

終わりに

Pythonの公式ドキュメントをローカルでビルドする方法でした。
README.rstに沿ってMakefileを叩けば簡単にビルドできます！

Makefileの書き方に学びがありました。

  • 仮想環境はsourceしなくてもいい。都度PATHに追加する
  • html targetの書き方（1回しか指定できないという思い込みがありました）

P.S. ついでに翻訳プチ改善

Sphinxドキュメントで参照箇所に見つけたtypoの類を直しました

  1. エントリ執筆時点 https://github.com/python/cpython/blob/ffd79bea0f032df5a2e7f75e8c823a09cdc7c7a2/Doc/README.rst↩
  2. conf.pyでも参照しています https://github.com/python/cpython/blob/ffd79bea0f032df5a2e7f75e8c823a09cdc7c7a2/Doc/conf.py#L12↩
  3. autoはCPU数分並列にする指定です ref: https://www.sphinx-doc.org/ja/master/man/sphinx-build.html#cmdoption-sphinx-build-j↩