internet/community.general
3
0
Fork 0
mirror of https://github.com/ansible-collections/community.general.git synced 2026-05-06 13:22:48 +00:00
Code Issues Packages Projects Releases Wiki Activity

Doc fragments to plugins (#50172)

Browse Source 
* promote doc_fragments into actual plugins

  change tests hardcoded path to doc fragments
  avoid sanity in fragments
  avoid improper testing of doc_fragments
  also change runner paths
 fix botmeta
 updated comment for fragments
 updated docs
This commit is contained in:
Brian Coca
2019-01-23 20:03:47 -05:00
committed by GitHub
parent 4041f02389
commit 96b3ef5553
106 changed files with 51 additions and 31 deletions
Download Patch File Download Diff File Expand all files Collapse all files

9
docs/docsite/rst/dev_guide/developing_modules_documenting.rst
View File

@@ -272,7 +272,14 @@ You can link from your module documentation to other module docs, other resource
Documentation fragments
-----------------------
If you're writing multiple related modules, they may share common documentation, such as authentication details or file mode settings. Rather than duplicate that information in each module's ``DOCUMENTATION`` block, you can save it once as a fragment and use it in each module's documentation. Shared documentation fragments are contained in a ``ModuleDocFragment`` class in `lib/ansible/utils/module_docs_fragments/ <https://github.com/ansible/ansible/tree/devel/lib/ansible/utils/module_docs_fragments>`_. To include a documentation fragment, add ``extends_documentation_fragment: FRAGMENT_NAME`` in your module's documentation.
If you're writing multiple related modules, they may share common documentation, such as authentication details or file mode settings. Rather than duplicate that information in each module's ``DOCUMENTATION`` block, you can save it once as a doc_fragment plugin and use it in each module's documentation. In Ansible, shared documentation fragments are contained in a ``ModuleDocFragment`` class in `lib/ansible/plugins/doc_fragments/ <https://github.com/ansible/ansible/tree/devel/lib/ansible/plugins/doc_fragments>`_. To include a documentation fragment, add ``extends_documentation_fragment: FRAGMENT_NAME`` in your module's documentation.
.. _note:
* in 2.8 the Ansible directories for doc fragments changed, see documentation of previous versions to find the old locations.
.. versionadded:: 2.8
Since version 2.8, you can have user supplied doc_fragments by using a ``doc_fragments`` directory adjacent to play or role, just like any other plugin.
For example, all AWS modules should include::