778fe2a47a
css caption size tweak
6 years ago
e8afab1fe5
many visual improvements
6 years ago
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.
6 years ago
cee0a5ac7b
Merge pull request #1557 from turt2live/travis/general/r0-prep
...
Prepare the identity service and server-server APIs for r0
6 years ago
a1b1054aa1
fix handling of multi-line state key descriptions
6 years ago
2753d24302
Merge remote-tracking branch 'matrix-org/master' into travis/general/r0-prep
6 years ago
827033c128
Merge remote matrix-org/master
6 years ago
f649d04ae1
Merge pull request #1626 from matrix-org/rav/encoding
...
Set the encoding to UTF-8 on all file I/O
6 years ago
20c9829f56
Merge pull request #1627 from matrix-org/travis/general/dont-build-proposals
...
Don't generate proposals.rst in Circle CI
6 years ago
ecd3ce39e5
Don't generate proposals.rst in Circle CI
6 years ago
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.
6 years ago
f1ae872857
light zebra striping for tables
6 years ago
9e1d6d7490
sanitise caption handling
6 years ago
b2092922e8
Don't define a variable for the appservice major version
6 years ago
a5c3924492
Merge remote matrix-org/master
6 years ago
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.
6 years ago
e7a69a6a6d
Merge remote-tracking branch 'matrix-org/master' into travis/general/r0-prep
6 years ago
2ab2f91088
Merge remote-tracking branch 'matrix-org/master' into travis/releases/push-gateway/r0.1.0
6 years ago
380a53ecba
adjust caption -> smaller, left align
6 years ago
989b50a1a0
remove debug string
6 years ago
6e0fe70500
make spec tables prettier
6 years ago
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.
6 years ago
4278a9a516
Merge remote-tracking branch 'matrix-org/master' into travis/c2s/fix-events
6 years ago
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.
6 years ago
e9e93b0eec
Move `invite_room_state` to the correct place in the client-server API
...
Fixes https://github.com/matrix-org/matrix-doc/issues/1350
6 years ago
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
6 years ago
d370a2c6fd
Prepare the identity service and server-server APIs for r0
...
* Create the changelog scaffolding
* Set up the variables for versioning
6 years ago
750d4f9fda
Rename the presence EDU files to be accurate to their types; Misc cleanup of titles
6 years ago
a53fa9300d
Merge remote-tracking branch 'matrix-org/master' into travis/s2s/presence
6 years ago
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.
6 years ago
9be78f3aa7
Better support enums when they come among oneOf types
6 years ago
88d97b06ae
Support oneOf
6 years ago
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.
6 years ago
0f8954d839
Merge pull request #1463 from turt2live/travis/s2s/pdus-and-edus
...
Improve documentation around EDUs and PDUs
6 years ago
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.
6 years ago
96f5510266
Ensure the example is always set to something
6 years ago
ea307b5bdb
Support rendering schema definitions in the spec
6 years ago
1d019c3757
Merge pull request #1340 from matrix-org/benparsons/prdefence
...
expect "#<pull-number>" or "/pull/<pull-number>" in PRs field
6 years ago
d7919b6989
also scrape PRs when the full URL is pasted
6 years ago
bc3e45d642
Merge pull request #1358 from uhoreg/ignore-emacs-tmp
...
ignore emacs temporary files
6 years ago
4f24d2101f
Only get issues that are proposals when finding proposals
...
Otherwise we end up with not-proposals showing up in the list.
6 years ago
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.
6 years ago
acf9632afc
Enlist the examples
6 years ago
9fa838d3e8
Improve type naming
6 years ago
5ade15534d
Remove extra branch in example generation
6 years ago
042772aaf5
Make nested titles better
6 years ago
cb4fcd1d09
Merge remote-tracking branch 'matrix-org/master' into travis/s2s/transactions-swagger
6 years ago
a4e5a461f9
Improve handing of lists appearing in items
6 years ago
2dae0c9c49
use python3 in dump-swagger.py
6 years ago
e226b60c7f
Merge remote-tracking branch 'matrix-org/master' into travis/s2s/transactions-swagger
6 years ago
3ff1b0ddea
Merge pull request #1389 from turt2live/travis/towncrier
...
Use Towncrier to generate the unstable changelog
6 years ago
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.
6 years ago
cfac4a1ab3
Use towncrier 18.6.0 final
6 years ago
e5da1e1741
Improve upon the transaction schema and examples
...
Reduces data duplication and makes the objects more reusable for other areas of the spec
6 years ago
8a4ba8c5ca
Use Popen rather than run()
6 years ago
af7460088f
Use six for url quoting
6 years ago
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.
6 years ago
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.
6 years ago
905ef6dadd
Have the towncrier generator complain if the output looks wrong
6 years ago
ebc7db12fb
Remove extraneous list casting
6 years ago
9e0fafbcd4
Remove debugging line
6 years ago
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)
6 years ago
550f95570b
Fix regex for some versions of python
6 years ago
7ada960206
Fix the Travis CI build to work on 3.5
6 years ago
08f6912825
Ask Travis to install 3.5 explicitly
6 years ago
a4f8e0807a
Print the python version being used in the CI build.
6 years ago
63b926a4aa
Make Travis CI use python 3
6 years ago
c2f85788de
Add documentation about how to add to the changelog
6 years ago
9277e4c52d
Add initial towncrier support
6 years ago
f54d5a4039
Convert build scripts to python 3
6 years ago
1722734a51
Merge pull request #1364 from turt2live/travis/server-name-join
...
Document the server_name query parameter on /join/{roomIdOrAlias}
6 years ago
f9a0a49e96
Add a bunch more people to the speculator trusted list
6 years ago
4485b2f025
Merge branch 'master' into travis/server-name-join
6 years ago
8bd1fe9908
Merge pull request #1357 from turt2live/travis/fix-windows
...
Use filepath.To/FromSlash instead of manually replacing slashes
6 years ago
d02e9b875b
Merge pull request #1355 from matrix-org/benpa/travisci-ignore-proposals
...
don't run proposals.py step if in TravisCI environment
6 years ago
cbbdcbcf01
Show arrays in the query string as "[type]" rather than "array"
...
Otherwise the question "array of what?" is raised.
6 years ago
aac7b848f7
Add uhoreg and myself as trusted speculator people
6 years ago
a2e0d0382c
ignore emacs temporary files
...
and fix ignoring of dotfiles
6 years ago
85e1962f9c
Use filepath.To/FromSlash instead of manually replacing slashes
...
see https://github.com/matrix-org/matrix-doc/pull/1356#discussion_r199897557
6 years ago
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.
6 years ago
5803c9cace
don't run proposals.py step if in TravisCI environment
6 years ago
e52d94bea9
ignore malformed PR items
6 years ago
5ab5fe08d1
Small grammatical and stylistic fixes
6 years ago
0c1ba33eba
include proposals.py in matrix-doc CI
6 years ago
ee98082a60
update MSC1270
6 years ago
cb00fc35ab
git checkout master
6 years ago
d1c27349b2
Merge branch 'master' of https://github.com/matrix-org/matrix-doc
6 years ago
419bf1e52c
Fix continuserv instructions
...
As per f04b17f1c9
6 years ago
7a82a5d427
correct proposals.py
6 years ago
34090b24c4
prepare proposals.py for CI
6 years ago
663e1a5ebe
Update some text
6 years ago
73b28612ec
updates from feedback on pull
6 years ago
4d59abebf0
handle PR links from GitHub
6 years ago
d338f18927
handle EOF gracefully when searching for Authors and PRs
6 years ago
f1cc26dfd7
sort output by Created date per-table
6 years ago
b8f38b21a7
update introductory text
6 years ago
e87f1f2619
include PRs in tables
6 years ago
3b4e56c4e0
handle dd/mm/yyyy and yyyy-mm-dd dates in text
6 years ago
3b84de383c
cleanup and include all content
6 years ago
cbdd33a5f5
single authors and shepherds link correctly
6 years ago
73b7faddd4
handle multiple Google Docs
6 years ago
866b0b6348
I mostly play with ascii art
6 years ago
dc2b53318b
prettify ID column
6 years ago
a78f7b38e9
generator is now usable
6 years ago
c58dc59ffe
separate tables by label
6 years ago
1f7fbefd53
start using a table
6 years ago
e18aa30fd2
start generating new proposals page
6 years ago
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.
6 years ago
8e97ec8bad
make the speculator work for rick
6 years ago
9150ba0dce
Improve error output from failing to parse examples
6 years ago
a36bd1a6d2
Make build fail if gendoc fails
...
(cf https://github.com/matrix-org/matrix-doc/issues/1146 )
6 years ago
87d90ab58a
gendoc: improve title line matching
...
This makes it possible to include tables etc without the script trying to turn
them into titles.
7 years ago
1045bc721d
Document federation version endpoint
7 years ago
427e0bb83b
make jenkins and travis use a common script
7 years ago
202a265d85
Config for travis-ci
7 years ago
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.
7 years ago
a38d4fc68e
Move templating into scripts dir
...
There's no real need for this to be at the top level.
7 years ago
e7772af5c3
Supporting-docs now in matrix.org repo.
7 years ago
cc6b16b63c
Generate the swagger for export
...
We may as well generate the unstable version of the C-S swagger.
7 years ago
d6f892f894
continuserv, speculator: update dump-swagger call
...
dump-swagger now expects -o before its output path
7 years ago
56c3e5a627
README.rst: Add notes on how to build the spec
7 years ago
834a3d78a8
Add a pip requirements file for the scripts
7 years ago
986c9d99a0
Improve arg parsing in dump-swagger
7 years ago
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.
7 years ago
2454598926
Speculator: include API docs links for branches
7 years ago
13d3293378
Fix version-extraction regexp
...
Fixes https://github.com/matrix-org/matrix-doc/issues/982
7 years ago
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.
7 years ago
8a66b1a68b
Build the spec as part of the build
7 years ago
0af06291fe
Hardcode client major version r0
7 years ago
986e51cf35
Gendoc: allow overriding the dest dir
7 years ago
9d2a93ad7b
Run jekyll as part of the matrix-doc build
...
- this saves us having to run it manually on the web server.
7 years ago
934dd4754c
swagger-http-server: fix port param
...
it needs to be an int, not a list
7 years ago
2ec43a5948
Add continuserv index
...
Oops, forgot this when adding support for the API docs to continuserv in
bfb65d8
8 years ago
d41438605d
Use matrix.org for swagger UI
...
In the swagger UI, default to matrix.org rather than localhost, to make the UI
more useful.
8 years ago
bfb65d8ceb
Serve the API docs with continuserv
8 years ago
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.
8 years ago
459f4b953d
swagger-http-server: add a --port argument
8 years ago
1ea836bb1b
Remove howtos from build script
8 years ago
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>
8 years ago
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).
8 years ago
b6c41727c5
Add PyYAML to scripts/README.md
...
PyYAML is a 3rd-party package used by `gendoc.py`.
8 years ago
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.
8 years ago
f46a2a7f2b
Include the basePath in the path in swagger output
...
This fixes both SPEC-393, and ORG-52.
8 years ago
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)
8 years ago
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.
8 years ago
a8eed29e9f
gendoc: Allow multiple targets
8 years ago
7138205f31
Update README.md
...
escape angle-bracket to stop it getting lost in markdown
8 years ago
0546f0917d
Replace hacky shell to do matrix styling with hacky perl
...
Since the shell just wrapped three invocations of perl, we might as well do
it all in perl.
8 years ago
23c4ffbc1b
Add securityDefintions to generated swagger JSON
...
Also factor out to a common file
8 years ago
60f36bf868
Script to serve the generated swagger JSON
...
We need custom CORS headers to serve the swagger JSON, so add a script to do it
8 years ago
Ben Parsons