今日は、弊社従業員が執筆した技術系記事をお届けします。
今回は、annofab-cliのドキュメントの改善について紹介します。
annofab-cli とは
annofab-cliは、弊社のアノテーションツール「Annofab」を、コマンドラインから操作するツールです。
annofab-cli のドキュメント
ドキュメントは https://annofab-cli.readthedocs.io/ja/latest/ から参照できます。
annofab-cliのドキュメントは、reStructuredText で書かれています。これをSphinxで生成して、ReadTheDocsにデプロイしています。
デプロイされたドキュメントは https://annofab-cli.readthedocs.io/ja/latest/ から参照できます。
ドキュメントの困りごと
今まで、annofab-cliのドキュメントには簡単なコマンドの使い方は記載されていましたが、コマンドラインオプションの説明までは記載されていませんでした。
annofab-cliの利用者がコマンドラインオプションを調べるには、以下のようなコマンドを実行する必要がありました。
$ annofabcli task list --help
usage: annofabcli task list [-h] [--yes] [--endpoint_url ENDPOINT_URL] [--logdir LOGDIR] [--disable_log] [--logging_yaml LOGGING_YAML] -p PROJECT_ID [-tq TASK_QUERY | -t TASK_ID [TASK_ID ...]] [-u USER_ID [USER_ID ...]] [-f {csv,json,pretty_json,task_id_list}]
[-o OUTPUT] [--csv_format CSV_FORMAT] [-q QUERY]
タスク一覧を出力します。
optional arguments:
-h, --help show this help message and exit
-p PROJECT_ID, --project_id PROJECT_ID
対象のプロジェクトのproject_idを指定します。 (default: None)
コマンドの実行でコマンドラインオプションを調べる場合、
- ● annofab-cliをインストールしないと、コマンドのヘルプを確認できない
- ● ターミナルに表示されたリンクやコードが見づらい
などの課題もありました。
どう解決したか
annofab-cliはPythonのargparseモジュールを使って、コマンドラインインターフェースを作成しています。
argparseで設定した内容からHTMLを生成するsphinx-argparseというSphinxの拡張機能があるので、今回はこの拡張機能を使いました。
以下に、作業した内容を記載します。
1. sphinx-argparseのインストール
poetryで開発用の依存関係として追加します。
$ poetry add sphinx-argparse --dev
2. sphinx-argparseをsphinx拡張機能として利用できるようにする
sphinxの設定ファイル（annofab-cli/docs/conf.py）のextensionsに、sphinxarg.ext を追加します。
extensions += ['sphinxarg.ext']
3. reStructuredTextファイルにargparseディレクティブを追加する
reStructuredTextファイル内で、コマンドヘルプを表示する箇所にargparseディレクティブを追加します。
たとえばannofabcli task listコマンドのヘルプを表示する場合は、annofab-cli/docs/command_reference/task/list.rst に、以下を追加します。
.. argparse::
:ref: annofabcli.task.list_tasks.add_parser
:prog: annofabcli task list
:nosubcommands:
:ref: には、argument.ArgumentParser クラスのインスタンスを返す関数を指定します。
def add_parser():
parser = argparse.ArgumentParser()
parser.add_argument("--project_id", type=str)
# ...
return parser
その他のオプションについては、https://sphinx-argparse.readthedocs.io/en/latest/usage.html を参照してください。
4. ドキュメントの生成
sphinx-buildコマンドを実行して、ドキュメントを生成します。
補足: 作業環境
作業した環境は以下の通りです。
- ● Python 3.8
- ● sphinx v4.2.0
- ● sphinx-argparse v0.2.5