Rewrite readme and update contributor docs
Incorporates https://github.com/matrix-org/matrix-doc/pull/3025/pull/977/head
Travis Ralston
4 years ago
committed by
Richard van der Hoff
parent
aab72c3d14
commit
52cd88f070
@ -0,0 +1,97 @@
|
|||||||
|
# Matrix Specification
|
||||||
|
|
||||||
|
This repository contains the Matrix Specification, rendered at [spec.matrix.org](http://spec.matrix.org/).
|
||||||
|
|
||||||
|
Developers looking to use Matrix should join [#matrix-dev:matrix.org](http://matrix.to/#/#matrix-dev:matrix.org)
|
||||||
|
on Matrix for help.
|
||||||
|
|
||||||
|
Spec authors and proposal writers are welcome to join [#matrix-spec:matrix.org](http://matrix.to/#/#matrix-spec:matrix.org). We welcome contributions! See [CONTRIBUTING.rst](./CONTRIBUTING.rst) for details.
|
||||||
|
|
||||||
|
## Structure
|
||||||
|
|
||||||
|
The Matrix spec is compiled with [Hugo](https://gohugo.io/) (a static site generator) with the following structure:
|
||||||
|
|
||||||
|
* `/assets`: assets that need postprocessing using [Hugo Pipes](https://gohugo.io/hugo-pipes/introduction/).
|
||||||
|
For example, Sass files would go here.
|
||||||
|
|
||||||
|
* `/content`: files that will become pages in the site go here. Typically these are Markdown files with some YAML front
|
||||||
|
matter indicating, [among other things](https://gohugo.io/content-management/front-matter/), what layout should be
|
||||||
|
applied to this page. The organization of files under `/content` determines the organization of pages in the built
|
||||||
|
site.
|
||||||
|
|
||||||
|
* `/data`: this can contain TOML, YAML, or JSON files. Files kept here are directly available to template code as
|
||||||
|
[data objects](https://gohugo.io/templates/data-templates/), so templates don't need to load them from a file and
|
||||||
|
parse them. This is also where our
|
||||||
|
|
||||||
|
* `/layouts`: this contains [Hugo templates](https://gohugo.io/templates/). Some templates define the overall layout of
|
||||||
|
a page: for example, whether it has header, footer, sidebar, and so on.
|
||||||
|
* `/layouts/partials`: these templates can be called from other templates, so they can be used to factor out
|
||||||
|
template code that's used in more than one template. An obvious example here is something like a sidebar, where
|
||||||
|
several different page layouts might all include the sidebar. But also, partial templates can return values: this
|
||||||
|
means they can be used like functions, that can be called by multiple templates to do some common processing.
|
||||||
|
* `/layouts/shortcodes`: these templates can be called directly from files in `/content`.
|
||||||
|
|
||||||
|
* `/static`: static files which don't need preprocessing. JS or CSS files could live here.
|
||||||
|
|
||||||
|
* `/themes`: you can use just Hugo or use it with a theme. Themes primarily provide additional templates, which are
|
||||||
|
supplied in a `/themes/$theme_name/layouts` directory. You can use a theme but customise it by providing your own
|
||||||
|
versions of any of the them layouts in the base `/layouts` directory. That is, if a theme provides
|
||||||
|
`/themes/$theme_name/layouts/sidebar.html` and you provide `/layouts/sidebar.html`, then your version of this
|
||||||
|
template will be used.
|
||||||
|
|
||||||
|
It also has the following top-level file:
|
||||||
|
|
||||||
|
* `config.toml`: site-wide configuration settings. Some of these are built-in and you can add your own. Config settings
|
||||||
|
defined here are available in templates. All these directories above are configurable via `config.toml` settings.
|
||||||
|
|
||||||
|
Additionally, the following directories may be of interest:
|
||||||
|
|
||||||
|
* `/attic`: Here contains historical sections of specification and legacy drafts for the specification.
|
||||||
|
* `/changelogs`: Various bits of changelog for the specification areas.
|
||||||
|
* `/event-schemas`: [JSON Schema](http://json-schema.org/) definitions for the spec.
|
||||||
|
* `/data-definitions`: Bits of structured data consumable by Matrix implementations.
|
||||||
|
* `/meta`: Documentation relating to the spec's processes that are otherwise untracked (release instructions, etc).
|
||||||
|
* `/scripts`: Various scripts for generating the spec.
|
||||||
|
* `/proposals`: Matrix Spec Change (MSC) proposals. See <https://spec.matrix.org/unstable/proposals/>.
|
||||||
|
* `/api`: [OpenAPI](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md) / Swagger definitions for
|
||||||
|
the spec.
|
||||||
|
|
||||||
|
## Authoring changes to the spec
|
||||||
|
|
||||||
|
Please read [CONTRIBUTING.rst](./CONTRIBUTING.rst) before authoring a change to the spec. Note that spec authoring takes
|
||||||
|
place after an MSC has been accepted, not as part of a proposal itself.
|
||||||
|
|
||||||
|
1. Install the extended version (often the OS default) of Hugo: <https://gohugo.io/getting-started/installing>
|
||||||
|
2. Run `git submodule update --init --recursive` for good measure.
|
||||||
|
3. Run `npm i` to install the dependencies. Note that this will require NodeJS to be installed.
|
||||||
|
4. Run `npm run get-proposals` to seed the proposals data. This is not required.
|
||||||
|
5. Run `hugo serve` to run a local webserver which builds whenever a file change is detected. If watching doesn't appear
|
||||||
|
to be working for you, try `hugo serve --disableFastRender` instead.
|
||||||
|
6. Edit the specification 🙂
|
||||||
|
|
||||||
|
We use a highly customized [Docsy](https://www.docsy.dev/) theme for our generated site, which uses Bootstrap and Font
|
||||||
|
Awesome. If you're looking at making design-related changes to the spec site, please coordinate with us in
|
||||||
|
[#matrix-docs:matrix.org](https://matrix.to/#/#matrix-docs:matrix.org) before opening a PR.
|
||||||
|
|
||||||
|
## Building the specification
|
||||||
|
|
||||||
|
If for some reason you're not a CI/CD system and want to render the spec yourself, follow the above steps for authoring
|
||||||
|
changes to the specification and instead of `hugo serve` run `hugo -d "spec"` - this will generate the spec to `/spec`.
|
||||||
|
If you'd like to serve the spec off a path instead of a domain root (eg: `/unstable`), add `--baseURL "/unstable"` to
|
||||||
|
the `hugo -d "spec"` command.
|
||||||
|
|
||||||
|
For building the swagger definitions, create a python3 virtualenv and activate it. Then run `pip install -r ./scripts/requirements.txt` and finally `python ./scripts/dump-swagger.py` to generate it 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
|
||||||
|
|
||||||
|
Specification issues are tracked on github at <https://github.com/matrix-org/matrix-doc/issues>.
|
||||||
|
|
||||||
|
See [meta/github-labels.rst](./meta/github-labels.rst) for information on what the labels mean.
|
||||||
@ -1,143 +0,0 @@
|
|||||||
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.
|
|
||||||
Loading…
Reference in New Issue