From 96671ce83331bac1a5bdc342a1a33d5a1ef29feb Mon Sep 17 00:00:00 2001 From: Kegan Dougal Date: Tue, 26 May 2015 14:33:32 +0100 Subject: [PATCH] Use the templating system to set {{git_version}}. Restructure sections code. Restructured the sections code to be slightly more encapsulated than before. This will be expanded to more clearly separate the templating system from the specific implementation of the spec templates. --- scripts/gendoc.py | 62 +------------------ specification/00_basis.rst | 4 +- supporting-docs/howtos/client-server.rst | 2 +- templating/internal/sections.py | 77 ++++++++++++++---------- templating/internal/units.py | 52 +++++++++++++++- 5 files changed, 101 insertions(+), 96 deletions(-) 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():