Documentation

Documentation of the generator and related infrastructure is hosted under docs. Static html documentation is build from the latest master branch by the CI. We use mkdocs together with the material theme. Before building the documentation, make sure you have the required dependencies installed:

pip install -r docs/requirements.txt

After everything is installed, you can build and serve a local copy by executing (in the root directory):

mkdocs serve

This opens a local webserver listening on http://127.0.0.1:8000/.

Organization

The docs folder is organized as follows:

• rm: Reference manuals, listings and detailed design decisions.
• ug: User guides, more tutorial style texts to get contributors and user up-to-speed.
• schema: Contains the JSON schema used for data validation and generation.
• schema-doc: Contains auto-generated documentation from the schema in the schema folder. The documentation is generated using adobe/jsonschema2md.

Re-generate Documentation

Unfortunately, there isn't a good Python tool that generates schema to markdown documents, hence, we rely on adobe/jsonschema2md which requires node and npm. To re-generate the documentation execute (in the repository root):

jsonschema2md -d docs/schema/ -o docs/schema-doc -n