[Ironic][docs] Moving API Documentation closer to code
Dear all,
I am an Outreachy intern, working with OpenStack Ironic on improving their API reference documentation mechanism. Currently, the API documentation is kept separately from the code (in the Ironic repository), which means it diverges from the code, and is difficult to maintain and manage as development progresses.
It would be desirable to auto-document our REST API interactions and data structures in code along with the very classes they come from. This way, we can clearly understand the request, the response, and any other important interaction details from a single point of view inside the code. It will also be a lot easier to maintain.
The current Ironic API documentation is being generated by Sphinx, using the os-api-ref extension. It would be a viable solution to move the documentation from the separate sub-directory to docstrings within the code files itself, and develop a Sphinx extension that provides essential features to generate the documentation from docstrings.
More details about the proposed extension, and its features can be found on the Ironic Storyboard [1].
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.
[1]: https://storyboard.openstack.org/#!/story/2009785
Thank you and regards, Mahnoor Asghar
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.
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.
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. -- Jeremy Stanley
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.
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.
On 2022-01-19 11:10:58 +1300 (+1300), Steve Baker wrote: [...]
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.
Correct, I don't recall anyone having tried exactly that approach yet. It's more akin to what you'd do for documenting a Python library. I was merely mentioning what other solutions had been attempted, as an explanation for why I was adding the [api-sig] subject tag. Apologies if that was unclear.
I understand more clearly now the reason for the initial choice of keeping the documentation and code separate. Any solution to address the maintainability problem that has arisen as a consequence, should be able to maintain API version history. Auto-documentation is another approach we could try, but I think it would not offer many features or be very descriptive. (The output might be very boilerplate-looking).
On Wed, Jan 19, 2022 at 4:10 AM Jeremy Stanley fungi@yuggoth.org wrote:
On 2022-01-19 11:10:58 +1300 (+1300), Steve Baker wrote: [...]
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.
Correct, I don't recall anyone having tried exactly that approach yet. It's more akin to what you'd do for documenting a Python library. I was merely mentioning what other solutions had been attempted, as an explanation for why I was adding the [api-sig] subject tag. Apologies if that was unclear. -- Jeremy Stanley
participants (4)
-
Jeremy Stanley
-
Julia Kreger
-
Mahnoor Asghar
-
Steve Baker