Fork 0
Go to file
Pascal Abresch 71b9a571ab fix minor mistakes
Signed-off-by: Pascal Abresch <nep@packageloss.eu>
2020-04-04 04:59:16 +02:00
.buildkite Trigger matrix.org rebuild 2019-05-07 00:11:14 +01:00
.circleci update to the new deployment of Giles 2019-09-04 14:12:38 +01:00
.github Add some github stuff (PR templates, funding) 2019-12-07 15:57:24 -07:00
api Fix spelling mistakes. 2020-01-18 09:09:42 -06:00
attic Consistently spell homeserver as homeserver 2015-12-02 19:23:33 +00:00
changelogs Add changelog for spelling. 2020-01-18 14:12:24 -06:00
data-definitions Spec SAS verification and the common key verification framework 2019-06-04 12:43:47 -06:00
drafts Use example.org on examples instead of domain.com which is a real domain 2018-09-02 17:58:21 +03:00
event-schemas Merge pull request #2258 from matrix-org/travis/spec/is-terms 2019-09-06 10:29:47 -06:00
meta remove some lies about markdown being bad (#2337) 2019-11-01 14:05:54 +00:00
proposals fix minor mistakes 2020-04-04 04:59:16 +02:00
schemas Fix indentation and schema references in the identity service spec 2018-08-24 15:53:27 -06:00
scripts Merge remote-tracking branch 'remotes/origin/master' into kitsune-map-to-enum-support 2019-10-03 11:06:27 +09:00
specification Fix link to v4 event ID format in identity service spec 2020-01-02 02:30:29 -06:00
.gitignore Add .vscode to .gitignore 2019-01-10 12:18:22 +00:00
CONTRIBUTING.rst We're stable now 🎉 2019-06-12 18:09:15 -06:00
LICENSE Add a license to the spec 2016-07-12 17:28:30 +01:00
README.rst add missing github-labels file 2019-08-30 13:50:00 +01:00
pyproject.toml update to the new deployment of Giles 2019-09-04 14:12:38 +01:00


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
- ``changelogs``: change logs for the various parts of the
- ``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
- ``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.


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

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

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 shell 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

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
* 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
* You can host the swagger UI yourself. See
  https://github.com/swagger-api/swagger-ui#how-to-run for advice on how to do

.. _`Swagger`: http://swagger.io/


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

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`_,

  source env/bin/activate
  go run ./scripts/continuserv/main.go

You will then be able to view the generated spec by visiting

Issue tracking

Issues with the Matrix specification are tracked in `GitHub

See `meta/github-labels.rst <meta/github-labels.rst>`_ for notes on what the labels mean.