wholetrans/docs-matrix-spec
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity
docs-matrix-spec/scripts
History
Richard van der Hoff 0546f0917d Replace hacky shell to do matrix styling with hacky perl 
Since the shell just wrapped three invocations of perl, we might as well do
it all in perl.
2016-05-04 00:01:54 +01:00
..
continuserv Continuserv: Reduce number of watches 2016-04-11 23:21:21 +01:00
css Enable syntax highlighting for example http requests 2015-10-26 17:25:33 +00:00
speculator speculator: Allow access token to be specified 2016-02-15 14:48:26 +00:00
add-matrix-org-stylings.pl Replace hacky shell to do matrix styling with hacky perl 2016-05-04 00:01:54 +01:00
dump-swagger.py Add securityDefintions to generated swagger JSON 2016-05-03 13:57:16 +01:00
gendoc.py Speed up gendoc.py by only running build.py once 2016-01-08 00:40:03 +00:00
README.md Script to serve the generated swagger JSON 2016-05-03 12:04:44 +01:00
swagger-http-server.py Script to serve the generated swagger JSON 2016-05-03 12:04:44 +01:00

README.md

Generating the HTML for the specification

Requirements:

  • docutils (for converting RST to HTML)
  • Jinja2 (for templating)

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/