From bb9537b8248bcb25dab300164ad68849db923939 Mon Sep 17 00:00:00 2001 From: Kegan Dougal Date: Mon, 1 Jun 2015 17:48:16 +0100 Subject: [PATCH] Add a CHANGELOG. Modify table CSS. 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. --- CHANGELOG.rst | 11 ++++ scripts/nature.css | 8 +++ specification/00_basis.rst | 12 ++++- specification/10_client_server_api.rst | 50 +------------------ templating/matrix_templates/sections.py | 11 +++- .../matrix_templates/templates/http-api.tmpl | 2 +- templating/matrix_templates/units.py | 46 ++++++++++++++++- 7 files changed, 86 insertions(+), 54 deletions(-) create mode 100644 CHANGELOG.rst diff --git a/CHANGELOG.rst b/CHANGELOG.rst new file mode 100644 index 00000000..7b6c9471 --- /dev/null +++ b/CHANGELOG.rst @@ -0,0 +1,11 @@ +.. This file is automatically processed by the templating system. To make it +.. happy, you MUST use '=' as the title underline and you MUST stick the version +.. in the title. The version MUST follow the numbering format +.. "v.." - You cannot use a-z. If the templating system fails to +.. find the right info, it will be treated as a test failure and so will show up +.. in Jenkins. Comments like this are ignored by both RST and the templating +.. system. + +Specification changes in v0.1.0 (2015-06-01) +============================================ +- First numbered release. \ No newline at end of file diff --git a/scripts/nature.css b/scripts/nature.css index 10126879..9d67f689 100644 --- a/scripts/nature.css +++ b/scripts/nature.css @@ -274,3 +274,11 @@ table { border: 0; border-collapse: collapse; } + +td[colspan]:not([colspan="1"]) { + background: #eeeeee; +} + +thead { + background: #eeeeee; +} diff --git a/specification/00_basis.rst b/specification/00_basis.rst index 5be6d33c..b7ec349b 100644 --- a/specification/00_basis.rst +++ b/specification/00_basis.rst @@ -3,7 +3,17 @@ Matrix Specification Version: {{spec_version}} ----------------------------- -``{{git_version}}`` +This specification has been generated from +https://github.com/matrix-org/matrix-doc using +https://github.com/matrix-org/matrix-doc/blob/master/scripts/gendoc.py as of +revision ``{{git_version}}``. + +Changelog +~~~~~~~~~ +{{spec_changelog}} + +For a full changelog, see +https://github.com/matrix-org/matrix-doc/blob/master/CHANGELOG.rst Table of Contents ================= diff --git a/specification/10_client_server_api.rst b/specification/10_client_server_api.rst index 76a0e3b6..659ceb3e 100644 --- a/specification/10_client_server_api.rst +++ b/specification/10_client_server_api.rst @@ -1224,56 +1224,8 @@ Maintaining the presence list:: Profiles ~~~~~~~~ -The client API for profile management consists of the following REST calls. -Fetching a user account displayname:: - - GET $PREFIX/profile//displayname - - Returned content: JSON object containing the following keys: - displayname: string of freeform text - -This call may be used to fetch the user's own displayname or to query the name -of other users; either locally or on remote systems hosted on other home -servers. - -Setting a new displayname:: - - PUT $PREFIX/profile//displayname - - Content: JSON object containing the following keys: - displayname: string of freeform text - -Fetching a user account avatar URL:: - - GET $PREFIX/profile//avatar_url - - Returned content: JSON object containing the following keys: - avatar_url: string containing an http-scheme URL - -As with displayname, this call may be used to fetch either the user's own, or -other users' avatar URL. - -Setting a new avatar URL:: - - PUT $PREFIX/profile//avatar_url - - Content: JSON object containing the following keys: - avatar_url: string containing an http-scheme URL - -Fetching combined account profile information:: - - GET $PREFIX/profile/ - - Returned content: JSON object containing the following keys: - displayname: string of freeform text - avatar_url: string containing an http-scheme URL - -At the current time, this API simply returns the displayname and avatar URL -information, though it is intended to return more fields about the user's -profile once they are defined. Client implementations should take care not to -expect that these are the only two keys returned as future versions of this -specification may yield more keys here. +{{profile_http_api}} Security -------- diff --git a/templating/matrix_templates/sections.py b/templating/matrix_templates/sections.py index 0c29070a..02bc1715 100644 --- a/templating/matrix_templates/sections.py +++ b/templating/matrix_templates/sections.py @@ -13,7 +13,12 @@ class MatrixSections(Sections): return self.units.get("git_version") def render_spec_version(self): - return "0.1.0" + spec_meta = self.units.get("spec_meta") + return spec_meta["version"] + + def render_spec_changelog(self): + spec_meta = self.units.get("spec_meta") + return spec_meta["changelog"] def _render_events(self, filterFn, sortFn, title_kind="~"): template = self.env.get_template("events.tmpl") @@ -52,7 +57,9 @@ class MatrixSections(Sections): # dump rest rest = [ e for e in endpoints if e not in sorted_endpoints ] return sorted_endpoints + rest - return self._render_http_api_group("profile", sortFn=sortFn) + return self._render_http_api_group( + "profile", sortFn=sortFn, title_kind="+" + ) def render_room_events(self): def filterFn(eventType): diff --git a/templating/matrix_templates/templates/http-api.tmpl b/templating/matrix_templates/templates/http-api.tmpl index 8880cfd1..e9fb7322 100644 --- a/templating/matrix_templates/templates/http-api.tmpl +++ b/templating/matrix_templates/templates/http-api.tmpl @@ -12,7 +12,7 @@ Request format: Parameter Value Description ================== ================= =========================================== {% for loc in endpoint.req_param_by_loc -%} -**{{loc}} parameters** +*{{loc}} parameters* -------------------------------------------------------------------------------- {% for param in endpoint.req_param_by_loc[loc] -%} {{param.key}}{{param.type|indent(19-param.key|length)}}{{param.desc|indent(18-param.type|length)|wrap(43)|indent_block(37)}} diff --git a/templating/matrix_templates/units.py b/templating/matrix_templates/units.py index de8bafc8..9b340f5e 100644 --- a/templating/matrix_templates/units.py +++ b/templating/matrix_templates/units.py @@ -3,6 +3,7 @@ from batesian.units import Units import inspect import json import os +import re import subprocess import urllib import yaml @@ -108,7 +109,7 @@ class MatrixUnits(Units): "title": single_api.get("summary", ""), "desc": single_api.get("description", single_api.get("summary", "")), "method": method.upper(), - "path": path, + "path": api.get("basePath", "") + path, "requires_auth": "security" in single_api, "rate_limited": 429 in single_api.get("responses", {}), "req_params": [], @@ -369,6 +370,49 @@ class MatrixUnits(Units): schemata[filename] = schema return schemata + def load_spec_meta(self): + path = "../CHANGELOG.rst" + title_part = None + version = None + changelog_lines = [] + with open(path, "r") as f: + prev_line = None + for line in f.readlines(): + if line.strip().startswith(".. "): + continue # comment + if prev_line is None: + prev_line = line + continue + if not title_part: + # find the title underline (at least 3 =) + if re.match("^[=]{3,}$", line.strip()): + title_part = prev_line + continue + prev_line = line + else: # have title, get body (stop on next title or EOF) + if re.match("^[=]{3,}$", line.strip()): + # we added the title in the previous iteration, pop it + # then bail out. + changelog_lines.pop() + break + changelog_lines.append(line) + + # parse out version from title + for word in title_part.split(): + if re.match("^v[0-9\.]+$", word): + version = word[1:] # strip the 'v' + + self.log("Version: %s Title part: %s Changelog lines: %s" % ( + version, title_part, len(changelog_lines) + )) + if not version or len(changelog_lines) == 0: + raise Exception("Failed to parse CHANGELOG.rst") + + return { + "version": version, + "changelog": "".join(changelog_lines) + } + def load_git_version(self): null = open(os.devnull, 'w') cwd = os.path.dirname(os.path.abspath(__file__))