Clarify/remove use of collection_prep for collection documentation

[felixfontein]

#66 added "Include a README file in each collection", which mentions

Generating the README's plugin documentation from the plugin code helps eliminate documentation errors.
Supplemental documentation such as user guides may be written in reStructured Text (rst) and located in the docs/docsite/rst/ directory of the collection.

and then recommends (via Examples:)

Use https://github.com/ansible-network/collection_prep to generate the documentation for the collection

collection_prep's collection_prep_add_docs tool (which I guess is meant here) does multiple things:

1. It updates the collection's README file;
2. It creates docs/*.rst files for all plugins and modules contained in the collection (see https://github.com/ansible-collections/ansible.utils/tree/main/docs for an example).

While the README part is totally fine, I have several problems with 2.:

• Why are these .rst files in docs/ generated at all? I don't see that they are useful.
  • They are not updated after every PR, but often only on release time, so you cannot use them in the collection's repo to look at docs for the latest commit. (If someone wants that, there are other tools for that: https://github.com/ansible-community/github-docs-build)
  • They are not useful when being in an offline environment, since a) RST preview isn't really available (MD would be more useful), and b) the HTML blobs for the tables are not exactly easy to read when considering it as a text file (see for example https://raw.githubusercontent.com/ansible-collections/ansible.utils/main/docs/ansible.utils.validate_test.rst).
  • Users that want to look at docs in an offline environment can use ansible-doc to see a nicer version (compare the raw text above with ansible-doc -t test ansible.utils.validate).
  • If users have online access, they can look at better rendered documentation. (AH / galaxy_ng show documentation, see for example https://galaxy.ansible.com/ui/repo/published/ansible/utils/content/test/validate/ for the same plugin.)
  • I've asked around multiple times to figure out why some collections add these .rst files at all. So far I never got a useful answer.
• Even if someone wants these .rst files in docs/, collection_prep's docs generation is severely outdated and unmaintained; there are PRs open for years (!) that would improve it, and it doesn't support basic functionality such as Ansible semantic markup, which has been around for two years by now.
  • PRs: Mention the name of collection along with version_added ansible-network/collection_prep#72, Use antsibull-docs-parser to render semantic markup ansible-network/collection_prep#88, render 'choices' when they are a dictionary ansible-network/collection_prep#92

Considering all this, recommending collection_prep in its current state is a bad idea in my opinion. If it would allow to only update the README, using it only for that would be fine IMO. But adding the .rst files to docs/... considering the points above, I think it is more bad practice. Maybe there are also good reasons for doing it, but I haven't heard of any so far.

[ericzolf]

The arguments are conclusive to me. @jillr you created the initial PR, you want to react to those comments?

[jillr]

collection_prep was the solution we had at the time, but we have been moving more towards github actions for publishing docs. I agree that collection_prep is no longer the best solution and https://github.com/ansible-community/github-docs-build is a better choice for what we had been using it for.

[yurnov]

They are not updated after every PR, but often only on release time, so you cannot use them in the collection's repo to look at docs for the latest commit. (If someone wants that, there are other tools for that: https://github.com/ansible-community/github-docs-build)

They should be updated every PR, to do that in each collections repo it should be something like CONTRIBUTION.md with a guide that each PR should include documentation update and a clear instruction on how to do it, like here.