New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Docs: Add a "seealso" section to the module docs #45949

Open
wants to merge 2 commits into
base: devel
from

Conversation

@dagwieers
Member

dagwieers commented Sep 21, 2018

SUMMARY

Something I wanted for a longer time was a separate section to list related modules and/or related references. This clears up the notes section for things that are actual notes.

So you can add a section in your module documentation and four types of references are possible.

seealso:

# Reference by module name
- module: aci_tenant

# Reference by module name, including description
- module: aci_tenant
  description: ACI module to create tenants on a Cisco ACI fabric.

# Reference by rST documentation anchor
- ref: aci_guide
  description: Detailed information on how to manage your ACI infrastructure using Ansible.

# Reference by Internet resource
- name: APIC Management Information Model reference
  description: Complete reference of the APIC object model.
  link: https://developer.cisco.com/docs/apic-mim-ref/

This PR also includes:

  • Implements ansible-doc support
  • Implements schema support for the seealso options
  • Updates to the development documentation
  • Rename filter convert_symbols_to_format to rst_ify, cfr the existing html_ify and tty_ify filters
    • This makes the existing template a lot easier to read and fixes the confusion I had myself rereading the template (again).
  • We fixed the possible suboption types (which was limited to 'bool' only)
ISSUE TYPE
  • Docs Pull Request
  • Feature Pull Request
COMPONENT NAME

Module docs

ANSIBLE VERSION

v2.8

ADDITIONAL INFORMATION

Before:
screenshot from 2018-09-21 03-09-14

After:
screenshot from 2018-09-21 03-30-55

ansible-doc output

SEE ALSO:
      * Module aci_bd
           The official documentation on the aci_bd module.
           https://docs.ansible.com/ansible/devel/modules/aci_bd_module.html
      * Module aci_tenant
           The official documentation on the aci_tenant module.
           https://docs.ansible.com/ansible/devel/modules/aci_tenant_module.html
      * Ansible documentation [aci_guide]
           Detailed information on how to manage your ACI infrastructure using Ansible.
           https://docs.ansible.com/ansible/latest/#stq=aci_guide&stp=1
      * Ansible documentation [aci_dev_guide]
           Detailed guide on how to write your own Cisco ACI modules to contribute.
           https://docs.ansible.com/ansible/latest/#stq=aci_dev_guide&stp=1

The documentation for this feature looks like this:
screenshot from 2018-09-21 17-24-07

TODO (see #45985):

  • Currently ref-type references cannot be converted to a title + link, as Sphinx takes care of this internally. The solution is to make a searchable link that brings the user to the document based on the reference name.
@ansibot

This comment has been minimized.

@dagwieers

This comment has been minimized.

Member

dagwieers commented Sep 21, 2018

@dagwieers dagwieers added this to To do in Ansible Core Documentation via automation Sep 21, 2018

@dagwieers dagwieers force-pushed the dagwieers:doc-seealso branch 4 times, most recently from 2948904 to ccacf51 Sep 21, 2018

@ansibot

This comment has been minimized.

Contributor

ansibot commented Sep 21, 2018

@ansibot ansibot added the test label Sep 21, 2018

@ansibot

This comment was marked as resolved.

Contributor

ansibot commented Sep 21, 2018

The test ansible-test sanity --test validate-modules [explain] failed with 1 error:

lib/ansible/modules/network/aci/aci_bd_subnet.py:0:0: E305 DOCUMENTATION.seealso: extra keys not allowed @ data['seealso']. Got [{'module': 'aci_bd'}, {'module': 'aci_tenant'}]

click here for bot help

@ansibot ansibot added needs_revision and removed core_review labels Sep 21, 2018

@mkrizek mkrizek removed the needs_triage label Sep 21, 2018

@gundalow

This looks like a good addition. We will review in more detail after AnsibleFest

schema.py and /developing_modules_documenting will also need updating

Added to https://etherpad.openstack.org/p/ansible-summit-october-2018-documentation

@dagwieers

This comment was marked as resolved.

Member

dagwieers commented Sep 21, 2018

@gundalow If you look at the code, I do modify schema.py, however it does not work and I have no clue how it is supposed to work. Value should be a list of dictionaries, but the test still does not accept it.

And I think that's why ansible-doc is not working here either. Always returns None.

@gundalow gundalow changed the title from Docs: Add a "seealso" section to the module docs to [WIP] Docs: Add a "seealso" section to the module docs Sep 21, 2018

@dagwieers dagwieers force-pushed the dagwieers:doc-seealso branch 3 times, most recently from a0cf081 to d563d92 Sep 21, 2018

@ansibot ansibot added the WIP label Sep 21, 2018

Docs: Add a "seealso" section to the module docs
Something I wanted for a longer time was a separate section to list
related modules and/or related references. This clears up the notes
section for things that are actual notes.

So you can add a section in your module documentation and four types of
references are possible.

    seealso:

    # Reference by module name
    - module: aci_tenant

    # Reference by module name, including description
    - module: aci_tenant
      description: ACI module to create tenants on a Cisco ACI fabric.

    # Reference by rST documentation anchor
    - ref: aci_guide
      description: Detailed information on how to manage your ACI infrastructure using Ansible.

    # Reference by Internet resource
    - name: APIC Management Information Model reference
      description: Complete reference of the APIC object model.
      link: https://developer.cisco.com/docs/apic-mim-ref/

This PR also includes:

- Implements ansible-doc support
- Implements schema support for the seealso options
- Updates to the development documentation
- Rename filter convert_symbols_to_format to rst_ify, cfr the existing html_ify and tty_ify filters
  - This makes the existing template a lot easier to read and fixes the confusion I had myself rereading the template (again).
- We fixed the possible suboption types (which was limited to 'bool' only)

@dagwieers dagwieers force-pushed the dagwieers:doc-seealso branch from 500c766 to 0bccc57 Sep 21, 2018

All feedback was incorporated

@ansibot ansibot added core_review and removed needs_revision labels Sep 25, 2018

@gundalow

This comment has been minimized.

Contributor

gundalow commented Sep 25, 2018

On hold till after AnsibleFest

@dagwieers

This comment has been minimized.

Member

dagwieers commented Oct 10, 2018

@acozine Can we get this moving ?

@gundalow

This comment has been minimized.

Contributor

gundalow commented Oct 13, 2018

Once live we should mention this in ansible/community#346

Show resolved Hide resolved lib/ansible/cli/doc.py Outdated
@dagwieers

This comment has been minimized.

Member

dagwieers commented Oct 19, 2018

Ok, another re-review required. Thanks !

@ansibot ansibot removed the stale_ci label Oct 19, 2018

@gundalow

This comment has been minimized.

Contributor

gundalow commented Oct 22, 2018

Look at how ansible-doc --version works to get the current version

@dagwieers

This comment has been minimized.

Member

dagwieers commented Oct 22, 2018

The problem using the version string is that it has no knowledge about whether e.g. 2.7 is available on the docsite. Or whether it is latest or devel. During the several stages of release this may or may not be the case. So I think using latest is the safest bet overal.

And we should focus on making it easier to jump between versions on the docsite, which IMO has the highest priority for end-user experience. (Knowing most people end up on the wrong/older documentation through Google anyway).

@gundalow

This comment has been minimized.

Contributor

gundalow commented Oct 24, 2018

Dag, good point. Let's stick with /latest/

@ansibot ansibot added the stale_ci label Nov 1, 2018

@dagwieers

This comment has been minimized.

Member

dagwieers commented Nov 29, 2018

Ok, so anything else needed before we can merge this ?

@acozine

This comment has been minimized.

Contributor

acozine commented Nov 29, 2018

@dagwieers could the seealso section use the existing, documented link syntax to link to URLs and module docs? (U(https:external_url) for links and M(module_name) for modules)

@dagwieers

This comment has been minimized.

Member

dagwieers commented Nov 30, 2018

@acozine It is a YAML dictionary, not a free text-field. Because we don't let the user do the markup, it is a listing of information we present depending on where it is being used. So it doesn't make sense.

For instance, for the module entry we depend on the Sphinx references to automatically fill in the title.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment