matrix-spec-proposals/scripts/README.md

Generating the HTML for the specification
=========================================

Requirements:
 - docutils (for converting RST to HTML)
 - Jinja2 (for templating)
 - PyYAML (for reading YAML files)

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/
Script to serve the generated swagger JSON We need custom CORS headers to serve the swagger JSON, so add a script to do it 9 years ago			`Generating the HTML for the specification`
			`=========================================`

			`Requirements:`
			`- docutils (for converting RST to HTML)`
			`- Jinja2 (for templating)`
Add PyYAML to scripts/README.md PyYAML is a 3rd-party package used by `gendoc.py`. 9 years ago			`- PyYAML (for reading YAML files)`
Script to serve the generated swagger JSON We need custom CORS headers to serve the swagger JSON, so add a script to do it 9 years ago
			`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`
Update README.md escape angle-bracket to stop it getting lost in markdown 9 years ago			`* View the UI via your browser at http://\<hostname>?url=api-docs.json`
Script to serve the generated swagger JSON We need custom CORS headers to serve the swagger JSON, so add a script to do it 9 years ago
			`[1] http://swagger.io/`