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

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 `<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
 ==============
 

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.

scripts/README.md

@@ -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/