Uploaded image for project: 'Automation Hub'
  1. Automation Hub
  2. AAH-53

Exclude doc_fragments and module_utils from plugin documentation

Details

    • Task
    • Resolution: Done
    • Normal
    • 2.0, 4.4cloud02
    • 2.0
    • UI
    • None
    • 2
    • False
    • False
    • Undefined
    • AAH Sprint 6, AAH Sprint 7, AAH Sprint 8

    Description

      Use Case

      Users want to find out what plugins are available to them to use within playbooks etc from the collections.

      Today, the AH plugin list includes doc_fragments and module_utils, neither of which are directly usable to a user of the collection. This extraneous information makes it more difficult for a user to find what they looking for.

      For example, the amazon.aws collectionhas 7 plugins that can be used in playbooks etc, but AH lists 27.

      Today on docs.ansible.com, we do not expose doc_fragments (or module_utils) in the user-facing documentation. [doc_fragments](https://docs.ansible.com/ansible/devel/dev_guide/developing_modules_documenting.html#documentation-fragments) are a developer convenience to add a common 'fragment' of the module docstring across multiple modules.

      I noticed this is different on AH:

      https://cloud.redhat.com/ansible/automation-hub/amazon/aws/content/doc_fragments/aws

      There was some discussion about this on a slack channel, that there is a corner case wherein a customer using the Amazon.aws collection could be writing their own modules and could want to use the doc_fragment in their modules. That seems to me a very small number of potential customers that need this info vs the majority who have to wade through excess doc_fragments (and possibly module_util) entries in AH to find what they are really looking for. If such information is deemed important, it is more developer documentation, not the user documentation that AH seems best suited to display.

      Alternatives

      NOTE: This is based on a brief internal discussion and amazon.aws is only used here as an example, not to imply the collection maintainers agree or disagree with how AH works today, but I didn't want this discussion to get lost on slack so opened this issue for further consideration by AH folks.

      Attachments

        Activity

          People

            cspealma@redhat.com Clara Spealman
            chousekn Chris Houseknecht (Inactive)
            Votes:
            0 Vote for this issue
            Watchers:
            1 Start watching this issue

            Dates

              Created:
              Updated:
              Resolved: