Usergrid documentation is written in Markdown (*.md) and RST (.rst) formats and we use the Python based Sphinx-Docs documentation system to transform our Markdown and RST files to HTML format.
Sphinx requires Python and pip. Once you have Python, you can install sphinx and pip like so:
$ sudo easy_install pip $ sudo pip install sphinx==1.3.2
Sphinx runs via a Makefile in this, the docs directory. So, cd to this directory and make html:
cd $usergrid/docs make clean html
Find the Markdown (.md) or reST (.rst) files that you need to change, edit them and then run make clean html to generate the HTML into the target/html directory, where you can preview your changes.
Note that Sphinx's native format is reStructuredText (RST) and not Markdown. This causes some issues. For example, using Sphinx directives in Markdown files sometimes works and sometimes does not. RST is a different format than Markdown and it has a different set of directives, some very useful for organizing a large set of documentation files.
The Table of Contents for the documentation is in index.rst, which ties everything together with a series of RST toctree directives. All other files should be written in Markdown, unless they need some special RST directives that will not work in Markdown.
A note about tables. Markdown and reST do not have very good table support. Simple tables are easy to do and you can find examples (e.g. connecting-entities.md) but for tables with multiple lines in each cell, you'll probably want to use a raw HTML table, and there are plenty of examples of that around too.
First you generate the HTML for the docs from the Markdown and reST sources like so:
cd $usergrid/docs make clean html
To update the Usergrid website you must copy the udpated docs files from target/html directory to the website directory at the root of the Usergrid project, i.e. ${usergrid-project-dir}/website/docs.
You can do this by running the script update-website.sh.
Once you've done that then you should follow the instructions in the website/README.md file, which explains how to update the website.
The REST API documentation in rest-endpoints/api-docs.md is generated from a Swagger file in the directory src/main/resources, so DO NOT edit that file directly.
If you need to update the REST API docs, you should edit the usergrid-swagger.yaml file and then re-generate the file.
If you need to change the formatting of the REST API docs, then you will need to edit the Mustache templates in src/main/resource and you may need to edit the Groovy script that does the generation: src/main/groovy/usergrid.ApiDocGenerator.
You will need:
NOTE: Mustache.hava is not in Maven Central so unfortunately, you will have to Git Clone Mustache.java before you can run the generation script.
This is the command to run the generation:
groovy src/main/groovy/usergrid/ApiDocGenerator.groovy
The script will update the file rest-endpoints/api-docs.md and when you are happy with your update you should commit and push that file with Git.