Building html documentation for standalone local module: where to find Makefile?

Get Help
1

Hi,

I’m currently reading through: Testing plugin documentation — Ansible Documentation

It says:

  1. Build HTML from your module documentation: MODULES=mymodule make webdocs.

It might sound a little silly, but can somebody point me to that Makefile? I can’t find it in GitHub - ansible/ansible: Ansible is a radically simple IT automation platform that makes your applications and systems easier to deploy and maintain. Automate everything from code deployment to network configuration to cloud management, in a language that approaches plain English, using SSH, with no agents to install on remote systems. https://docs.ansible.com. and as far as I understand I can’t use antsibull-docs since it’s a standalone local module.

2

I think the last version of Ansible this worked for was 2.9. For ansible-base 2.10 / Ansible 2.10 the docs building process was completely changed, but this part of the documentation apparently was never updated accordingly.

Nowadays you should use a collection (you can have local collections next to your playbooks, similar to local modules), then you can use antsibull-docs + Sphinx to create HTML docs for your collection (documentation).

3

I knew I’ve seen that Makefile somewhere in the past. Thanks!

I presume I have to change COLLECTIONS_PATHS accordingly (e.g. through ansible.cfg)? ansible doesn’t seem to look for collections next to the playbooks out of the box.

Thanks a bunch!

4

No, you only need to change that configuration (except if you want to place the collections somewhere else).

Iy you have a playbook in a directory, create a subdirectory structure collections/ansible_collections/foo/bar/. In that directory you can place the contents of the foo.bar collection (like galaxy.yml) If you run a playbook in the directory which contains collections/, ansible will find the foo.bar collection.

The nested collections/ansible_collections/ structure is important (and also somewhat annoying :wink: ).

(It’s mentioned in the docs at the end of this section: Installing collections — Ansible Documentation. I guess it would make sense make that more prominent…)

5

PR to remove/update the outdated parts on building module HTML docs: Remove/update incorrect docs building documentation by felixfontein · Pull Request #1128 · ansible/ansible-documentation · GitHub

6

I created an issue for improving the docs for local collections: Better document local collections for playbooks · Issue #1129 · ansible/ansible-documentation · GitHub