build documentation for python API in lib/

[azrdev]

SUMMARY

Please let sphinx build documentation for the python API.

---

Apparently docs.ansible.com and everything in the ansible-doc (RPM) package is rendered from the docs/ directory in this repo. This includes e.g. in dev_guide/developing_plugins some code like

from ansible.errors import AnsibleError, AnsibleParserError
from ansible.plugins.lookup import LookupBase
from ansible.utils.display import Display

display = Display()

But if one wants to discover the API of these classes, it's necessary to dig into the source at lib/ansible/ (or use an IDE).

Probably a first step would be to add the lib/ansible/ directory to SOURCEDIR = in docs/docsite/Makefile.sphinx, and reference the output in the dev_guide.

Maybe sphinx even supports linking these API classes from the code samples in the rst files -- as a later step.

ISSUE TYPE

• Documentation Report

COMPONENT NAME

developing_plugins.rst

developing_inventory.rst

ANSIBLE VERSION

ansible 2.9.14
  config file = /etc/ansible/ansible.cfg
  configured module search path = ['/home/user/.ansible/plugins/modules', '/usr/share/ansible/plugins/modules']
  ansible python module location = /usr/lib/python3.8/site-packages/ansible
  executable location = /usr/bin/ansible
  python version = 3.8.6 (default, Sep 25 2020, 00:00:00) [GCC 10.2.1 20200723 (Red Hat 10.2.1-1)]

CONFIGURATION

OS / ENVIRONMENT

any

ADDITIONAL INFORMATION

[ansibot]

Files identified in the description: None

If these files are incorrect, please update the component name section of the description or use the !component bot command.

click here for bot help

[ansibot]

@azrdev: Greetings! Thanks for taking the time to open this issue. In order for the community to handle your issue effectively, we need a bit more information.

Here are the items we could not find in your description:

• component name

Please set the description of this issue with an appropriate template from: https://github.com/ansible/ansible/tree/devel/.github/ISSUE_TEMPLATE

click here for bot help

[webknjaz]

Hey @azrdev, there's no supported Python API. We only document what we support. Also, the docs build process is rather slow. Adding things like sphinxcontrib-apidoc, while sounds easy, may substantially slow down the build even more and I'm not sure if we're willing to sacrifice this.

[azrdev]

Thanks for the reply, @webknjaz

there's no supported Python API. We only document what we support.

The problem here is that the Developer Guide (in the official docs) references that python API -- since it's required to write plugins (e.g. inventory plugin).

[webknjaz]

What exactly is missing? You're only supposed to use what's documented there.

[samdoran]

needs_info

[azrdev]

To answer the question "what is missing", some thoughts:

1. what's the difference between the inventory parameter to parse() and self.inventory? I saw the same object reference, but is that always so? And which one should be used?
2. "The DataLoader can read files, auto load [...]" -- how to do so, does it have any interface?
3. Apparently (seen in other inventory plugins) for signaling non-fatal errors self.display can be used, but what methods does it provide?
4. class Cacheable is explained in the caching section, but class Constructable is only mentioned as "you can incorporate other features by adding more base classes" -- what would it do, and if I wanted to use it, how? What other "base classes"/mixins are provided?
5. InventoryManager.add_group() is not even mentioned in the docs
6. add_host, add_group only return the host/group as string, not (as I first expected) an object which could be added to other groups or provide a scoped set_variable method.
7. (edit 2021-01-13) How would I add a host belonging to a group? Set the group parameter of InventoryManager.add_host(host, group, port) to a string instead of None. How would I add a host to multiple groups? Or a group? (use InventoryData.add_child apparently)

As I said, just some thoughts: A real API doc would surely answer more and would ideally be exhaustive, i.e. when something is missing there, one can be sure it is not yet provided by ansible (to avoid NIH/duplication)

I just found https://docs.ansible.com/ansible/latest/dev_guide/developing_api.html which doesn't answer these questions, but at least shows some more use of that internal API, and also provides the "internal API" disclaimer.

In general this means the preferred way of integrating external dynamic inventories must depend on ansible internal API and may therefore break without prior notice at any point… sounds suboptimal to me.

[ansibot]

@azrdev This issue is waiting for you to provide the requested data in the description. Please edit the description or the issue will be closed.

click here for bot help

[ansibot]

Files identified in the description:

• docs/docsite/rst/dev_guide/developing_inventory.rst
• docs/docsite/rst/dev_guide/developing_plugins.rst

If these files are incorrect, please update the component name section of the description or use the !component bot command.

click here for bot help