xeronith/matrix-doc

Matrix Documentation (including The Spec)

This repository contains the Matrix specification.

If you want to ask more about the specification, join us on #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.

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 Synders has contributed a script for Nix users, which can be invoked with nix-shell scripts/contrib/shell.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.

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.

See meta/github-labels.rst for notes on what the labels mean.