てくなべ (tekunabe)

ansible / network automation / 学習メモ

[Ansible] ドキュメントを修正、ビルド、確認してプルリクエストを出すまでにやったこと

はじめに

Ansible のドキュメントは Sphinx で生成されるようになっています。

これまでちょっとした文言修正は、ちゃんとビルドして確認してこなかったのですが、先日書式レベルで修正したことがありました。そのため、ビルドする方法をしらべて試しました。

公式ドキュメントとしては、以下のページにまとめられています。

docs.ansible.com

このブログ記事では、私が実行した手順をまとめます。あくまで、今回私はこうやった、という記録だけです。詳細は前述の公式ドキュメントしてください。

git clone

予め GitHubansible/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 です。

ちょっとした修正です。

github.com

このリンクの書式

: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 です。これを実際にブラウザで表示して、修正したリンクや表示を確認します。

ビルドして生成されたHTML(ローカル)

あとは、CI でのテストに任せたいと思います。

git push と PR

通常と同じく、git push して PR を出します。

CI も通ってくれて、内容も問題ないと判断され、マージしていただきました。

今回 PR を出した devel ブランチは、現在 2.14 開発向けです。stable-2.13 へのバックポートは、別途まとめて出していただきました。最近は 週に一度程度 bulk backport されているようです。

まとめ

Ansible の公式ドキュメントを修正して、ビルド、確認、プルリクエストをだすまでやったことをまとめました。

これまでは、ビルドする方法が分からなかったので、書式レベルの修正は億劫だったのですが、今回できてよかったです。

ドキュメントの修正方法自体がちゃんとドキュメントにまとまってるのもとても助かりました。

docs.ansible.com