publish docs to readthedocs.org

[ktdreyer]

We should publish docs at https://readthedocs.org/projects/koji-ansible/

Links of interest:

• antsibull-docs from https://github.com/ansible-community/antsibull
• Felix Fontein's example of 3rd party module docs:
  • Output at https://ansible.fontein.de/
  • Makefile that generates this: https://github.com/felixfontein/felix-ansible-docsite/blob/main/Makefile

And from #ansible-community today:

< samccann> I'm wondering if we need to find a place to say where to find sphinx themes that are workable for creating your own collection-level docsite? like - https://github.com/felixfontein/felix-ansible-docsite/blob/main/_static/ansible.css
< samccann> not in official docs/ but maybe ansible-collections/overview? I feel bad directing people to grow their own docs solution, but I don't know how long they'd have to wait for Galaxy to show it
< dmsimard> samccann: https://github.com/ansible/ansible/blob/devel/docs/docsite/_extensions/pygments_lexer.py is pretty neat too.
< dmsimard> as in, making it available outside of ansible/ansible (like the themes) would be nice
< felixfontein> I'm not very familiar with how sphinx themes work; would it be possible to create a "theme extension" that adds a small CSS file to an existing theme and something like https://github.com/ansible/ansible/blob/devel/docs/docsite/_extensions/pygments_lexer.py ?
< felixfontein> I second that
< felixfontein> can sphinx extensions add CSS (and be theme-independent)?
< felixfontein> if yes, that should be very doable

< dmsimard> ktdreyer: ara used to have role docs in sphinx and used "code-block:: yaml+jinja" for nice syntax highlighting
< dmsimard> because the roles were split outside of ara and into a collection, there's no more sphinx so it's raw markdown nowadays

[ktdreyer]

The antsibull repo now supports third-party modules, and it works pretty well. It requires the latest ansible-core on PyPI.

I've pushed my current progress to a readthedocs branch today.

[ktdreyer]

Next step is to move the Makefile logic into conf.py, similar to what we have in https://github.com/ceph/ceph/blob/master/doc/conf.py

See docs at https://www.sphinx-doc.org/en/master/extdev/appapi.html#sphinx-core-events

[ktdreyer]

Tangent: ansible-doc and antsibull-docs supports some styles that we could start using to make the docs look nicer.

For example C(systemctl restart httpd) will render that as quoted text on the console (withansible-doc) and monospaced text in HTML (with antsibull-docs and sphinx).

The full list of supported escape values is available at antsibull/jinja2/filters.py, see also the unit tests that exercise them all at tests/units/test_jinja2.py

[ktdreyer]

This page describes more about that syntax: https://docs.ansible.com/ansible/2.9/dev_guide/developing_modules_documenting.html#linking-within-module-documentation

[ktdreyer]

Ansible now has a standard way for modules to advertise their check_mode and diff_mode support in the HTML documentation. It looks like this:

attributes:
    check_mode:
        support: full
    diff_mode:
        support: partial
    platform:
        platforms: rhel

See any in-tree module, for example yum_repository.py.