Skip to content

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.

Rubric#

What we're looking for when evaluating documentation:

Top-level#

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

Per-endpoint#

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 applications/crossbar/doc directory.

API Descriptions#

It would be great to have:

  • An About section briefly describing the endpoint
  • Descriptions of the relevant fields (defined in the schema for the resource)
  • Listing of URI segments available, with HTTP methods
  • Code sample for at least a cURL command; bonus points if you include PHP/Python/Javascript SDK equivalents.
  • 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.

Note

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...).

Warning

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.

Note

Since 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.

Note

cb_api_endpoint also generates/updates the Swagger file.

Tools used#

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_config database) 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.