Cut over to the new spec authoring platform

CONTRIBUTING.rst

@@ -103,7 +103,7 @@ the ``newsfragments`` directory. The ``type`` can be one of the following:
 
 All news fragments must have a brief summary explaining the change in the
 contents of the file. The summary must end in a full stop to be in line with
-the style guide and and formatting must be done using Markdown.
+the style guide and formatting must be done using Markdown.
 
 Changes that do not change the spec, such as changes to the build script, formatting,
 CSS, etc should not get a news fragment.

README.md

@@ -2,10 +2,11 @@
 
 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)
+Developers looking to use Matrix should join [#matrix-dev:matrix.org](https://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.
+Spec authors and proposal writers are welcome to join [#matrix-spec:matrix.org](https://matrix.to/#/#matrix-spec:matrix.org). 
+We welcome contributions! See [CONTRIBUTING.rst](./CONTRIBUTING.rst) for details.
 
 ## Structure
 
@@ -21,7 +22,7 @@ The Matrix spec is compiled with [Hugo](https://gohugo.io/) (a static site gener
 
 * `/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 
+  parse them. This is also where our Swagger/OpenAPI definitions are.
 
 * `/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.
@@ -35,8 +36,8 @@ The Matrix spec is compiled with [Hugo](https://gohugo.io/) (a static site gener
 
 * `/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 
+  versions of any of the theme 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 the 
   template will be used.
 
 It also has the following top-level file:
@@ -51,7 +52,7 @@ Additionally, the following directories may be of interest:
 * `/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.
+* `/scripts`: Various scripts for generating the spec and validating its contents.
 * `/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.
@@ -64,7 +65,8 @@ 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.
+4. Run `npm run get-proposals` to seed proposal data. This is merely for populating the content of the "Spec Change Proposals"
+   page and 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 🙂
@@ -75,18 +77,18 @@ Awesome. If you're looking at making design-related changes to the spec site, pl
 
 ## 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.
+If for some reason you're not a CI/CD system and want to render a static version of the spec for 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:
+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/
+* It can be uploaded from your filesystem to an online editor/viewer such as [on the swagger website](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>
+  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.
 

meta/documentation_style.rst

@@ -8,7 +8,7 @@ in.
 Format
 ------
 
-Documentation is written either in github-flavored markdown.
+Documentation is written in github-flavored markdown.
 
 Sections
 --------

pyproject.toml

@@ -1,9 +1,5 @@
 [ tool.gilesbot ]
 
-  [ tool.gilesbot.circleci_artifacts.legacydocs ]
-    url = "gen/index.html"
-    message = "Click details to preview the legacy HTML documentation."
-
   [ tool.gilesbot.circleci_artifacts.docs ]
     url = "public/index.html"
     message = "Click details to preview the HTML documentation."

scripts/speculator/main.go

@@ -337,7 +337,7 @@ func (s *server) serveSpec(w http.ResponseWriter, req *http.Request) {
 		log.Printf("Serving pr %s (%s)\n", branchName, sha)
 	} else if strings.ToLower(branchName) == "head" ||
 		branchName == "master" ||
-		strings.HasPrefix(branchName, "drafts/") {
+		strings.HasPrefix(branchName, "attic/drafts/") {
 		branchSHA, err := s.lookupBranch(branchName)
 		if err != nil {
 			writeError(w, 400, err)