How to Write Documentation for Kazoo!#
Consistency in documentation is a win for everyone, including your future self. Write the docs! We're here to help.
What we're looking for when evaluating documentation:
When writing top-level application docs, we're looking for:
- Basics of API usage
- Commonalities among all endpoints
- ASCII Art of various Erlang process trees, FSM transitions, etc
- SUP commands available
When writing docs for API endpoints, we'd like to strive for:
- Example request/response formats
- As many as needed to demonstrate usage
- Keep it terse - no storytelling needed. Just the facts ma'am!
- Suggested use cases (brief)
- Bullet list of common ways to use the API
- Links to user guides or tutorials of why to use this endpoint
- Common pitfalls when using the endpoint
- Conflicting settings to watch out for
- Put all endpoint documentation in
It would be great to have:
Aboutsection briefly describing the endpoint
- Descriptions of the relevant fields (defined in the schema for the resource)
- Listing of URI segments available, with HTTP methods
- Differences between versions of the endpoint, if any
Reference Template Markdown File#
A Reference Template for all Crossbar API can be generate by parsing the Erlang source file of the APIs. This is done by Kazoo AST
cb_api_endpoint module and is run every time in CI to make sure the template is updated and alerts developers there has been a change that need to be documented.
cb_api_endpoint is uses Erlang functionality to generate an Erlang Abstract Syntax Tree (AST) of the source code. It looks for
resource_exists of each API endpoint to extract what HTTP methods are implemented by the endpoint, and generates a basic reference markdown file for the endpoint with some boilerplate cURL command usage. Also if the endpoint is using JSON schema, it prints it as table in the reference template.
You can use
make apis on root of the project to run all Kazoo AST modules (which extracting various data from Erlang source files). API reference templates generated by
cb_api_endpoint are in
applications/crossbar/doc/ref directory. Simply copy the to
doc directory of Crossbar and add your documentation in this file.
You have to run
make apis every time you make an update to any JSON schema (whether it is for endpoint, or system config, or FreeSWITCH or etc...).
JSON Schema of endpoint documentations (those files in root of
applications/crossbar/doc) are not update automatically. It is advised after you update the JSON schema, run
make apis and copy paste the schema part of the ref doc into the actual endpoint documentation file.
cb_api_endpoint is generating the AST from BEAM file, it is possible some time that BEAM file is not up to date. This would maybe results in generating outdated JSON schema files and Swagger file.
cb_api_endpoint also generates/updates the Swagger file.
Automatic JSON Schema generator#
These tools are not necessary for documentation, but are helping to generating schemas to use by Kazoo applications and generates API endpoints ref docs.
generate-api-endpoints.escript: Builds the Crossbar reference docs in 'applications/crossbar/doc/ref'. Helps detect when Crossbar endpoints have changes to their functionality that is client-facing.
generate-doc-schemas.py: Updates crossbar docs with the schema table from the ref (auto-gen) version
generate-schemas.escript: Parses the core/applications code looking for calls to
kapps_config(module used to access documents in the
system_configdatabase) and building a base JSON schema file for each document found. Also parses callflow's action modules looking for keys used to access values in the Data JSON object to build a base JSON schema file for each callflow action.
format-json.py: Python script to format JSON files (like CouchDB views, JSON schemas) and write the formatted version back to the file. 'make apis' runs this as part of its instructions.