From 46f633598edc870011003d765eaf36e67678150f Mon Sep 17 00:00:00 2001 From: Toshio Kuratomi Date: Thu, 12 Sep 2019 09:55:50 -0700 Subject: [PATCH] Add guidelines for when to use a doc_fragment (#61828) --- .../docsite/rst/dev_guide/developing_modules_documenting.rst | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/docs/docsite/rst/dev_guide/developing_modules_documenting.rst b/docs/docsite/rst/dev_guide/developing_modules_documenting.rst index 3dfa8710c95..d01e8789c78 100644 --- a/docs/docsite/rst/dev_guide/developing_modules_documenting.rst +++ b/docs/docsite/rst/dev_guide/developing_modules_documenting.rst @@ -285,6 +285,11 @@ Documentation fragments If you're writing multiple related modules, they may share common documentation, such as authentication details, file mode settings, ``notes:`` or ``seealso:`` entries. 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/ `_. To include a documentation fragment, add ``extends_documentation_fragment: FRAGMENT_NAME`` in your module's documentation. +Modules should only use a doc_fragment if it will implement all of the interface documented there in +a manner that behaves the same as the existing modules which implement that fragment. The goal is +that any parameter listed in doc_fragments will behave identically when used in another module +implementing the doc_fragment. + .. _note: * Prior to Ansible 2.8, documentation fragments were kept in ``lib/ansible/utils/module_docs_fragments``.