This repository contains the documentation for Matrix.
Primarily, that means the Matrix protocol specifcation, but this repo also comtains a lot of supporting documents, including some introductions to Matrix, and, notably, a list of projects using Matrix which is visible on the matrix.org website.
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.supporting-docs: additional documents which explain design decisions, examples, use cases, etc.templating: the templates and templating system used to generate the spec.
Contributing
If you want to ask more about the specification, join us on #matrix-dev:matrix.org.
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.)
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.
Issue tracking
Issues with the Matrix specification and supporting documentation are tracked in GitHub.
The following labels are used to help categorize issues:
spec-omission
Things which have been implemented but not currently specified. These may range from entire API endpoints, to particular options or return parameters.
Issues with this label will have been implemented in Synapse. Normally there will be a design document in Google Docs or similar which describes the feature.
Examples:
clarification
An area where the spec could do with being more explicit.
Examples:
- Spec the implicit limit on /syncs
- Clarify the meaning of the currently_active flags in presence events
bug
Something which is in the spec, but is wrong.
Note: this is not for things that are badly designed or don't work well (for which see 'improvement' or 'feature') - it is for places where the spec doesn't match reality.
Examples:
improvement
A suggestion for a relaatively simple improvement to the protocol.
Examples:
- We need a 'remove 3PID' API so that users can remove mappings
- We should mandate that /publicRooms requires an access_token
feature
A suggestion for a significant extension to the matrix protocol which needs considerable consideration before implementation.
Examples:
projects
A project which needs adding to the 'Try Matrix Now' page.
Examples:
- add https://gitlab.com/uhoreg/matrix-appservice-prosody
- add https://github.com/tavoda/matrix-java project
site
Ideas for things to help document or sell matrix more generally. (Probably these would be better filed under https://github.com/matrix-org/matrix.org, but they tend to end up here.)