Python API Documentation

[dekimsey]

Proposal: Python API Documentation

Author: Daniel Kimsey

Date: 2016/06/21

• Status: New
• Proposal type: documentation
• Targeted Release: 2.2
• Estimated time to implement: 1 months

  Motivation

Ansible has great user-oriented documentation detailing how the public facing components of the ansible tool works. But it is seriously lacking in internal documentation. The Python API page doesn't go into sufficient detail about all the various innards.

This makes writing plugins a bit challenging. Extending/hacking the internals is nigh-impossible. A great deal of work was done in v2 to OO the internals, but actual Sphinx/readthedocs style documentation of what various internals do and why is severely lacking.

Problems

For noteworthy places include:

• The executor modules, what do they each do. What kind of methods do they have?
• Strategy plugin interface, what are the arguments? What kind of errors might need to be handled? What can these objects do?
• What is the formal interface to the plugin types? What does CALLBACK_TYPE on a callback plugin do?
• When do callbacks get called?
• Exactly what attributes should I see on a Task/Play/Playbook object? (This one is a particular issue, objects with Attribute instances are not repr-able, nor is there any docs on what their attributes are and why they may or may not be set.)
• What is a DataLoader, a VarsModule, or a TaskQueueManager?

  Solution proposal

• Create actual API documentation.

  Anything else?

This is unfortunately something that might take a lot of work simply because there is very little existing API documentation. I fear the community will be less able to contribute than core-developers because it requires intimate knowledge of what these classes are and how they function.

[abadger]

See the connection plugin for an example of what we could be doing in this space: https://github.com/ansible/ansible/blob/devel/lib/ansible/plugins/connection/__init__.py

[trondhindenes]

I couldn't agree more, I was planning to use the api's when I wrote flansible (https://github.com/trondhindenes/flansible) but I simply couldn't figure it out, so I ended up building a shell-based thing instead. Would be great to have the api's at a level where it's at least feasible to build custom automation on top if ansible without having to shell the execution.

[bcoca]

@trondhindenes that is what ansible-runner is for

labeled 'in progress' as runner is a documented usable API and the 'public APIs' in ansilbe (module_utils/*, etc) have started the process of being documented https://docs.ansible.com/ansible/latest/reference_appendices/module_utils.html