You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
144 lines
5.2 KiB
ReStructuredText
144 lines
5.2 KiB
ReStructuredText
This repository contains the Matrix specification.
|
|
|
|
If you want to ask more about the specification, join us on
|
|
`#matrix-dev:matrix.org <http://matrix.to/#/#matrix-dev:matrix.org>`_.
|
|
|
|
We welcome contributions to the spec! See the notes below on `Building the
|
|
specification`_, and `<CONTRIBUTING.rst>`_ to get started making contributions.
|
|
|
|
Note that the Matrix Project lists, which were previously kept in this
|
|
repository, are now in https://github.com/matrix-org/matrix.org.
|
|
|
|
Structure of this repository
|
|
============================
|
|
|
|
- ``api`` : `OpenAPI`_ (swagger) specifications for the the HTTP APIs.
|
|
- ``attic``: historical sections of specification for reference
|
|
purposes.
|
|
- ``changelogs``: change logs for the various parts of the
|
|
specification.
|
|
- ``drafts``: Previously, contained documents which were under discussion for
|
|
future incusion into the specification and/or supporting documentation. This
|
|
is now historical, as we use separate discussion documents (see
|
|
`<CONTRIBUTING.rst>`_).
|
|
- ``event-schemas``: the `JSON Schema`_ for all Matrix events
|
|
contained in the specification, along with example JSON files.
|
|
- ``meta``: documents outlining the processes involved when writing
|
|
documents, e.g. documentation style, guidelines.
|
|
- ``scripts``: scripts to generate formatted versions of the
|
|
documentation, typically HTML.
|
|
- ``specification``: the specification split up into sections.
|
|
|
|
.. _OpenAPI: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md
|
|
.. _JSON Schema: http://json-schema.org/
|
|
|
|
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 3.4+ virtualenv as follows::
|
|
|
|
virtualenv -p python3 env
|
|
env/bin/pip install -r scripts/requirements.txt
|
|
|
|
(Benjamin Saunders 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``.
|
|
|
|
Windows users
|
|
~~~~~~~~~~~~~
|
|
The ``source`` program does not exist on Windows, so instead run one of the
|
|
``activate`` files in ``.\env\Scripts\`` to activate the virtual environment.
|
|
|
|
If you're on Windows Vista or higher, be sure that the "Symbolic Links"
|
|
option was selected when installing Git prior to cloning this repository. If
|
|
you're still seeing errors about files not being found it is likely because
|
|
the symlink at ``api/client-server/definitions/event-schemas`` looks like a
|
|
file. To correct the problem, open an Administrative/Elevated Command Prompt in your
|
|
cloned matrix-doc directory and run the following::
|
|
|
|
cd api\client-server\definitions
|
|
del event-schemas
|
|
mklink /D event-schemas "..\..\..\event-schemas"
|
|
|
|
This will delete the file and replace it with a symlink. Git should not detect
|
|
this as a change, and you should be able to go back to building the project.
|
|
|
|
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
|
|
./scripts/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/
|
|
|
|
Continuserv
|
|
-----------
|
|
|
|
Continuserv is a script which will rebuild the specification every time a file
|
|
is changed, and will serve it to a browser over HTTP. It is intended for use by
|
|
specification authors, so that they can quickly see the effects of their
|
|
changes.
|
|
|
|
It is written in Go, so you will need the ``go`` compiler installed on your
|
|
computer. You will also need to install fsnotify by running::
|
|
|
|
go get gopkg.in/fsnotify/fsnotify.v1
|
|
|
|
Then, create a virtualenv as described above under `Preparation`_,
|
|
and::
|
|
|
|
source env/bin/activate
|
|
go run ./scripts/continuserv/main.go
|
|
|
|
You will then be able to view the generated spec by visiting
|
|
http://localhost:8000/index.html.
|
|
|
|
Issue tracking
|
|
==============
|
|
|
|
Issues with the Matrix specification are tracked in `GitHub
|
|
<https://github.com/matrix-org/matrix-doc/issues>`_.
|
|
|
|
See `meta/github-labels.rst <meta/github-labels.rst>`_ for notes on what the labels mean.
|