docs.ansible.com: one-click module-category link on the module pages

[gitqlt]

Proposal:

Author: gitqlt <@gitqlt> IRC: n/a Date: 2018-10-21

• Status: New
• Proposal type: docs.ansible.com
• Targeted release: 2.7
• Associated PR:
• Estimated time to implement: X

Motivation

Easier navigation with one-click module-category link on the module pages.

Problems

The positioning header on the top of the module pages shows only two (clickable) levels. Eg:

• Docs
• script - Runs a local script on a remote node after transferring it

However, the module category link (here: Commands modules) is missing. To see all the similar modules together makes it easier to learn/differentiate the modules' functionality, so the module category should be accessible with one-click from the module description page.

Solution proposal

Include the module index, module category links as well. Eg:

• Docs ( or better: REFERENCE & APPENDICES)
• Module Index
• Commands modules
• script - Runs a local script on a remote node after transferring it

Dependencies (optional)

Testing (optional)

Documentation (optional)

Anything else?

The problem is not just with the modules. For example, the positioning header of page https://docs.ansible.com/ansible/2.7/user_guide/playbooks_reuse_includes.html currently shows

• Docs
• Including and Importing

but should be constructed from the links:

• Docs (or better: USING ANSIBLE)
• User Guide
• Working With Playbooks
• Creating Reusable Playbooks
• Including and Importing

[webknjaz]

cc @acozine @gundalow @dagwieers

[acozine]

@gitqlt thanks for writing up this proposal. Currently each page has two breadcrumb links: one to itself (on the page you reference, that's the "Including and Importing" link) and the other ("Docs") to the main index page for the Ansible Core documentation. I've added this to the agenda for the November 6 Documentation Working Group meeting.

[decentral1se]

:+1:

[kolibri]

The module pages also have another problem: They don't collapse the navigation on the left side. So, even if you are on a modules page, you have to collapse the menu to get to the categories.

For me, the modules reference is the main reason why I visit the docs. I just want to check quickly modules/argument names. The entire modules section could be part of the left menu accessible by one click.

[ahuffman]

:+1:

[gitqlt]

After starting with the collections, breadcrumb links are still missing on the documentation pages of the modules. Most collections, including ansible.builtin have really weak references: all you can do is click the Docs link. But a sequence of links Docs / All Modules,Plugins / Ansible.Builtin / template (e.g. on the page: template) would provide a better user experience. In particular, access to the page Ansible.Builtin would be useful.

With the General Community, you have a two-click hack. The modules here have a link to the Galaxy where you find the Ansible Docs site. Again, the breadcrumb links would be better. Docs / All Modules,Plugins / Community.General / yaml

=== Anyway

[acozine]

@gitqlt please review https://github.com/ansible-community/antsibull/pull/240