Trove/ExampleGenerator
Contents
Description
The API docs have a bunch of snippets featuring the JSON request and respond headers and body. Currently these are made by manually with no validation that they resemble what Trove is actually doing.
We can instead generate these docs using simple Python code. Rackspace has used such code for about two years but was unable to submit it as until recently there was no place for it to live. However during the Austin midcycle (now half a year ago) we asked Anne Gentle, guest speaker, if it would be acceptable to move the Trove API docs to the main Trove repo. Through the hard work of Anne, Andreas Jaeger, and others the docs were moved. Following up on that we can finally move the doc generation tool to Trove.
The snippet generator is all Proboscis (sorry) but this means it will fit in with all the tests run with run_tests.py (yay!). We can have it write the snippets to apidocs/src/samples, meaning if something changes due to work by a developer they'll know it and have to check it in to avoid errors in the gate. This will ensure we don't change our API unless we really want to. :)
Here's the breakdown of the work:
- Add snippet generator to tests, let it run every time.
- This is tangential but we'll probably want to remove all the XML snippets, as well as all mention of XML from the docs, to help with this next part:
- In its current form, the snippet generator doesn't generate all snippets (there have been more created since we last updated it) so we'll have to add additional generated snippets until finally *all* the snippets are generated.
Public API
No changes- except our contract will be even less likely to change.
CLI interface
No changes.
ReST Part
No changes.
Internal API
No changes.
RPC API description
No changes.
Guest Agent
No changes.
