はじめに
Ansible のドキュメントは Sphinx で生成されるようになっています。
これまでちょっとした文言修正は、ちゃんとビルドして確認してこなかったのですが、先日書式レベルで修正したことがありました。そのため、ビルドする方法をしらべて試しました。
公式ドキュメントとしては、以下のページにまとめられています。
このブログ記事では、私が実行した手順をまとめます。あくまで、今回私はこうやった、という記録だけです。詳細は前述の公式ドキュメントしてください。
git clone
予め GitHub の ansible/ansible リポジトリを、自分のアカウントに fork しておきます。
fork したほうを git clone します。
$ git clone git@github.com/akira6592/ansible $ cd ansible $ git status On branch devel
今回のドキュメント修正用のブランチを devel から作成します。
$ git checkout -b fix-development_process
Python 環境の準備
Sphinx でビルドするために Python 環境を準備する必要があります。今回は専用の venv を作成します。
$ python3.9 -m venv ~/envs/adoc $ source ~/envs/adoc/bin/activate
clone した中の docs/docsite ディレクトリに、requirements.txt があるので、これをもとに pip install します。
$ cd docs/docsite $ pip install -r requirements.txt
ドキュメント修正
実際にドキュメントを修正します。今回は、docs/docsite/rst/community/development_process.rst です。
ちょっとした修正です。
このリンクの書式
:ref:`backported <backport_process>`
の動作を確認したくて、ビルドしようと思った次第です。
この書式は、Ansible 側でもきちんと説明されていました。
なお、生成されているのは以下のページです。
The Ansible Development Cycle — Ansible Documentation
チェック
次に、rstcheck によるチェックです。
$ pwd /Users/sakana/Documents/git/ansible/docs/docsite $ rstcheck rst/community/development_process.rst rst/community/development_process.rst:1: (INFO/1) Hyperlink target "community-development-process" is not referenced. rst/community/development_process.rst:30: (INFO/1) Hyperlink target "community-pull-requests" is not referenced. rst/community/development_process.rst:144: (INFO/1) Hyperlink target "community-changelogs" is not referenced. rst/community/development_process.rst:168: (INFO/1) Hyperlink target "changelogs-how-to" is not referenced. rst/community/development_process.rst:258: (INFO/1) Hyperlink target "changelogs-how-to-format" is not referenced. rst/community/development_process.rst:302: (INFO/1) Hyperlink target "changelogs-how-to-format-playbooks" is not referenced. rst/community/development_process.rst:320: (INFO/1) Hyperlink target "backport-process" is not referenced. Error! Issues detected.
あれれ・・。今回修正したリンクとにたような文言 backport-process が表示されてしまいました。ちゃんと参照関係は通るはずなのですが。実際の動作はビルドして確認することにします。
（なお、修正前の状態でも同じ表示がされていました。）
ビルド
いよいよビルドです。ここでいうビルドは HTML の生成です。
ビルドする対象の範囲によってビルドする方法もいくつかあるようですが、今回は htmlsingle にしました。
内部で sphinx-build コマンドなどが実行されるようです。
コマンドとしては、make htmlsingle rst=rstファイルのパス なのですが、rst オプションで指定したパスに対して rst ディレクトリが補完されるので、rst ディレクトリを除いた形で指定します。
$ pwd /Users/sakana/Documents/git/ansible/docs/docsite $ make htmlsingle rst=community/development_process.rst Creating symlinks in gettext_structure ln -sf ../rst/core_index.rst rst/index.rst ln -sf ../rst/dev_guide/core_index.rst rst/dev_guide/index.rst ln -sf ../sphinx_conf/all_conf.py rst/conf.py sphinx-build -j 4 -b html -d _build/doctrees ./rst _build/html rst/community/development_process.rst Sphinx v5.1.1 を実行中 出力先ディレクトリを作成しています... 完了 /Users/sakana/Documents/git/ansible/docs/docsite/rst/dev_guide/index.rst: WARNING: ドキュメントを読めません。無視します。 https://docs.python.org/2/objects.inv から intersphinx インベントリをロード中... https://docs.python.org/3/objects.inv から intersphinx インベントリをロード中... http://jinja.palletsprojects.com/objects.inv から intersphinx インベントリをロード中... https://docs.ansible.com/ansible/6/objects.inv から intersphinx インベントリをロード中... ...(略)... ビルド中 [mo]: 指定された 0 件のpoファイル ビルド中 [html]: コマンドラインで指定された1件のソースファイル 環境データを更新中[新しい設定] 9345 件追加, 0 件更新, 0 件削除 ソースを読み込み中...[ 1%] 2.10_index .. collections/ansible/builtin/items_lookup ソースを読み込み中...[ 3%] collections/ansible/builtin/jsonfile_cache .. collections/ansible/posix/debug_callback ソースを読み込み中...[ 4%] collections/ansible/posix/firewalld_info_module .. collections/arista/eos/eos_linkagg_modul ...(略)... ソースを読み込み中...[100%] scenario_guides/vmware_rest_scenarios/create_vm .. win_guide/windows_winrm /Users/sakana/Documents/git/ansible/docs/docsite/rst/dev_guide/index.rst: WARNING: ドキュメントを読めません。無視します。 /Users/sakana/Documents/git/ansible/docs/docsite/rst/index.rst:65: WARNING: toctree に存在しないドキュメントへの参照が含まれています 'dev_guide/index' ...(略)... /Users/sakana/Documents/git/ansible/docs/docsite/rst/dev_guide/core_index.rst: WARNING: ドキュメントはどの toctree にも含まれていません 完了 ドキュメントの出力準備中... WARNING: 検索インデックスを読み込めず、ドキュメントビルドの一部が不完全です。 完了 出力中...[100%] index 索引を生成中... genindex py-modindex 完了 追加のページを出力中... search 完了 ダウンロードファイルをコピー中...[100%] network/getting_started/sample_files/first_playbook_ext.yml 静的ファイルをコピー中... 完了 extraファイルをコピー中... 完了 English (code: en) の検索インデックスを出力... 完了 オブジェクト インベントリを出力... 完了 ビルド 成功, 982 警告. HTMLページは_build/htmlにあります。 Output is in _build/html/community/development_process.html $
私の環境では結構時間がかかりました。警告が表示さていていて少しもやもやしますが、エラーではないようです。
表示と確認
ビルド実行結果の最後にあるように、HTML ファイルが _build/html/community/development_process.html に生成されました。
リポジトリトップからのパスだと docs/docsite/_build/html/community/development_process.html です。これを実際にブラウザで表示して、修正したリンクや表示を確認します。
あとは、CI でのテストに任せたいと思います。
git push と PR
通常と同じく、git push して PR を出します。
CI も通ってくれて、内容も問題ないと判断され、マージしていただきました。
今回 PR を出した devel ブランチは、現在 2.14 開発向けです。stable-2.13 へのバックポートは、別途まとめて出していただきました。最近は 週に一度程度 bulk backport されているようです。
まとめ
Ansible の公式ドキュメントを修正して、ビルド、確認、プルリクエストをだすまでやったことをまとめました。
これまでは、ビルドする方法が分からなかったので、書式レベルの修正は億劫だったのですが、今回できてよかったです。
ドキュメントの修正方法自体がちゃんとドキュメントにまとまってるのもとても助かりました。
