可読コレクションのドキュメント化
本当のプログラマーがコードを文書化しないというのは周知の事実です.それを書くのが難しいならば、それは理解して、使用するのが難しいはずです.しかし、我々の仕事のために支払われるならば、この態度は少し問題であることを証明するかもしれません.そして、我々はあなたがすべて壊れた参照してくださいする必要はありませんので、我々はあなたの使用可能なコレクションを文書化する方法を示します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つのセクションを作成する必要があります.
我々の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 .乾杯!
Reference
この問題について(可読コレクションのドキュメント化), 我々は、より多くの情報をここで見つけました https://dev.to/xlab_si/documenting-ansible-collections-1g1iテキストは自由に共有またはコピーできます。ただし、このドキュメントのURLは参考URLとして残しておいてください。
Collection and Share based on the CC Protocol