wholetrans/docs-matrix-spec
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

README.rst: Add notes on how to build the spec

Browse source
This commit is contained in:
Richard van der Hoff 2017-10-25 09:57:02 +01:00
parent 834a3d78a8
commit 56c3e5a627
3 changed files with 62 additions and 47 deletions
Download patch file Download diff file Expand all files Collapse all files

61
README.rst
View file

@ -41,6 +41,67 @@ If you want to ask more about the specification, join us on
If you would like to contribute to the specification or supporting
documentation, see `<CONTRIBUTING.rst>`_.
Building the specification
==========================
The Matrix Spec is generated by a set of scripts, from the RST documents, API
specs and event schemas in this repository.
Preparation
-----------
To use the scripts, it is best to create a Python virtualenv as follows::
virtualenv env
env/bin/pip install -r scripts/requirements.txt
(Benjamin Synders has contributed a script for `Nix`_ users, which can be
invoked with ``nix-shell scripts/contrib/shell.nix``.)
.. TODO: Possibly we need some libs installed; should record what they are.
.. _`Nix`: https://nixos.org/nix/
Generating the specification
----------------------------
To rebuild the specification, use ``scripts/gendoc.py``::
source env/bin/activate
./scripts/gendoc.py
The above will write the rendered version of the specification to
``scripts/gen``. To view it, point your browser at ``scripts/gen/index.html``.
Generating the OpenAPI (Swagger) specs
--------------------------------------
`Swagger`_ is a framework for representing RESTful APIs. We use it to generate
interactive documentation for our APIs.
Before the Swagger docs can be used in the Swagger UI (or other tool expecting
a Swagger specs, they must be combined into a single json file. This can be
done as follows::
source env/bin/activate
./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
``./scripts/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. See
https://github.com/swagger-api/swagger-ui#how-to-run for advice on how to do
so.
.. _`Swagger`: http://swagger.io/
Issue tracking
==============

3
api/README
View file

@ -1,3 +1,2 @@
This directory contains swagger-compatible representations of our APIs. See
scripts/README.md for details on how to make use of them.
the main README.rst for details on how to make use of them.

45
scripts/README.md
View file

@ -1,45 +0,0 @@
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:
* 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/
[2] https://nixos.org/nix/