diff options
author | Felix Fontein <felix@fontein.de> | 2022-08-04 22:47:59 +0200 |
---|---|---|
committer | GitHub <noreply@github.com> | 2022-08-04 15:47:59 -0500 |
commit | a2984758dc727eb90cb9717e3b966c782b32cae8 (patch) | |
tree | fbaf44910f101d4c8eb8ec0e040391c4f0a15632 /docs/docsite/rst | |
parent | 775cf8549164fe1655d5dbcadbe544cf18f30566 (diff) | |
download | ansible-a2984758dc727eb90cb9717e3b966c782b32cae8.tar.gz |
[2.13] Add basic docs on how to create a collection docsite with antsibull-docs (#78446)
* Add basic docs on how to create a collection docsite with antsibull-docs. (#78387)
(cherry picked from commit 733a7679485c84d8ee6c4ebf95c76d172e0369de)
* Fix typo: missing 'install'. (#78448)
(cherry picked from commit 2218b63aefc558ff967a8597a1dc9c4c5f88e27c)
Diffstat (limited to 'docs/docsite/rst')
3 files changed, 32 insertions, 1 deletions
diff --git a/docs/docsite/rst/dev_guide/developing_collections.rst b/docs/docsite/rst/dev_guide/developing_collections.rst index f2e1fb6eb7..d3fb4f7fca 100644 --- a/docs/docsite/rst/dev_guide/developing_collections.rst +++ b/docs/docsite/rst/dev_guide/developing_collections.rst @@ -16,6 +16,7 @@ You can create a collection and publish it to `Ansible Galaxy <https://galaxy.an developing_collections_shared developing_collections_testing developing_collections_distributing + developing_collections_documenting .. toctree:: :maxdepth: 2 diff --git a/docs/docsite/rst/dev_guide/developing_collections_documenting.rst b/docs/docsite/rst/dev_guide/developing_collections_documenting.rst new file mode 100644 index 0000000000..426aa47d1d --- /dev/null +++ b/docs/docsite/rst/dev_guide/developing_collections_documenting.rst @@ -0,0 +1,30 @@ +.. _documenting_collections: + +*********************** +Documenting collections +*********************** + +Documenting modules and plugins +=============================== + +Documenting modules is thoroughly documented in :ref:`module_documenting`. Plugins can be documented the same way as modules, that is with ``DOCUMENTATION``, ``EXAMPLES``, and ``RETURN`` blocks. + +Documenting roles +================= + +To document a role, you have to add a role argument spec by creating a file ``meta/argument_specs.yml`` in your role. As an example, you can look at `the argument specs file <https://github.com/sensu/sensu-go-ansible/blob/master/roles/install/meta/argument_specs.yml>`_ of the :ref:`sensu.sensu_go.install role <ansible_collections.sensu.sensu_go.install_role>` on GitHub. + +.. _build_collection_docsite: + +Build a docsite with antsibull-docs +=================================== + +You can use `antsibull-docs <https://pypi.org/project/antsibull-docs>`_ to build a Sphinx-based docsite for your collection: + +#. Create your collection and make sure you can use it with ansible-core by adding it to your :ref:`COLLECTIONS_PATHS`. +#. Create a directory ``dest`` and run ``antsibull-docs sphinx-init --use-current --dest-dir dest namespace.name``, where ``namespace.name`` is the name of your collection. +#. Go into ``dest`` and run ``pip install -r requirements.txt``. You might want to create a venv and activate it first to avoid installing this globally. +#. Then run ``./build.sh``. +#. Open ``build/html/index.html`` in a browser of your choice. + +If you want to add additional documentation to your collection next to the plugin, module, and role documentation, see :ref:`collections_doc_dir`. diff --git a/docs/docsite/rst/dev_guide/developing_modules_documenting.rst b/docs/docsite/rst/dev_guide/developing_modules_documenting.rst index 9bd9cbd461..081f7493b0 100644 --- a/docs/docsite/rst/dev_guide/developing_modules_documenting.rst +++ b/docs/docsite/rst/dev_guide/developing_modules_documenting.rst @@ -447,4 +447,4 @@ The use of "wildcard" imports such as ``from module_utils.basic import *`` is no Testing module documentation ============================ -To test Ansible documentation locally please :ref:`follow instruction<testing_module_documentation>`. +To test Ansible documentation locally please :ref:`follow instruction<testing_module_documentation>`. To test documentation in collections, please see :ref:`build_collection_docsite`. |