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