On Mon, 5 Aug 2013 09:15:33 -0500 Anne Gentle <annegen...@justwriteclick.com> wrote:
> On Mon, Aug 5, 2013 at 8:55 AM, John Garbutt <j...@johngarbutt.com> > wrote: > > On 5 August 2013 08:44, Christopher Yeoh <cbky...@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 _______________________________________________ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev