diff --git a/scripts/gendoc.py b/scripts/gendoc.py index 611d0d105..1655d6f0a 100755 --- a/scripts/gendoc.py +++ b/scripts/gendoc.py @@ -241,7 +241,7 @@ def rst2html(i, o): ) -def run_through_template(input): +def run_through_template(input, set_verbose): tmpfile = './tmp/output' try: with open(tmpfile, 'w') as out: @@ -251,7 +251,7 @@ def run_through_template(input): "-o", "../scripts/tmp", "../scripts/"+input ] - if VERBOSE: + if set_verbose: args.insert(2, "-v") log("EXEC: %s" % " ".join(args)) log(" ==== build.py output ==== ") @@ -381,13 +381,13 @@ def main(target_name, keep_intermediates): log("Building spec [target=%s]" % target_name) target = get_build_target("../specification/targets.yaml", target_name) build_spec(target=target, out_filename="tmp/templated_spec.rst") - run_through_template("tmp/templated_spec.rst") + run_through_template("tmp/templated_spec.rst", VERBOSE) fix_relative_titles( target=target, filename="tmp/templated_spec.rst", out_filename="tmp/full_spec.rst" ) shutil.copy("../supporting-docs/howtos/client-server.rst", "tmp/howto.rst") - run_through_template("tmp/howto.rst") + run_through_template("tmp/howto.rst", False) # too spammy to mark -v on this rst2html("tmp/full_spec.rst", "gen/specification.html") rst2html("tmp/howto.rst", "gen/howtos.html") if not keep_intermediates: diff --git a/templating/batesian/units.py b/templating/batesian/units.py index 993f253dc..144cf245a 100644 --- a/templating/batesian/units.py +++ b/templating/batesian/units.py @@ -22,7 +22,11 @@ class Units(object): def log(self, text): if self.debug: - print "batesian:units: %s" % text + func_name = "" + trace = inspect.stack() + if len(trace) > 1 and len(trace[1]) > 2: + func_name = trace[1][3] + ":" + print "batesian:units:%s %s" % (func_name, text) def get_units(self, debug=False): unit_list = inspect.getmembers(self, predicate=inspect.ismethod) diff --git a/templating/matrix_templates/units.py b/templating/matrix_templates/units.py index a5c6a8153..50fa784e6 100644 --- a/templating/matrix_templates/units.py +++ b/templating/matrix_templates/units.py @@ -1,4 +1,12 @@ -"""Contains all the units for the spec.""" +""" +Contains all the units for the spec. + +This file loads swagger and JSON schema files and parses out the useful bits +and returns them as Units for use in Batesian. + +For the actual conversion of data -> RST (including templates), see the sections +file instead. +""" from batesian.units import Units import inspect import json @@ -134,7 +142,7 @@ class MatrixUnits(Units): "good_response": "" } } - self.log(".o.O.o. Endpoint: %s %s" % (method, path)) + self.log(" ------- Endpoint: %s %s ------- " % (method, path)) for param in single_api.get("parameters", []): # description desc = param.get("description", "") @@ -183,6 +191,9 @@ class MatrixUnits(Units): "desc": json_body[key]["description"] }) # endfor[param] + for row in endpoint["req_params"]: + self.log("Request parameter: %s" % row) + # group params by location to ease templating endpoint["req_param_by_loc"] = { # path: [...], query: [...], body: [...] @@ -240,6 +251,7 @@ class MatrixUnits(Units): # add response params if this API has any. if good_response: + self.log("Found a 200 response for this API") res_type = Units.prop(good_response, "schema/type") if res_type and res_type not in ["object", "array"]: # response is a raw string or something like that @@ -278,6 +290,16 @@ class MatrixUnits(Units): }] }) + for response_table in endpoint["res_tables"]: + self.log("Response: %s" % response_table["title"]) + for r in response_table["rows"]: + self.log("Row: %s" % r) + if len(endpoint["res_tables"]) == 0: + self.log( + "This API appears to have no response table. Are you " + + "sure this API returns no parameters?" + ) + endpoints.append(endpoint) aliases = single_api.get("x-alias", None) @@ -475,7 +497,7 @@ class MatrixUnits(Units): if re.match("^v[0-9\.]+$", word): version = word[1:] # strip the 'v' - self.log("Version: %s Title part: %s Changelog lines: %s" % ( + self.log("Version: %s Title part: %s Changelog line count: %s" % ( version, title_part, len(changelog_lines) )) if not version or len(changelog_lines) == 0: