On 2022-01-18 11:14:59 -0800 (-0800), Julia Kreger wrote:
On Tue, Jan 18, 2022 at 10:49 AM Jeremy Stanley <fungi@yuggoth.org> 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.
And the API version contracts we've tended to offer has been a very linear progression matching the software versions, for the most part. I think as the groups of maintainers have evolved, I believe the traditional belief may no longer really hold true. Or at least, there doesn't seem to be a good reason to continue to keep aspects disjointed and separated, at least that I'm aware of. I guess to put it another way, we have finite capacity/bandwidth, and anything we do to reduce hurdles, can help us further our work. [...]
Absolutely, that's why I qualified it with "traditionally" (many may no longer feel this way, or the people who made those choices may no longer be around/involved in their respective projects). I'm in favor of the Ironic team pursuing whatever makes documenting easier, just noting that the approach may not be applicable OpenStack-wide for these or other reasons. -- Jeremy Stanley