From 56c3e5a62779430843e84e4994db76b3ced4f51a Mon Sep 17 00:00:00 2001 From: Richard van der Hoff Date: Wed, 25 Oct 2017 09:57:02 +0100 Subject: [PATCH] README.rst: Add notes on how to build the spec --- README.rst | 61 +++++++++++++++++++++++++++++++++++++++++++++++ api/README | 3 +-- scripts/README.md | 45 ---------------------------------- 3 files changed, 62 insertions(+), 47 deletions(-) delete mode 100644 scripts/README.md diff --git a/README.rst b/README.rst index edd620fa..0fef5d1a 100644 --- a/README.rst +++ b/README.rst @@ -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 ``_. +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 ============== diff --git a/api/README b/api/README index 01b0958b..7b971fac 100644 --- a/api/README +++ b/api/README @@ -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. diff --git a/scripts/README.md b/scripts/README.md deleted file mode 100644 index 5178d5b7..00000000 --- a/scripts/README.md +++ /dev/null @@ -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://\?url=api-docs.json - -[1] http://swagger.io/ -[2] https://nixos.org/nix/