I've been working on updating the Usergrid docs for 2.0 and the first step step of that task is to complete the conversion of Usergrid docs from HTML from Apigee to Markdown files suitable for the Sphinx documentation system.
I am now done with the initial conversion (except for Push Notifications) and would like to share what I've done in hope of getting some feedback and possibly some advice about Sphinx. What I've done so far: 1. Completed converting Usergrid docs from HTML to Markdown. Consider this a complete first draft, it's badly in need of review: http://usergrid.incubator.apache.org/docs/ 2. Updated the README to explain how to update the docs: https://github.com/apache/incubator-usergrid/blob/master/docs/README.md 3. Added a Swagger file for the Usergrid API and a Groovy script and Mustache templates to generate Markdown method and model documentation. The Swagger file is in need of review and some reorganization. Groovy script and templates here: https://github.com/apache/incubator-usergrid/tree/master/docs/src/main Generated API reference is here: http://usergrid.incubator.apache.org/docs/rest-endpoints/api-docs.html I'm not that happy with the formatting of the above API reference -- making it look good is difficult due to Sphinx and Markdown limitations. 4. Updated README to better explain how to update our Website: https://github.com/apache/incubator-usergrid/blob/master/website/README.md There is still a lot more work to be done. The converted docs that I created only include curl examples, but we have examples for iOS, Android, Node.js and JavaScript. We need to create documentation for each SDK with those examples and ideally we should make those examples testable as part of the SDK process. Also: we need review. If you have time, please review the process and/or the docs and get your feedback (or pull requests to me). Thanks, Dave
