[collection] How to display a role documentation ?

[nqb]

Bug Report

SUMMARY

When browsing a collection on Galaxy website, you can't display README.md for a role.

STEPS TO REPRODUCE

• Browse https://galaxy.ansible.com/newswangerd/collection_demo
• Click on "Content"
• Try to display README.md for a role

EXPECTED RESULTS

You should be able to display README.md for a role like for a standalone role (outside a collection).

ACTUAL RESULTS

Impossible to display README.md for a role.

[chouseknecht]

This will be figured out in the next release of Galaxy. We're still sorting out exactly how to document Collections, and what documentation files will be displayed and how by Galaxy.

[geerlingguy]

Probably related:

• Docs: develop guidelines for documenting certified roles
• Docs: metadata for role documentation
• ansible/proposals - Proposal: role specification

[ericsysmin]

I like detailed documentation with tons of examples. I know exactly what I will likely do with the Avi Networks docs directory. Including multiple examples and cross-module and environment docs including more thorough docs than why I could do on Galaxy, or on Ansible docs. It would make plenty of sense to redirect a role docs if desired to readthedocs just like PyPI does. For example when you have over 80 examples of using your modules and you need to handle versioning them.

Would it really make sense to provide playbook documentation that uses 10+ modules within the collection? Yes, I don't think I'd advise that though when documenting a single module docstring.

In galaxy.yml we also have this

# The URL to any online docs
#documentation: http://docs.example.com 

Which could direct to a readthedocs page based on docs/ directory. Which would make sense.

[fabianvf]

The import required me to add role READMEs for the roles in my collection (which is fair), but I was surprised to see that there was apparently no way to view them in the collection UI. Feels a little odd to be required to provide documentation that the users can't even see

[chouseknecht]

We are running the latest galaxy-importer, which actually does transform role README files into HTML. The problem is that we have not updated the API and the frontend Javascript to do anything with the HTML. Collections uploaded to c.rh.c have role README files displayed in the UI, so we have the code. It's a matter of finding the time and hands to implement it here in the community codebase.

[newswangerd]

For clarity, c.rh.c is cloud.redhat.com.

[geerlingguy]

Mind blown: how did earlier collections like https://galaxy.ansible.com/testing/ansible_testing_content have the ability to display their role READMEs inline when listing all the roles? Screenshot in case this behavior changes:

[chouseknecht]

I think that's because there was a time when a collection was imported from a GitHub repository rather than an uploaded artifact. Surprised that still exists and actually works. Neat.