Replace the current stack of hugo templates with a towncrier invocation. The main advantage of this is that it means that the "Changes since last release" section is consistent with the changelogs for the actual releases.
This also changes the release process so that the changelog is generated before tagging, which means that the thing tagged v1.5 is actually the v1.5 spec.
Fixes#908.
* Remove extra pyprojects and update changelog docs
* Add script for rendering the changelog
* Add docs for how to release the spec
* Move legacy changelogs out of the way
* Inline resolve_references in dump-swagger
Since this is the only bit of the old templating system we still use, let's
inline it.
OrederedLoader and OrderedDict are now redundant, because all dicts in Python
preserve insertion order.
* Remove the old templating system
We've now replaced the old templates with hugo, so we can get rid of this mess.
PyYAML 6.0 was released yesterday, and it finally drops support for `yaml.load`
without a `loader` argument, which has been deprecated since 2017.
We don't use any fancy yaml objects, so `safe_load` should be fine.
* Introduce a new "added-in" template and use it on endpoints
* Use "added-in" on schema properties too
* Annotate sections of the spec with their added versions
* Demo of "added-in" on a room version (to be fleshed out)
* Use clearer versioning semantics
* Update and fix validator for Swagger custom properties
* Fix docs
This PR attempts to update the CI of matrix-doc to build [the new spec redesign](https://github.com/matrix-org/matrix-doc/issues/2906). It does so by additionally building the new spec in parallel to the old. The plan is to continue to host the old spec at https://matrix.org/docs/spec, while the new spec will be at https://spec.matrix.org. Eventually we will retire the old version of the spec, and have the old URL redirect to the new one.
In detail, this PR:
* Adds a new step to CircleCI to build the new spec with `hugo`. This step uses alpine, grabs some dependencies, and then builds the HTML.
* We needed to hand some specific options to hugo for CircleCI in order to continue allowing CircleCI to host temporary builds of the spec after each CI run. This required changing some assumptions related to relative paths.
* CircleCI's artifacts hosting is also quite limited. Specifically it will not automatically resolve `/some/path` to `/some/path/index.html`, which our hugo theme relied on. Fixes were implemented for this, but we may want to consider switching away from CircleCI artifacts as a host, and using something like [netlify](https://www.netlify.com/) instead.
* Modifies the existing Buildkite pipeline step to build both the new spec in a separate step. It additionally modifies the old spec to be built with alpine. (Separate out into another PR)
* We'd like to separate out the deployment of matrix.org from the new spec. Therefore a new step, with a separate artifact build (`spec.tar.gz`). We will eventually remove the old step and the matrix.org build trigger.
* Modifies `pyproject.toml` to update the config of [giles](https://github.com/OpenAstronomy/baldrick/blob/master/baldrick/plugins/circleci_artifacts.py), which is what creates the "docs", "swagger" links in the CI steps for matrix-docs PRs.
* A new step was added for the new spec. The old spec was renamed to "legacy".
Historical note: this was originally a series of several commits, spread out
over several weeks. They have been squashed together to make `git annotate`
work properly.
The original commits were:
* 91ab3934 <Will> 2021-01-25 21:16:42 -0800 Add raw API end event schemas into /data directory
* aae22f47 <Will> 2021-01-25 21:33:06 -0800 Remove non-data files
* 1092d4ca <Will> 2021-01-26 20:41:33 -0800 Add data-compatiuble extension (.yaml) to all data files that currently omit one
* 21060109 <Will> 2021-01-26 20:57:28 -0800 Remove symlink to event-schemas, and update openAPI schema paths accordingly
* 4f633845 <Travis Ralston> 2021-04-12 21:54:54 -0600 Fix event schema examples too
* 301c7b2f <Will> 2021-02-05 10:15:42 -0800 Restore docs describing OpenAPI extensions that we use
check-swagger-sources also had a bug which caused it to fail while validating the directory
structure of /data/api. This was fixed by @KitsuneRal - thank you!
* add a base file
* Fix directory name
* Added translation using Weblate (English)
* Translated using Weblate (English)
Currently translated at 1.6% (1 of 64 strings)
Translation: matrix-doc/SAS Emoji v1
Translate-URL: https://translate.riot.im/projects/matrix-doc/sas-emoji-v1/en_EN/
* add english files
* delete english files
* Added translation using Weblate (English)
* Added translation using Weblate (English)
* Do manual translations
* Deleted translation using Weblate (English)
* Deleted translation using Weblate (English)
* Add a script to update the definitions with the translations
* update i18n
* Add a note to the spec about translations
* changelog
* Ensure translations end with json
MSC: https://github.com/matrix-org/matrix-doc/pull/2209
The changes are slightly difficult to word without dumping the text in and playing a game of spot the difference, so we now use our pre-existing pygments support to render a representation of the difference. The difference is shown in markdown-like format instead of RST for ease of understanding. It's also not rendered HTML for largely complexity reasons.
Travis Ralston