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

@@ -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<num>.<num>.<num>" - 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.

scripts/nature.css

@@ -274,3 +274,11 @@ table {
     border: 0;
     border-collapse: collapse;
 }
+
+td[colspan]:not([colspan="1"]) {
+    background: #eeeeee;
+}
+
+thead {
+    background: #eeeeee;
+}

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
 =================

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::
+{{profile_http_api}}
-
-  GET $PREFIX/profile/<user_id>/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/<user_id>/displayname
-
-  Content: JSON object containing the following keys:
-    displayname: string of freeform text
-
-Fetching a user account avatar URL::
-
-  GET $PREFIX/profile/<user_id>/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/<user_id>/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/<user_id>
-
-  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.
 
 Security
 --------

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):

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)}}

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__))