|
|
|
|
Generating the HTML for the specification
|
|
|
|
|
=========================================
|
|
|
|
|
|
|
|
|
|
Requirements:
|
|
|
|
|
- docutils (for converting RST to HTML)
|
|
|
|
|
- Jinja2 (for templating)
|
|
|
|
|
- PyYAML (for reading YAML files)
|
|
|
|
|
|
|
|
|
|
Nix[2] users can enter an environment with the appropriate tools and
|
|
|
|
|
dependencies available by invoking `nix-shell contrib/shell.nix` in this
|
|
|
|
|
directory.
|
|
|
|
|
|
|
|
|
|
To generate the complete specification along with supporting documentation, run:
|
|
|
|
|
python gendoc.py
|
|
|
|
|
|
|
|
|
|
The output of this will be inside the "scripts/gen" folder.
|
|
|
|
|
|
|
|
|
|
Matrix.org only ("gen" folder has matrix.org tweaked pages):
|
|
|
|
|
./matrix-org-gendoc.sh /path/to/matrix.org/includes/nav.html
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Generating the Swagger documentation
|
|
|
|
|
====================================
|
|
|
|
|
Swagger[1] is a framework for representing RESTful APIs. We use it to generate
|
|
|
|
|
interactive documentation for our APIs.
|
|
|
|
|
|
|
|
|
|
Swagger UI reads a JSON description of the API. To generate this file from the
|
|
|
|
|
YAML files in the `api` folder, run:
|
|
|
|
|
./dump-swagger.py
|
|
|
|
|
|
|
|
|
|
By default, `dump-swagger` will write to `scripts/swagger/api-docs.json`.
|
|
|
|
|
|
|
|
|
|
To make use of the generated file, there are a number of options:
|
|
|
|
|
* It can be uploaded from your filesystem to an online editor/viewer such as
|
|
|
|
|
http://editor.swagger.io/
|
|
|
|
|
* You can run a local HTTP server by running `./swagger-http-server.py`, and
|
|
|
|
|
then view the documentation via an online viewer; for example, at
|
|
|
|
|
http://petstore.swagger.io/?url=http://localhost:8000/api-docs.json
|
|
|
|
|
* You can host the swagger UI yourself:
|
|
|
|
|
* download the latest release from https://github.com/swagger-api/swagger-ui
|
|
|
|
|
* copy the contents of the 'dist' directory alongside `api-docs.json`
|
|
|
|
|
* View the UI via your browser at http://\<hostname>?url=api-docs.json
|
|
|
|
|
|
|
|
|
|
[1] http://swagger.io/
|
|
|
|
|
[2] https://nixos.org/nix/
|
