Commit graph

401 commits

Author SHA1 Message Date
Travis Ralston 7d34995ece It's actually an "identity server implementing the Identity Service API"
Also add a note about appservices being special.
2018-08-31 15:35:32 -06:00
Travis Ralston 7ac76fa27c Actually we're going with "identity server" afterall 2018-08-31 15:04:00 -06:00
Richard van der Hoff 8773b9319b
Merge pull request #1599 from matrix-org/benpa/spec-tables-prettier
Benpa/spec tables prettier
2018-08-31 21:40:55 +01:00
Travis Ralston 84a2b7f3c0
Merge pull request #1632 from uhoreg/fix_room_member_state_key
fix handling of multi-line state key descriptions
2018-08-31 14:38:58 -06:00
Ben Parsons c77b505441 capitali[zs]e path parameters 2018-08-31 14:37:47 +01:00
Ben Parsons 778fe2a47a css caption size tweak 2018-08-31 14:29:46 +01:00
Ben Parsons e8afab1fe5 many visual improvements 2018-08-31 13:55:27 +01:00
Travis Ralston 98a445890c Render a warning if the spec is unstable
Fixes https://github.com/matrix-org/matrix-doc/issues/1499

This is done by using magic variables in the RST. The magic variables are generated based on the substitutions available, making them available for use at build-time. 

Magic variables were chosen because it allows people to continue working on the spec and release process without having to worry about removing a chunk of text from the top of the file. Originally, this was attempted by using jinja2 if-statements, however the substitutions are replaced *after* the template is executed, so the condition would never match. 

The format of the variable is to make the templating happy. Using colons or percent signs results in the templator thinking something else is going on, and then complaining about format.
2018-08-30 15:05:50 -06:00
Travis Ralston cee0a5ac7b
Merge pull request #1557 from turt2live/travis/general/r0-prep
Prepare the identity service and server-server APIs for r0
2018-08-30 14:46:35 -06:00
Hubert Chathi a1b1054aa1 fix handling of multi-line state key descriptions 2018-08-30 15:57:09 -04:00
Travis Ralston 2753d24302 Merge remote-tracking branch 'matrix-org/master' into travis/general/r0-prep 2018-08-30 12:17:09 -06:00
Travis Ralston 827033c128 Merge remote matrix-org/master 2018-08-30 11:29:47 -06:00
Richard van der Hoff f649d04ae1
Merge pull request #1626 from matrix-org/rav/encoding
Set the encoding to UTF-8 on all file I/O
2018-08-30 18:11:38 +01:00
Richard van der Hoff 20c9829f56
Merge pull request #1627 from matrix-org/travis/general/dont-build-proposals
Don't generate proposals.rst in Circle CI
2018-08-30 18:10:48 +01:00
Travis Ralston ecd3ce39e5 Don't generate proposals.rst in Circle CI 2018-08-30 10:38:23 -06:00
Richard van der Hoff 4e90b32348 Set the encoding to UTF-8 on all file I/O
Hopefully this will resolve issues with building the spec on systems where the
default encoding is somthing other than UTF-8.
2018-08-30 17:18:07 +01:00
Ben Parsons f1ae872857 light zebra striping for tables 2018-08-30 17:16:45 +01:00
Ben Parsons 9e1d6d7490 sanitise caption handling 2018-08-30 17:01:27 +01:00
Travis Ralston b2092922e8 Don't define a variable for the appservice major version 2018-08-29 21:51:26 -06:00
Travis Ralston a5c3924492 Merge remote matrix-org/master 2018-08-29 21:28:24 -06:00
Travis Ralston c7a228bf7b Don't make the major version a variable
We are likely to want to maintain v1 when we release a v2, so we'll avoid a variable for now.
2018-08-29 19:32:52 -06:00
Travis Ralston e7a69a6a6d Merge remote-tracking branch 'matrix-org/master' into travis/general/r0-prep 2018-08-29 19:29:42 -06:00
Travis Ralston 2ab2f91088 Merge remote-tracking branch 'matrix-org/master' into travis/releases/push-gateway/r0.1.0 2018-08-29 17:54:34 -06:00
Ben Parsons 380a53ecba adjust caption -> smaller, left align 2018-08-29 17:18:37 +01:00
Ben Parsons 989b50a1a0 remove debug string 2018-08-29 16:40:26 +01:00
Ben Parsons 6e0fe70500 make spec tables prettier 2018-08-29 16:38:59 +01:00
Travis Ralston b402608b41 Don't reference the major version for the push gateway specification
If we ever have a v2 endpoint for the push gateway, we'd likely spec it alongside the v1 stuff, updating applicable references elsewhere.
2018-08-28 14:40:14 -06:00
Travis Ralston 4278a9a516 Merge remote-tracking branch 'matrix-org/master' into travis/c2s/fix-events 2018-08-27 19:17:37 -06:00
Travis Ralston fa96d8629b Prepare the appservice spec for an r0 release
This puts the scaffolding in place for an r0 release to happen, such as the changelog and version variables.
2018-08-27 18:04:08 -06:00
Travis Ralston e9e93b0eec Move invite_room_state to the correct place in the client-server API
Fixes https://github.com/matrix-org/matrix-doc/issues/1350
2018-08-26 20:51:39 -06:00
Travis Ralston 0f28f83270 Fix client-server event schemas: remove age, dedupe fields
This commit adds support for event schema examples to have references to help reduce the chance of fields being forgotten. This also helps reduce duplication of fields, allowing for a more consistent spec that uses the same values everywhere.

This also removes both `unsigned` and `age` from the examples as per:
* https://github.com/matrix-org/matrix-doc/issues/1524
* https://github.com/matrix-org/matrix-doc/issues/630

Finally, this replaces "localhost" in the examples with an example domain. This is really just a nitpick thing on my part where seeing a "real world" domain is preferred. 

Fixes https://github.com/matrix-org/matrix-doc/issues/1524
Fixes https://github.com/matrix-org/matrix-doc/issues/630
Step towards https://github.com/matrix-org/matrix-doc/issues/1530
2018-08-24 18:04:51 -06:00
Travis Ralston d370a2c6fd Prepare the identity service and server-server APIs for r0
* Create the changelog scaffolding
* Set up the variables for versioning
2018-08-24 17:19:25 -06:00
Travis Ralston 750d4f9fda Rename the presence EDU files to be accurate to their types; Misc cleanup of titles 2018-08-17 10:53:47 -06:00
Travis Ralston a53fa9300d Merge remote-tracking branch 'matrix-org/master' into travis/s2s/presence 2018-08-17 09:34:16 -06:00
Travis Ralston ba51d5960e r0.1.0 release of the Push Gateway specification
Because this is the first release, it has several moving parts to it:
* The version variables have been defined.
* The towncrier changelog has been prepared for future modifications.
* The templating has been updated to better support future versions of the specification.
* A release process document has been created.
2018-08-16 11:50:18 -06:00
Kitsune Ral 9be78f3aa7 Better support enums when they come among oneOf types 2018-08-12 16:45:35 +09:00
Kitsune Ral 88d97b06ae Support oneOf 2018-08-12 16:45:33 +09:00
Travis Ralston 05a2427c73 Document how presence EDUs work between servers
It's worth noting that Synapse does not make use of the `poll` or `unpoll` fields, and therefore the wording has been updated to permit servers to reject users. In the case of synapse, it would automatically reject everyone in the list by nature of ignoring it.
2018-08-08 08:24:09 -06:00
Travis Ralston 0f8954d839
Merge pull request #1463 from turt2live/travis/s2s/pdus-and-edus
Improve documentation around EDUs and PDUs
2018-08-08 08:02:37 -06:00
Travis Ralston db6d466fa1 Go one level deep when finding definitions
This is useful for when we start defining event schemas. This also has a sanity check for ensuring the directory exists, allowing the IS and push API paths to be uncommented.
2018-08-03 19:49:46 -06:00
Travis Ralston 96f5510266 Ensure the example is always set to something 2018-08-03 12:03:23 -06:00
Travis Ralston ea307b5bdb Support rendering schema definitions in the spec 2018-07-31 13:55:53 -06:00
Ben Parsons 1d019c3757
Merge pull request #1340 from matrix-org/benparsons/prdefence
expect "#<pull-number>" or "/pull/<pull-number>" in PRs field
2018-07-31 15:17:42 +01:00
Ben Parsons d7919b6989 also scrape PRs when the full URL is pasted 2018-07-31 15:08:42 +01:00
Travis Ralston bc3e45d642
Merge pull request #1358 from uhoreg/ignore-emacs-tmp
ignore emacs temporary files
2018-07-30 17:09:08 -06:00
Travis Ralston 4f24d2101f Only get issues that are proposals when finding proposals
Otherwise we end up with not-proposals showing up in the list.
2018-07-26 09:51:08 -06:00
Travis Ralston dcc4b0bfbc Remove Travis CI configuration
We're using Circle CI for testing a bunch of the spec, and so far it has the advantage of being faster. Also, it's not named the same as me.

We can also remove the Travis CI specific check in generate-matrix-org-assets because Circle CI doesn't touch this.
2018-07-24 14:47:47 -06:00
Travis Ralston acf9632afc Enlist the examples 2018-07-24 10:25:24 -06:00
Travis Ralston 9fa838d3e8 Improve type naming 2018-07-24 10:17:57 -06:00
Travis Ralston 5ade15534d Remove extra branch in example generation 2018-07-24 10:17:39 -06:00
Travis Ralston 042772aaf5 Make nested titles better 2018-07-24 10:13:23 -06:00
Travis Ralston cb4fcd1d09 Merge remote-tracking branch 'matrix-org/master' into travis/s2s/transactions-swagger 2018-07-24 09:15:36 -06:00
Travis Ralston a4e5a461f9 Improve handing of lists appearing in items 2018-07-24 09:14:31 -06:00
Travis Ralston 2dae0c9c49 use python3 in dump-swagger.py 2018-07-19 08:54:04 -06:00
Travis Ralston e226b60c7f Merge remote-tracking branch 'matrix-org/master' into travis/s2s/transactions-swagger 2018-07-18 10:59:39 -06:00
Travis Ralston 3ff1b0ddea
Merge pull request #1389 from turt2live/travis/towncrier
Use Towncrier to generate the unstable changelog
2018-07-18 08:27:02 -06:00
Travis Ralston 98c607bff5 Advertise python 3.4 support and use that in Travis CI
We also don't need to update virtualenv, or use python3.5 specific
packages.
2018-07-17 10:28:57 -06:00
Travis Ralston cfac4a1ab3 Use towncrier 18.6.0 final 2018-07-17 08:48:31 -06:00
Travis Ralston e5da1e1741 Improve upon the transaction schema and examples
Reduces data duplication and makes the objects more reusable for other areas of the spec
2018-07-12 21:34:52 -06:00
Travis Ralston 8a4ba8c5ca Use Popen rather than run() 2018-07-12 10:16:32 -06:00
Travis Ralston af7460088f Use six for url quoting 2018-07-12 10:07:09 -06:00
Travis Ralston 374ec00046 Convert things that mention "Transaction" to swagger
There's two kinds of transactions currently: one with EDUs and one without. The one with EDUs is only used on /send, however the schema is still somewhat worth splitting out for simplicity.

The examples are brought apart to make them slightly more reusable for when they get dumped into the relevant sections of the spec (see TODO in server_server_api.rst)

Further, the Transactions stuff introduces tuples to the spec. The units.py has been updated to support this.
2018-07-11 16:52:27 -06:00
Travis Ralston a8461e647f Improve the error handling for towncrier
The changelog shows up via stdout, everything else via stderr. We dump as much information as we can into the changelog to make debugging errors easier.
2018-07-11 08:35:55 -06:00
Travis Ralston 905ef6dadd Have the towncrier generator complain if the output looks wrong 2018-07-10 16:57:21 -06:00
Travis Ralston ebc7db12fb Remove extraneous list casting 2018-07-10 16:52:17 -06:00
Travis Ralston 9e0fafbcd4 Remove debugging line 2018-07-10 15:13:22 -06:00
Travis Ralston 3a9cfd490f
Improve pagination handling in proposals.py
Previously if multiple pages were returned then the script would lose the results. 

A check to ensure the response is an array was also added. This helps avoid somewhat cryptic errors when iterating over non-lists (eg: error messages, bad output, etc)
2018-07-09 23:52:22 -06:00
Travis Ralston 550f95570b Fix regex for some versions of python 2018-07-09 15:17:43 -06:00
Travis Ralston 7ada960206 Fix the Travis CI build to work on 3.5 2018-07-09 14:55:25 -06:00
Travis Ralston 08f6912825 Ask Travis to install 3.5 explicitly 2018-07-09 12:13:58 -06:00
Travis Ralston a4f8e0807a Print the python version being used in the CI build. 2018-07-09 08:41:20 -06:00
Travis Ralston 63b926a4aa Make Travis CI use python 3 2018-07-06 17:19:04 -06:00
Travis Ralston c2f85788de Add documentation about how to add to the changelog 2018-07-06 16:54:14 -06:00
Travis Ralston 9277e4c52d Add initial towncrier support 2018-07-06 16:32:27 -06:00
Travis Ralston f54d5a4039 Convert build scripts to python 3 2018-07-06 15:21:07 -06:00
Travis Ralston 1722734a51
Merge pull request #1364 from turt2live/travis/server-name-join
Document the server_name query parameter on /join/{roomIdOrAlias}
2018-07-06 07:00:24 -06:00
Richard van der Hoff f9a0a49e96 Add a bunch more people to the speculator trusted list 2018-07-05 20:27:40 +01:00
Travis Ralston 4485b2f025
Merge branch 'master' into travis/server-name-join 2018-07-05 11:23:13 -06:00
Travis Ralston 8bd1fe9908
Merge pull request #1357 from turt2live/travis/fix-windows
Use filepath.To/FromSlash instead of manually replacing slashes
2018-07-04 08:09:43 -06:00
Matthew Hodgson d02e9b875b
Merge pull request #1355 from matrix-org/benpa/travisci-ignore-proposals
don't run proposals.py step if in TravisCI environment
2018-07-04 00:04:25 +01:00
Travis Ralston cbbdcbcf01 Show arrays in the query string as "[type]" rather than "array"
Otherwise the question "array of what?" is raised.
2018-07-03 15:50:01 -06:00
Travis Ralston aac7b848f7 Add uhoreg and myself as trusted speculator people 2018-07-03 13:10:28 -06:00
Hubert Chathi a2e0d0382c ignore emacs temporary files
and fix ignoring of dotfiles
2018-07-03 14:10:22 -04:00
Travis Ralston 85e1962f9c Use filepath.To/FromSlash instead of manually replacing slashes
see https://github.com/matrix-org/matrix-doc/pull/1356#discussion_r199897557
2018-07-03 12:07:31 -06:00
Travis Ralston eb21a71b70 Make the builder happier with Windows environments
There's two main issues with Windows environments:
* Slashes
* Windows still notifies about some directories we've ignored, therefore we need to filter them too

It's not super pretty, but it does work.
2018-07-03 10:49:55 -06:00
Ben Parsons 5803c9cace don't run proposals.py step if in TravisCI environment 2018-07-03 15:49:40 +01:00
Ben Parsons e52d94bea9 ignore malformed PR items 2018-06-25 15:00:58 +01:00
user 5ab5fe08d1 Small grammatical and stylistic fixes 2018-06-17 15:49:39 +01:00
Ben Parsons 0c1ba33eba include proposals.py in matrix-doc CI 2018-06-07 14:30:50 +01:00
Ben Parsons ee98082a60 update MSC1270 2018-06-04 12:12:48 +01:00
Ben Parsons cb00fc35ab git checkout master 2018-05-31 15:54:23 +01:00
Ben Parsons d1c27349b2 Merge branch 'master' of https://github.com/matrix-org/matrix-doc 2018-05-31 15:47:34 +01:00
Richard van der Hoff 419bf1e52c Fix continuserv instructions
As per f04b17f1c9

Also dedup continuserv readme
2018-05-30 09:45:22 +01:00
Ben Parsons 7a82a5d427 correct proposals.py 2018-05-29 14:20:48 +01:00
Ben Parsons 34090b24c4 prepare proposals.py for CI 2018-05-29 14:19:03 +01:00
Ben Parsons 663e1a5ebe Update some text 2018-05-18 10:17:54 +01:00
Ben Parsons 73b28612ec updates from feedback on pull 2018-05-15 16:07:55 +01:00
Ben Parsons 4d59abebf0 handle PR links from GitHub 2018-05-15 15:33:39 +01:00
Ben Parsons d338f18927 handle EOF gracefully when searching for Authors and PRs 2018-05-15 15:22:03 +01:00
Ben Parsons f1cc26dfd7 sort output by Created date per-table 2018-05-15 11:59:34 +01:00
Ben Parsons b8f38b21a7 update introductory text 2018-05-14 14:25:12 +01:00
Ben Parsons e87f1f2619 include PRs in tables 2018-05-14 11:32:40 +01:00
Ben Parsons 3b4e56c4e0 handle dd/mm/yyyy and yyyy-mm-dd dates in text 2018-05-14 09:48:54 +01:00
Ben Parsons 3b84de383c cleanup and include all content 2018-05-12 10:30:52 +01:00
Ben Parsons cbdd33a5f5 single authors and shepherds link correctly 2018-05-11 21:23:06 +01:00
Ben Parsons 73b7faddd4 handle multiple Google Docs 2018-05-11 20:47:27 +01:00
Ben Parsons 866b0b6348 I mostly play with ascii art 2018-05-10 16:02:55 +01:00
Ben Parsons dc2b53318b prettify ID column 2018-05-09 11:32:31 +01:00
Ben Parsons a78f7b38e9 generator is now usable 2018-05-08 15:35:46 +01:00
Ben Parsons c58dc59ffe separate tables by label 2018-05-08 14:43:06 +01:00
Ben Parsons 1f7fbefd53 start using a table 2018-05-08 12:17:38 +01:00
Ben Parsons e18aa30fd2 start generating new proposals page 2018-05-02 13:47:01 +01:00
Richard van der Hoff f04b17f1c9 Fix path to fsnotify
Apparently this should be referred to as gopkg.in/fsnotify/fsnotify.v1. I'm not
sure what has changed to stop the old format working.
2018-03-27 11:27:23 +01:00
Richard van der Hoff 8e97ec8bad make the speculator work for rick 2018-03-14 17:52:10 +00:00
Richard van der Hoff 9150ba0dce Improve error output from failing to parse examples 2018-03-06 11:09:33 +00:00
Richard van der Hoff a36bd1a6d2 Make build fail if gendoc fails
(cf https://github.com/matrix-org/matrix-doc/issues/1146)
2018-03-06 11:03:52 +00:00
Richard van der Hoff 87d90ab58a gendoc: improve title line matching
This makes it possible to include tables etc without the script trying to turn
them into titles.
2017-11-22 22:44:04 +00:00
Maxime Dor 1045bc721d Document federation version endpoint 2017-11-15 04:16:30 +01:00
Richard van der Hoff 427e0bb83b make jenkins and travis use a common script 2017-11-14 19:19:58 +00:00
Richard van der Hoff 202a265d85 Config for travis-ci 2017-11-14 13:12:38 +00:00
Richard van der Hoff 0cbf533625 Use petstore for continuserv swagger docs
Matrix.org's swagger browser is behind https, which means it can't read the
swagger from a continuserv on http. Use the petstore instead.
2017-11-14 13:02:43 +00:00
Richard van der Hoff a38d4fc68e Move templating into scripts dir
There's no real need for this to be at the top level.
2017-11-08 08:37:56 +00:00
Richard van der Hoff e7772af5c3 Supporting-docs now in matrix.org repo. 2017-11-06 14:57:04 +00:00
Richard van der Hoff cc6b16b63c Generate the swagger for export
We may as well generate the unstable version of the C-S swagger.
2017-10-25 12:09:08 +01:00
Richard van der Hoff d6f892f894 continuserv, speculator: update dump-swagger call
dump-swagger now expects -o before its output path
2017-10-25 12:05:31 +01:00
Richard van der Hoff 56c3e5a627 README.rst: Add notes on how to build the spec 2017-10-25 09:57:02 +01:00
Richard van der Hoff 834a3d78a8 Add a pip requirements file for the scripts 2017-10-25 09:54:21 +01:00
Richard van der Hoff 986c9d99a0 Improve arg parsing in dump-swagger 2017-10-25 08:05:50 +01:00
Richard van der Hoff 0dfff6b190 Simplify dump_swagger
We don't need most of the templating stuff. All we have to do is merge together
the swagger files, and resolve references.
2017-09-27 08:04:24 +01:00
Richard van der Hoff 2454598926 Speculator: include API docs links for branches 2017-09-26 15:23:00 +01:00
Richard van der Hoff 13d3293378 Fix version-extraction regexp
Fixes https://github.com/matrix-org/matrix-doc/issues/982
2017-09-18 13:48:35 +01:00
Richard van der Hoff b0ea6038c6 Move jekyll back out of matrix-doc again
Having the jekyll assets here is a mistake, because they need to be versioned
separately to the spec: we keep old versions of the spec, but they sometimes
need to be restyled to match the latest website.
2017-08-03 15:49:17 +01:00
Richard van der Hoff 8a66b1a68b Build the spec as part of the build 2017-08-03 00:18:07 +01:00
Richard van der Hoff 0af06291fe Hardcode client major version r0 2017-08-02 21:58:52 +01:00
Richard van der Hoff 986e51cf35 Gendoc: allow overriding the dest dir 2017-08-02 21:48:07 +01:00
Richard van der Hoff 9d2a93ad7b Run jekyll as part of the matrix-doc build
- this saves us having to run it manually on the web server.
2017-08-02 16:20:46 +01:00
Richard van der Hoff 934dd4754c swagger-http-server: fix port param
it needs to be an int, not a list
2017-04-19 16:10:53 +01:00
Richard van der Hoff 2ec43a5948 Add continuserv index
Oops, forgot this when adding support for the API docs to continuserv in
bfb65d8.
2016-10-14 17:57:07 +01:00
Richard van der Hoff d41438605d Use matrix.org for swagger UI
In the swagger UI, default to matrix.org rather than localhost, to make the UI
more useful.
2016-10-14 17:56:26 +01:00
Richard van der Hoff bfb65d8ceb Serve the API docs with continuserv 2016-10-13 23:54:08 +01:00
Richard van der Hoff 1320a86cbe Serve the api docs from the speculator
There are a few parts to this:

* when we generate the spec for a particular git sha, also run the script which
  turns our yaml api descriptions into a swagger json file.

* tweak serveSpec to add another header when serving the generated json.

* add a link to the generated index which will (via js hackery) redirect to our
  hosted swagger UI at http://matrix.org/docs/api/client-server, with a "url"
  query-param pointing at the generated json.

Also, factor makeTempDir out of gitClone, so that we can give clearer log lines.
2016-10-03 12:36:46 +01:00
Richard van der Hoff 459f4b953d swagger-http-server: add a --port argument 2016-09-27 12:18:01 +01:00
Oddvar Lovaas 1ea836bb1b Remove howtos from build script 2016-09-21 16:22:49 +01:00
Benjamin Saunders 33d80408e0 Add a nix-shell environment suitable for building
This enables easy execution of scripts/*.py by Nix users.

Signed-off-by: Benjamin Saunders <ben.e.saunders@gmail.com>
2016-08-30 21:26:35 -07:00
Richard van der Hoff 49cd65dd58 Add a license to the spec
We're licensing hte spec under ASLv2. Add the LICENSE file, and add the
short-form to as much of the source as is practical right now (adding it to
json source is a massive pita).
2016-07-12 17:28:30 +01:00
Stas Rudakou b6c41727c5 Add PyYAML to scripts/README.md
PyYAML is a 3rd-party package used by `gendoc.py`.
2016-06-11 14:10:21 +03:00
Richard van der Hoff 8b61dab1c6 gendoc.py: add --list_targets arg
I want to be able to run all of the targets except one from matrix-doc, so make
a way to list the targets.
2016-05-09 12:12:50 +01:00
Richard van der Hoff f46a2a7f2b Include the basePath in the path in swagger output
This fixes both SPEC-393, and ORG-52.
2016-05-06 12:35:27 +01:00
Richard van der Hoff 8aa0f64665 Update the speculator to understand spec subdirs
Fix the speculator so that it doesn't blow up when it finds subdirs in the gen
directory.

(It doesn't handle the html diff very well in the case that the subdirs don't
match, but it's hard to do much about that)
2016-05-05 18:46:29 +01:00
Richard van der Hoff 01f8173c84 Put each bit of spec in its own directory
I want to change the URLs for the spec sections on the website from
<version>/<section>.html to <section>/<version>.html, to better reflect how we
do the versioning.

This puts each bit of spec in its own directory, updates the index to point to
the right place, and fixes continuserv to deal with directories as well as
files.

This will probably require fixes to the speculator too, but I'll have to come
back to that.
2016-05-05 18:26:17 +01:00