Open Stack

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