You cannot select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
matrix-spec-proposals/scripts
Richard van der Hoff 1320a86cbe Serve the api docs from the speculator
There are a few parts to this:

* when we generate the spec for a particular git sha, also run the script which
  turns our yaml api descriptions into a swagger json file.

* tweak serveSpec to add another header when serving the generated json.

* add a link to the generated index which will (via js hackery) redirect to our
  hosted swagger UI at http://matrix.org/docs/api/client-server, with a "url"
  query-param pointing at the generated json.

Also, factor makeTempDir out of gitClone, so that we can give clearer log lines.
8 years ago
..
continuserv Put each bit of spec in its own directory 9 years ago
contrib Add a nix-shell environment suitable for building 8 years ago
css Enable syntax highlighting for example http requests 9 years ago
speculator Serve the api docs from the speculator 8 years ago
README.md Add a nix-shell environment suitable for building 8 years ago
add-matrix-org-stylings.pl Replace hacky shell to do matrix styling with hacky perl 9 years ago
dump-swagger.py Add a license to the spec 8 years ago
gendoc.py Remove howtos from build script 8 years ago
swagger-http-server.py swagger-http-server: add a --port argument 8 years ago

README.md

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:

[1] http://swagger.io/ [2] https://nixos.org/nix/