可読コレクションのドキュメント化

Tadej Borov語AKによる語
本当のプログラマーがコードを文書化しないというのは周知の事実です.それを書くのが難しいならば、それは理解して、使用するのが難しいはずです.しかし、我々の仕事のために支払われるならば、この態度は少し問題であることを証明するかもしれません.そして、我々はあなたがすべて壊れた参照してくださいする必要はありませんので、我々はあなたの使用可能なコレクションを文書化する方法を示しますSphinx .

必要条件
このポストからコンピュータにコマンドをテストしたい場合は、新しい仮想環境を作成し、Sensu Go Ansible collection このように:

$ python3 -m venv venv
$ . venv/bin/activate
(venv) $ mkdir -p ansible_collections/sensu
(venv) $ cd ansible_collections/sensu
(venv) $ git clone https://github.com/sensu/sensu-go-ansible.git sensu_go
(venv) $ cd sensu_go
(venv) $ rm -rf docs/*

はい、これらのディレクトリはすべて必要です.この要件の背後にある理由を別のポストで説明するつもりです.しかし、現在、不可解なコレクションを文書化する問題に戻る時間です.

つ、2つのドキュメントタイプ!
技術的な作家は、異なる種類のドキュメンテーションを区別します.タイプの正確な数は異なりますfour and eight .
このポストのために、我々はタイプの大部分をまとめて、2種類のドキュメンテーションを考慮するだけです:ソースコードの一部であるAPI仕様と我々が我々の不可解なコレクションで送る残りのガイド.なぜ?APIコードをソースコードから抽出できます.残りのドキュメントを手動で書く必要があります.
ドキュメントのオーサリングのより技術的な面では、書き込みプロセス自体を簡単に見てフォーカスするだけです.

どのようなドキュメントツールをインストールする必要がありますか?

文書ディレクトリの初期構造をどのように設定できますか?

ドキュメントをレンダリングするときに実行する手順は何ですか?

コレクションドキュメントをオンラインで公開するには?

では、ブートストラップ処理を有効にしましょう.

貿易の道具
我々のコレクションのドキュメントを準備するために2つのツールを使用します.ansible-doc-extractor 可読モジュールに埋め込まれたドキュメントを抽出するにはSphinx レンダリングプロセスを駆動するため.

You have not heard about ansible-doc-extractor yet? It is probably the best invention since sliced bread ;) What does it do? It can extract module API documentation and render it into reStructuredText documents. We created it because we are lazy and need something that allows us to create a web API documentation for Sensu Go Ansible collection modules. And now you all get to benefit from our laziness ;)

両方のパッケージが利用できるのでPython package index , 一つのコマンドでインストールできます.

(venv) $ pip install Sphinx ansible-doc-extractor

すべてが計画に従って行かれるならば、我々は現在持っていますsphinx-quickstart and ansible-doc-extractor 利用可能なコマンドとドキュメントディレクトリ構造の作成を開始できます.

ドキュメント構造
私たちの不可解なコレクションドキュメントはdocs トップレベルディレクトリ.このディレクトリはSphinx設定のすべてを配置する場所です.ここでは、ソースドキュメントが表示されます.
一旦我々が作成したならばdocs ディレクトリは、以下のように実行します.

(venv) $ ( cd docs && sphinx-quickstart )

確認してくださいy 分離するかどうか尋ねられるときsource and build ディレクトリ.これらのディレクトリを分割すると、ドキュメントソースファイルをきちんと整理しておくことができます.お気軽にあなたの好みに他のすべての質問に答えてください.
では、実際のドキュメントを書き、生成します.

ドキュメントソースの準備
ドキュメントをエンドユーザに使用するには、少なくとも3つのセクションを作成する必要があります.

短いQuickstart章は、時間がお金である今日の世界で、必須です.

我々の不可解なコレクションがカバーするように設計されるという一般的なシナリオを記述する記事または2.

生成されたモジュールAPIドキュメントでは、エンドユーザーが脚本を書くときに使用されます.

最初の2つのセクションを手動で書く必要があります.しかし、すでに前に述べたように、我々はその最後の部分を自動化することができます.
我々のAPIドキュメントファイルをdocs/source/modules ディレクトリ.それから、私たちは、それらのすべてを我々のドキュメンテーションにテーブルの内容指示を変更することによって含むことができますdocs/source/index.rst ドキュメントから

.. toctree::
   :maxdepth: 1
   :caption: Contents:
   :glob:

   modules/*

さて、必要なのはモジュールAPIドキュメンテーションを抽出して、docs/source/modules ディレクトリ.そしてansible-doc-extractor , これはほとんど些細なことです.たとえば、APIドキュメントをsensu.sensu_go.asset モジュールの実行は簡単です.

(venv) $ mkdir -p docs/source/modules
(venv) $ ANSIBLE_COLLECTIONS_PATHS=$(pwd)/../../.. \
  ansible-doc-extractor docs/source/modules plugins/modules/asset.py

以前のコマンドが終了したら、私たちの資産モジュールのドキュメントを安全に保存する必要がありますdocs/source/modules/asset.rst ドキュメント.

You might have noticed that ANSIBLE_COLLECTIONS_PATHS variable that we set when running the extraction process. Why do we need it? Because Ansible needs to include Python modules that contain document fragments. And it can only do so if we point it towards the right folder. Oh, by the way, this is why we created all those folders when we cloned the Sensu Go collection.

今すぐグランドフィナーレ:ドキュメントをレンダリングし、それをWebに公開します.

ドキュメントの発行
私たちはGitHub Pages 簡単にするために我々のドキュメンテーションを主催すること.もちろん、静的なWebページを提供することができます何かを使用することができます.
しかし、我々が我々のコンテンツをギタブにプッシュする前に、我々はそれを提出する必要があります.ありがたいことにsphinx-quickstart プログラムは、docs 必要なすべてのコマンドを含むフォルダ.実行する必要があるのは、

(venv) $ ( cd docs && make html )

我々が現在開くならばdocs/build/html/index.html 我々の選択のウェブブラウザで、我々は我々のドキュメンテーションのホームページを見なければなりません:

(venv) $ xdg-open docs/build/html/index.html

最後に必要なのは、Githubに最終的なドキュメントをアップロードすることです.あなたがこれで援助を必要とするならばGitHub Pages サイトを参照し、ドキュメントを参照します.あなたの残りのために、ここでは、初めての出版物の自動操縦版です:

(venv) $ git checkout --orphan gh-pages
(venv) $ git rm -rf .
(venv) $ touch .nojekyll
(venv) $ git add .nojekyll
(venv) $ git commit -m "Init gh-pages branch"
(venv) $ git checkout master
(venv) $ git worktree add gh-pages gh-pages
(venv) $ rm -rf docs/build
(venv) $ ( cd docs && make html )
(venv) $ rsync -av docs/build/html/ gh-pages/
(venv) $ cd gh-pages
(venv) $ git commit -am "Update docs for release x.y.z"
(venv) $ git push -u origin gh-pages
(venv) $ cd ..

その後のドキュメントの更新は、より簡単です.

(venv) $ rm -rf docs/build
(venv) $ ( cd docs && make html )
(venv) $ rsync -av docs/build/html/ gh-pages/
(venv) $ cd gh-pages
(venv) $ git commit -am "Update docs for release x.y.z"
(venv) $ git push
(venv) $ cd ..

ご遠慮いたします

別れの言葉
あなたの中には、生成されたドキュメントが現在crapのように見えることに気づいたかもしれません.わたしたちはあなたを責めることはできません.)心に留めておきなさいansible-doc-extractor 進化の初期段階にある.一旦概念を確かめるならば、我々は親切に我々により良い形でものを得るのを援助するためにデザイナーまたは2に尋ねます.しかし、その時まで、“vimは私が必要とするすべての”-水のデザインの美しさをお楽しみください);
あなたが文書機械のすべての不可解なコレクションの現実の例を必要とするならばSensu Go Ansible collection リポジトリと外観docs ディレクトリ.そして、いつものように、私たちに連絡して自由に感じるかReddit .
乾杯!