I’m looking to see if there are any examples that are publicly available about using mkdocs-material for hosting the collections docs? Mkdocs-material theme provides a lot of capabilities that it would be good to incorporate further. Such as a version admonition.
I’m not an expert on the documentation stuff, but maybe someone from @Docs could help here.
I don’t know of a mkdocs one for collection docs, but there is the following for a sphinx-based docsite for a collection - Creating a collection docsite - antsibull-docs – Ansible Documentation Build Scripts
The Ansible mkdocs theme is built on material: GitHub - ansible/mkdocs-ansible: Ansible MkDocs Theme based on Material
Not sure there are any collections docs using it though.
So… I’m kind of in the same boat right now. I’m trying to create a sample Ansible collection, currently which only contains a few roles. So I have role documentation done both in markdown as README.md in each role’s directory and also as meta/argument_specs.yml.
antsibull-docs does well in creating the HTML for the roles via antsibull-docs sphinx-init --use-current --dest-dir built-docs.
But we also use mkdocs to convert all markdown in the project into an HTML site.
The problem I’m about to try and figure out is:
- Can I use antsibull-docs to write markdown to then be picked up by mkdocs? (Edit: Probably not - Allow markdown? · Issue #20 · ansible-community/antsibull-changelog · GitHub )
- Can I use mkdocs to convert rst along with markdown to html, since antsibull-docs also generates rst (Edit: No - Question: Can the source be RestructuredText (rst)? · Issue #1817 · mkdocs/mkdocs · GitHub )
- Can I use a third tool to convert rst over to markdown to feed mkdocs? (Edit: There is now - python translate script for converting site from sphinx-build to mkdocs-material · squidfunk/mkdocs-material · Discussion #6092 · GitHub )
- Is there some standard for documenting collections like there is for roles and plugins? The Official documentation only talks about roles and plugins. So without guidance there, I’m left to free-form a README.md at the root of the project.
- How to properly merge my overall collection project markdown with the content coming from antsibull-docs to make it look coherent?
- How to do all of this within a GitLab tag pipeline
antsibull-docs right now has no support for generating MarkDown, though that shouldn’t be too hard to implement. The main problem I see with MarkDown is that it has not very good support for tables (see option/return/attribute tables), except by adding HTML blobs for these, and that links to specific parts of other documents are cumbersome. This is something RST is far better at.
That issue is for antsibull-changelog, not for antsibull-docs 
There is currently no issue for antsibull-docs for that… (Feel free to create one, the repo is here: GitHub - ansible-community/antsibull-docs: Tooling for building Ansible documentation)
@felixfontein When you say MD having poor support for tables, what would you say is missing?
And actually while I have you here… …do you know if there’s any sort of standard for argument_specs.yml-type documentation-as-code for Ansible collections and playbooks? I love that it’s implemented for roles and plugins but it really feels like collections and playbooks are kind of left to the developer’s interpretation.
You cannot have more than one paragraph inside a table cell, and anything but the most basic formatting is hard.
(Compare that to RST list tables, where you can put a lot of stuff inside a table cell. That’s basically what antsibull-docs is using for the Sphinx output. For the ‘simplified RST’ output - suitable for example for GitHub - it uses HTML blobs, since GitHub’s RST renderer didn’t supported list tables. It might do now, since they made big changes to their RST renderer this year…)
I don’t think there is. antsibull-docs can do this (same as for plugins and modules), but there are also other role-specific tools (I think). There are also elaborated tools (some of them have been around ofr quite some time) that create (or update in README) option tables based on default/main.yml, or maybe also other input than argument_specs.yml.
1 Like
You can in fact have multiple paragraphs in one cell, you just have to put in some HTML
style. But that still isn’t pleasant by any means in that fashion.
But we have found the formatting capabilities within MKdocs-material has been quite amazing and awesome to work with.
Will work with trying to work out mkdocs-ansible to see if it can auto-format everything. Maybe that will be something to be made if that package doesn’t do what is expected.
Overall, should we look at continuing to host our own documents for the modules? Or should we be looking to just point at the Galaxy documentation??
I had been making some really good progress on getting what would be needed for a docs generation script. However, I’m running into the extension of other docs. Such as these:
extends_documentation_fragment:
- constructed
- inventory_cache
I’m about to dive into the antsibull docs to see if I can decipher it. I have it parsing modules just fine and looking good.
If anyone else has some thoughts about this before I dig in, that would be helpful.
@jvanderaa you really don’t want to parse documentation manually; use ansible-doc --metadata-dump --no-fail-on-errors foo.bar to dump all docs for all modules, plugins, and roles in the collection foo.bar as JSON and work with that instead.
Also if you need to interpret Ansible markup (like C(...), M(...), etc) you might be interested in GitHub - ansible-community/antsibull-docs-parser: Python library for processing Ansible documentation markup if you’re using Python, or GitHub - ansible-community/antsibull-docs-ts: TypeScript library for processing Ansible documentation markup if you’re using JavaScript or TypeScript. These zero-dependency libraries parse markup and have built-in functionality to convert it to MarkDown or RST or HTML, and make it easy to write conversion functions to other formats.
Do you know where I can find more info on the usage of antsibull-docs-parser? The GitHub repo really only talks about installation. Is this utility useful for converting argument_specs for modules and roles to markdown?
My nickel is leave it to Galaxy if you do not have any extra guides (as in you have plugin docs and a readme). Galaxy will likely outperform your individual collection docsite on search results.
But if you have user guides etc associated with your collection, Galaxy doesn’t really support that well, so you do end up needing a docsite for those. But that docsite doesn’t have to repeat the plugin docs that Galaxy already has.
Right now there is no documentation, but you can look at how it was integrated into various programs:
- Use antsibull-docs-parser to render semantic markup by felixfontein · Pull Request #88 · ansible-network/collection_prep · GitHub
- Use antsibull-docs-parser to render semantic markup by felixfontein · Pull Request #28 · xlab-steampunk/ansible-doc-extractor · GitHub
It is useful for one very specific part of that, namely for converting one (or multiple) paragraph using Ansible markup to markdown. You still have to handle processing the argument spec and templating that somehow.
Right now be warned that Galaxy does not render role argument specs (not sure whether there’s an issue tracking that, since galaxy_ng does not use GitHub for issues), and it does not render documentation of plugins that use docs fragments from other collections (Galaxy importer: collection dependency handling, no idea whether there’s anything in galaxy_ng’s issue tracker for that either).
1 Like
This is perfect @felixfontein - the part with the ansible-doc portion. That will get me a long ways down the road here. I had been working on some things with the help of LLM to do some parsing. But working from the structured data is going to be terrific. I will definitely be glad to share or help collaborate on enhancing it for others if those in the position of say are willing to accept another format.