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 8aa0f64665 Update the speculator to understand spec subdirs 
Fix the speculator so that it doesn't blow up when it finds subdirs in the gen
directory.

(It doesn't handle the html diff very well in the case that the subdirs don't
match, but it's hard to do much about that)
2016-05-05 18:46:29 +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 Update the speculator to understand spec subdirs 2016-05-05 18:46:29 +01: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/