Templates don't know at what level they will be inserted. Previously, we
hard-coded the title style which is not compatible with the build target
system. Define a set of styles which will be replaced by the gendoc script
when it encounters them:
'<' : Make this title a sub-heading
'/' : Make this title a heading at the same level
'>' : Make this title a super-heading
The build target system is now basically complete and functioning.
This will allow us to programatically position .rst snippets *anywhere*
which will for once and for all remove the horrid title level mismatch bugs.
We require this in order to allow people to re-shuffle the spec without
having to adjust the spec itself (e.g. 2 targets with different levels of
nesting).
We're well beyond the point now where a simple `cat` of .rst files to "build"
the spec is practical. We may want to slice and dice the spec in different
ways to address various cross-cutting concerns. To this end, there is now a
'targets' file which contains the "build targets" for the spec, which contains
the sorting order for the .rst files. For now, we just have a single
target: 'main'.
Convert the file format to be of the form ##_##_something.rst where the
first ## is the top-level section number and the second ## is the
second-level section number, e.g. 07_01_push_cs_api.rst means
Section 7.1 - This is now enforced in gendoc.py along with the title line
style that should be used (= for top-level, - for 2nd level) which will
give helpful suggestions if you trip up. This feels much more intuitive
now looking in /specification
This is just replacing the existing spec with a swagger version.
Subsequent pull requests will add 3pid join to this, as well as specing
the invite, leave, ban, and kick endpoints.
Hook up templating system to read the CHANGELOG for version and changelog info.
Modified nature.css to make it clearer on table headings/sub-headings. Use the
full _matrix/client path on title links to make it clear it is for v1.
Kegan Dougal