Open Stack

On Mon, 5 Aug 2013 09:15:33 -0500
Anne Gentle <annegentle at justwriteclick.com> wrote:

> On Mon, Aug 5, 2013 at 8:55 AM, John Garbutt <john at johngarbutt.com>
> wrote:
> > On 5 August 2013 08:44, Christopher Yeoh <cbkyeoh at gmail.com> wrote:
> > > A separate metafile is created for each api sample response
> > > rather than trying to accumulate them by extension because this
> > > way it allows for the tests to still be run in parallel. The
> > > metafile also adds the logging of
> > the
> > > status code expected which is not currently done and I think an
> > > important part of the API.
> >
> 
> Wow what's your guess on how many files this will be? Trying to think
> of this from a doc management standpoint for troubleshooting when the
> output is incorrect.

Well around 60 extensions with say an average of 4-5 methods each,
times 2 for JSON/XML. Note that we already generate a lot more files
than that for the api samples already though. We could theoretically
collate the files in a post process on the nova side I guess which
would mean one meta file per extension instead, but I don't think it
really matters if that happens on the Nova tree side or the
documentation side.

I agree around concerns around troubleshooting. It would always have to
be a case of either fixing the script or fixing the source data (api
samples or meta data) and not manually patching the end result.

> > >
> > > On the documentation side we'd have a script collate all the
> > > metafiles
> > and
> > > produce the bulk of the specification document.
> >
> 
> I'd like to see the results of that script, and it's good you're
> thinking about docs. But if you create the docs from the code it's
> not quite a spec, what if the code is incorrect? Maybe I
> misunderstand.

The script doesn't yet exist, but Kersten is looking at what would
needed to be done (I don't understand enough of what is required at the
doc end to write it myself). 

We currently do create the docs from the code, so saying its a
"specification" is a bit backwards. It'd be a document of how we
actually behave rather than how we're theoretically supposed to.
But that's essentially what api.openstack.org/api_refs is now with the
api samples generated from code.

> 
> I fully support these efforts, and I just want to be sure I
> understand the eventual outcomes and ramifications.

Cool - just throwing this out now to get a bit of a sanity check around
it. And I do want to establish that there is enough information in the
metafile to automate the process. I'd eventually like to get to the
point where the API doc generation stays pretty much in sync with the
code itself with little manual intervention (probably just resyncing
the api doc tree with the nova tree every now and then).

Regards,

Chris