-
Notifications
You must be signed in to change notification settings - Fork 23.7k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
allow plugin loader to load sidecar docs #83170
base: devel
Are you sure you want to change the base?
allow plugin loader to load sidecar docs #83170
Conversation
The sidecar feature is not meant for migrating docs from plugins that should have the documentation embeded, but for those that cannot easily do so like tests and filters as they can have multiple plugins per file and also for modules that are not written in python we can avoid the 'python doc file'. |
The RHEL failures are unrelated and at to be fixed separately. |
I see. I agree that my initial use case/impetus for this PR may not be using the sidecar documentation feature as intended, but I think the PR itself still has merit, unless there's no intention to provide this for other plugin types (if any?) |
i've asked other core team members to weigh in. Personally I prefer to have the docs and code in the same file as it makes it trivial to keep in sync. sidecar was added for those cases that it was not possible to do so and they also happen to be cases in which the docs do not act as configuration (tests, filters and modules). |
I remember discussions when the sidecar feature was new, there were also other plugin authors/maintainers who would have liked to use sidecar docs for plugins. One big advantage of having the docs in a separate YAML file is that syntax highlighting and editor support for YAML files "just works". (I'm not sure whether the VSCode Ansible plugin handles the YAML-in-Python 'correctly', but even if it does, it won't work in other editors.) @briantist I think you were also interested in this (but maybe I also misremember, in that case please ignore this ping :) ). |
Yes, I am also interested in this, there was at least one other issue for it somewhere.
And I think that's fine, but it is a matter of opinion for whomever is maintaining it. Letting those docs be in a sidecar gives maintainers a choice, and those want to continue to embed them can. |
I restarting the CI doesn't help. Please, rebase the PR. |
* if you have an inventory plugin (or other non-test/non-filter plugin, I'd assume) that has docs only provided via sidecar, then the plugin's config defs need to be populated by the sidecar; otherwise, you're forced to have a `DOCUMENTATION` attribute in the inventory plugin that duplicates the content of the sidecar
35fd5de
to
27c4276
Compare
rebased with 27c4276 |
DOCUMENTATION
attribute in the inventory plugin that duplicates the content of the sidecarSUMMARY
Started using
antsibull-docs
and noticed that sidecar YAML files could be used for documentation instead of variables in ansible modules. Converted some configurable inventory plugins to use this feature, only to find that the inventory plugin would no longer understand how to read its config file. Tracked it down to thePluginLoader
using theDOCUMENTATION
attribute of the module (*.py
) only. Figured that it wouldn't make sense for the documentation to be duplicated, and wanted to use the sidecar YAML instead of theDOCUMENTATION
variable in the plugin, so this PR allows both in-plugin and sidecarDOCUMENTATION
snippets to be used for the plugin loader's config def loading.Saw there was a TODO related to this, so did it.
You'll note that the added lines does some path joining and existence testing; I realize that
lib/ansible/utils/plugin_docs.py
has afind_plugin_docfile
, but I couldn't figure out how to getPluginLoader._load_config_defs
to give me aname
thatfind_plugin_docfile
would understand (mycontext
infind_plugin_docfile
was either falsy or not resolved, because I got a lot of<inventory_plugin_name> was not found
). FWIW, how I've structured my collections, etc. may be slightly nonstandard; regardless, since the code looks at the same directory as the plugin file (*.py
), I figured they were equivalent, and at least this gets the ball rolling on this feature. If you have any suggestions on how to usefind_plugin_docfile
, please let me know.ISSUE TYPE
ADDITIONAL INFORMATION
Given some inventory plugin
and sidecar
and inventory plugin config file
The output before this change was not having any inventory, because the custom inventory plugin stopped understanding how to parse the config, and this inventory plugin needs to parse the config to fetch inventory
after this change, the plugin loader can use the sidecar's
DOCUMENTATION
to determine what the options are, and therefore read the plugin config (and therefore populate inventory) again