[Ironic][docs][api-sig] Moving API Documentation closer to code
fungi at yuggoth.org
Tue Jan 18 19:54:17 UTC 2022
On 2022-01-18 11:14:59 -0800 (-0800), Julia Kreger wrote:
> On Tue, Jan 18, 2022 at 10:49 AM Jeremy Stanley <fungi at 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.
-------------- next part --------------
A non-text attachment was scrubbed...
Size: 963 bytes
Desc: not available
More information about the openstack-discuss