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 01f8173c84 Put each bit of spec in its own directory 
I want to change the URLs for the spec sections on the website from
<version>/<section>.html to <section>/<version>.html, to better reflect how we
do the versioning.

This puts each bit of spec in its own directory, updates the index to point to
the right place, and fixes continuserv to deal with directories as well as
files.

This will probably require fixes to the speculator too, but I'll have to come
back to that.
2016-05-05 18:26:17 +01:00
..
continuserv Put each bit of spec in its own directory 2016-05-05 18:26:17 +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 Put each bit of spec in its own directory 2016-05-05 18:26:17 +01:00
README.md Update README.md 2016-05-04 01:08:50 +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/