diff --git a/scripts/gendoc.py b/scripts/gendoc.py index 02de6d86..f9120551 100755 --- a/scripts/gendoc.py +++ b/scripts/gendoc.py @@ -12,71 +12,12 @@ stylesheets = { "stylesheet_path": ["basic.css", "nature.css"] } - -def get_git_ver_string(): - null = open(os.devnull, 'w') - cwd = os.path.dirname(os.path.abspath(__file__)) - try: - git_branch = subprocess.check_output( - ['git', 'rev-parse', '--abbrev-ref', 'HEAD'], - stderr=null, - cwd=cwd, - ).strip() - except subprocess.CalledProcessError: - git_branch = "" - try: - git_tag = subprocess.check_output( - ['git', 'describe', '--exact-match'], - stderr=null, - cwd=cwd, - ).strip() - git_tag = "tag=" + git_tag - except subprocess.CalledProcessError: - git_tag = "" - try: - git_commit = subprocess.check_output( - ['git', 'rev-parse', '--short', 'HEAD'], - stderr=null, - cwd=cwd, - ).strip() - except subprocess.CalledProcessError: - git_commit = "" - try: - dirty_string = "-this_is_a_dirty_checkout" - is_dirty = subprocess.check_output( - ['git', 'describe', '--dirty=' + dirty_string, "--all"], - stderr=null, - cwd=cwd, - ).strip().endswith(dirty_string) - git_dirty = "dirty" if is_dirty else "" - except subprocess.CalledProcessError: - git_dirty = "" - - if git_branch or git_tag or git_commit or git_dirty: - git_version = ",".join( - s for s in - (git_branch, git_tag, git_commit, git_dirty,) - if s - ) - return git_version.encode("ascii") - return "Unknown rev" - - def glob_spec_to(out_file_name): with open(out_file_name, "wb") as outfile: for f in sorted(glob.glob("../specification/*.rst")): with open(f, "rb") as infile: outfile.write(infile.read()) -def set_git_version(filename): - git_ver = get_git_ver_string() - # inplace search and replace, stdout is redirected to the output - # file, hence the "print" lines here. - for line in fileinput.input(filename, inplace=True): - if "$GIT_VERSION" in line: - line = line.replace("$GIT_VERSION", git_ver) - print line.rstrip("\n") - def rst2html(i, o): with open(i, "r") as in_file: @@ -116,8 +57,7 @@ def main(): glob_spec_to("tmp/full_spec.rst") run_through_template("tmp/full_spec.rst") shutil.copy("../supporting-docs/howtos/client-server.rst", "tmp/howto.rst") - set_git_version("tmp/full_spec.rst") - set_git_version("tmp/howto.rst") + run_through_template("tmp/howto.rst") rst2html("tmp/full_spec.rst", "gen/specification.html") rst2html("tmp/howto.rst", "gen/howtos.html") cleanup_env() diff --git a/specification/00_basis.rst b/specification/00_basis.rst index ca316da3..3a6abfa5 100644 --- a/specification/00_basis.rst +++ b/specification/00_basis.rst @@ -1,8 +1,8 @@ Matrix Specification ==================== -Version: ``$GIT_VERSION`` -------------------------------------------- +Version: ``{{git_version}}`` +-------------------------------------------------- Table of Contents ================= diff --git a/supporting-docs/howtos/client-server.rst b/supporting-docs/howtos/client-server.rst index f2830ff2..3bed5a9f 100644 --- a/supporting-docs/howtos/client-server.rst +++ b/supporting-docs/howtos/client-server.rst @@ -8,7 +8,7 @@ How to use the client-server API ================================ .. NOTE:: - The git version of this document is ``$GIT_VERSION`` + The git version of this document is ``{{git_version}}`` This guide focuses on how the client-server APIs *provided by the reference home server* can be used. Since this is specific to a home server diff --git a/templating/internal/sections.py b/templating/internal/sections.py index 8c3e7393..ff6df4e5 100644 --- a/templating/internal/sections.py +++ b/templating/internal/sections.py @@ -1,46 +1,61 @@ """Contains all the sections for the spec.""" from . import AccessKeyStore +import inspect import os -def _render_section_room_events(env, units): - template = env.get_template("events.tmpl") - examples = units.get("event-examples") - schemas = units.get("event-schemas") - sections = [] - for event_name in sorted(schemas): - if not event_name.startswith("m.room"): - continue - sections.append(template.render( - example=examples[event_name], - event=schemas[event_name] - )) - return "\n\n".join(sections) -def _render_ce_type(env, units, type): - template = env.get_template("common-event-fields.tmpl") - ce_types = units.get("common-event-fields") - return template.render(common_event=ce_types[type]) +class Sections(object): + """A class which creates sections for each method starting with "render_". + The key for the section is the text after "render_" + e.g. "render_room_events" has the section key "room_events" + """ + + def __init__(self, env, units): + self.env = env + self.units = units + + def render_room_events(self): + template = self.env.get_template("events.tmpl") + examples = self.units.get("event-examples") + schemas = self.units.get("event-schemas") + sections = [] + for event_name in sorted(schemas): + if not event_name.startswith("m.room"): + continue + sections.append(template.render( + example=examples[event_name], + event=schemas[event_name] + )) + return "\n\n".join(sections) -def _render_ce_fields(env, units): - return _render_ce_type(env, units, "event") + # pass through git ver so it'll be dropped in the input file + def render_git_version(self): + return self.units.get("git-version") -def _render_cre_fields(env, units): - return _render_ce_type(env, units, "room_event") + def _render_ce_type(self, type): + template = self.env.get_template("common-event-fields.tmpl") + ce_types = self.units.get("common-event-fields") + return template.render(common_event=ce_types[type]) -def _render_cse_fields(env, units): - return _render_ce_type(env, units, "state_event") + def render_common_event_fields(self): + return self._render_ce_type("event") + + def render_common_room_event_fields(self): + return self._render_ce_type("room_event") + + def render_common_state_event_fields(self): + return self._render_ce_type("state_event") -SECTION_DICT = { - "room_events": _render_section_room_events, - "common_event_fields": _render_ce_fields, - "common_state_event_fields": _render_cse_fields, - "common_room_event_fields": _render_cre_fields -} def load(env, units): store = AccessKeyStore() - for section_key in SECTION_DICT: - section = SECTION_DICT[section_key](env, units) + sections = Sections(env, units) + render_list = inspect.getmembers(sections, predicate=inspect.ismethod) + for (func_name, func) in render_list: + if not func_name.startswith("render_"): + continue + section_key = func_name[len("render_"):] + section = func() print "Generated section '%s' : %s" % ( section_key, section[:60].replace("\n","") ) diff --git a/templating/internal/units.py b/templating/internal/units.py index 793c5222..b992ca45 100644 --- a/templating/internal/units.py +++ b/templating/internal/units.py @@ -2,6 +2,7 @@ from . import AccessKeyStore import json import os +import subprocess def prop(obj, path): # Helper method to extract nested property values @@ -172,10 +173,59 @@ def _load_schemas(): schemata[filename] = schema return schemata +def _load_git_ver(): + null = open(os.devnull, 'w') + cwd = os.path.dirname(os.path.abspath(__file__)) + try: + git_branch = subprocess.check_output( + ['git', 'rev-parse', '--abbrev-ref', 'HEAD'], + stderr=null, + cwd=cwd, + ).strip() + except subprocess.CalledProcessError: + git_branch = "" + try: + git_tag = subprocess.check_output( + ['git', 'describe', '--exact-match'], + stderr=null, + cwd=cwd, + ).strip() + git_tag = "tag=" + git_tag + except subprocess.CalledProcessError: + git_tag = "" + try: + git_commit = subprocess.check_output( + ['git', 'rev-parse', '--short', 'HEAD'], + stderr=null, + cwd=cwd, + ).strip() + except subprocess.CalledProcessError: + git_commit = "" + try: + dirty_string = "-this_is_a_dirty_checkout" + is_dirty = subprocess.check_output( + ['git', 'describe', '--dirty=' + dirty_string, "--all"], + stderr=null, + cwd=cwd, + ).strip().endswith(dirty_string) + git_dirty = "dirty" if is_dirty else "" + except subprocess.CalledProcessError: + git_dirty = "" + + if git_branch or git_tag or git_commit or git_dirty: + git_version = ",".join( + s for s in + (git_branch, git_tag, git_commit, git_dirty,) + if s + ) + return git_version.encode("ascii") + return "Unknown rev" + UNIT_DICT = { "event-examples": _load_examples, "event-schemas": _load_schemas, - "common-event-fields": _load_common_event_fields + "common-event-fields": _load_common_event_fields, + "git-version": _load_git_ver } def load():