Fix version_added

[phospi]

I was observing that collection_prep took the field version_added from the modules doc-string and replaced whatever was written in version_added with 1.0.0.

I don't understand very much what's going on in collection_prep but it was very unexpected that collection_prep did not only produced unexpected results but changed the actual module doc-string as well. I would expect collection_prep to leave the module docstring untouched.

[phospi]

Can someone please review this PR?
@goneri @Qalthos @NilashishC ?

[phospi]

Can someone please review this PR this year?
@goneri @Qalthos @NilashishC @ashwini-mhatre?

[Qalthos]

Can I ask what you're trying to do with this?

The original purpose of this code was to update lots of files from the core ansible repository and update them to have fully-qualified collection names for use in a new collection. This new collection would naturally have a version_added of 1.0.0, being a brand new collection. Even if you're trying to move something out of ansible/ansible today, the version_added value would not be the original value but some other fixed value (probably taken by args) representing the next version of that collection.

My guess is you're trying to use this as a kind of validation step to make sure FQCNs are used consistently in docs? If so, that's probably a thing that we could pivot this to do, though in that case I'm not sure we need this code at all as I'm pretty sure ansible-lint already has checks requiring version_added.

[phospi]

Hi @Qalthos,

many thanks for taking the time and checking my pull request.

I didn't know about that migration background. My situation is that I am running collection_prep as a pipeline step in my collection repository to get the docs generated from the doc-strings inside the modules. But of course my version_added differ in many cases from 1.0.0 and collection_prep is alway overwriting my configured version_added.

My PR is checking for the configured version_added in the doc-string and puts that into the generated docs. Currently collection_prep doesn't bother about a already documented version_added at all. But of course, to incorporate that with your scenario I should update my else-case.

Proposal:

    version_added = documentation.pop("version_added", None)
    desc_idx = [
        idx
        for idx, key in enumerate(documentation.keys())
        if key == "description"
    ]
    if version_added is not None:
        # insert detected version_added after the description
        documentation.insert(desc_idx[0] + 1, key="version_added", value=version_added)
    else:
        # insert new version_added after the description
        documentation.insert(desc_idx[0] + 1, key="version_added", value="1.0.0")

Interesting that you are mentioning ansible-lint. I always looked at ansible-lint as a linter for ansible yaml-files, like playbooks and roles. I didn't know that ansible-lint is capable of linting python code in ansible modules. Are you sure that works? The docs are completely yaml focused. All ansible-lint rules are about yaml structure.

[Qalthos]

My situation is that I am running collection_prep as a pipeline step in my collection repository to get the docs generated from the doc-strings inside the modules.

It sounds like you just want collection_prep_add_docs instead of all of collection_prep_update. That is the one we actively use to regenerate the documentation on collections. You can even use it as a pre-commit hook!

Though if there is something that update does that add_docs doesn't, let us know and we'll see if we can get it in add_docs instead.

Interesting that you are mentioning ansible-lint. I always looked at ansible-lint as a linter for ansible yaml-files, like playbooks and roles. I didn't know that ansible-lint is capable of linting python code in ansible modules. Are you sure that works? The docs are completely yaml focused. All ansible-lint rules are about yaml structure.

Yeah, I got my wires crossed, sorry. ansible-test sanity (specifically the validate-modules test) is the thing that verifies that version_added is set properly.