Open Stack

On 19/01/22 07:45, Jeremy Stanley wrote:
> On 2022-01-18 23:21:21 +0500 (+0500), Mahnoor Asghar wrote:
> [...]
>> I am an Outreachy intern, working with OpenStack Ironic on improving
>> their API reference documentation mechanism.
> [...]
>
> Welcome!
>
>> The wider OpenStack community may be facing similar problems
>> maintaining their documentation, and it would be helpful to
>> understand their perspective and concerns - with respect to using
>> such an extension, their expectations from it, collaborating on
>> it, and whether they have additional ideas about how we may bring
>> API documentation closer to the code.
> [...]
>
> Keep in mind that developers of OpenStack's services have
> traditionally held the belief that a good public API should be
> versioned independently from the software which implements it. One
> version of the software may provide multiple API versions, and
> there's not necessarily a 1:1 correlation between public REST API
> methods and the internal Python API methods which implement them. I
> suspect this has driven some of the desire to separate REST API
> documentation from the source code itself.
>
> There have been past attempts to implement self-describing APIs,
> scraping running services in CI jobs, and so on. I don't recall the
> details, but folks who were active in the API SIG likely have a
> clearer recollection and can probably relate some of the challenges
> encountered with various approaches.

This proposal is mostly about moving the existing documentation to 
docstrings rather than introspecting the functions/methods themselves to 
auto-generate. There may be some auto-generate potential for parameters 
and output schemas, but whatever is done needs to be able to document 
the API version evolution. The benefits of this is more about giving 
developers proximity to the documentation of the REST API they're 
changing, making discrepancies more obvious, and giving reviewers a 
clear view on whether a change is documented correctly.