Deprecation by date

[felixfontein]

No description provided.

[abadger]

My first instinct on seeing this was that it belongs in the schema because it is data manipulation, not just display. It's going to be desirable for Galaxy and other things that need to display the documentation to have access to this as well.

But thinking about how it would fit into the schema, i think it goes a little beyond what the schema is responsible for. It's creating data rather than normalizing existing data.

So i think this belongs here:

https://github.com/ansible-community/antsibull/blob/master/antsibull/cli/doc_commands/stable.py#L256

There needs to be a function which calculates additional data from what was actually pulled out of the documentation fields. For instance, full_path for outputting the suboptions correctly will end up in that function. I think this is similar and belongs in that function as well

[abadger]

@awcrosby I think this new function that I mentioned to @felixfontein above is what you were wanting as well -- a place where we can have common code that converts or adds to the raw documentation data structures so all of us generating output from it have an easier time. Maybe you'll want to hit me up on slack (or jump on irc, #ansible-docs) to talk more about whether that can work for you too?

[felixfontein]

I completely restarted this branch from scratch. It now contains the schema definitions currently in use in Ansible for deprecation by date, and for (auto-)adding collection names.

[felixfontein]

I've split up DeprecationSchema into TopLevelDeprecationSchema (uses removed_in, removed_at_date and removed_from_collection) and OptionDeprecationSchema (uses version, date and collection_name), and made sure that only plugin options can be deprecated this way, but not module options. (Module options are deprecated via argument spec.)

This makes the schema be compatible to what Ansible's code and validate-module's schema currently require resp. enforce.

The top-level name -> option name conversions in OptionDeprecationSchema are debatable, since Ansible itself will only accept the option name fields. Maybe we should remove the conversions?

[felixfontein]

@abadger I'm confused. Where does that "version_added": "historical" come from in all the good schema validation data? I don't think ansible-doc exports that. Ignore that, I think I understood what's going on :)

[felixfontein]

(What's missing right now is a XOR check for deprecation by date and deprecation by version.) Added.

[abadger]

Looks good, thanks!

[felixfontein]

@abadger also thanks a lot for reviewing this one!