From f6cb1e9d141d881ae6205027626d6643776e833c Mon Sep 17 00:00:00 2001 From: Loek Le Blansch Date: Sun, 15 Sep 2024 20:46:48 +0200 Subject: WIP requirements --- scripts/tex.py | 43 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 43 insertions(+) create mode 100644 scripts/tex.py (limited to 'scripts/tex.py') diff --git a/scripts/tex.py b/scripts/tex.py new file mode 100644 index 0000000..b044857 --- /dev/null +++ b/scripts/tex.py @@ -0,0 +1,43 @@ +# utility function for converting latex code + +def group(*args): + return "".join("{" + arg + "}" for arg in args) + +def string(content): + return r"\string" + content + +def cmd(*args): + name = args[0] + args = args[1:] + if len(args) == 0: args = [""] + return f"\\{name}" + group(*args) + +def csdef(*args): + return r"\def" + cmd(*args) + +def auxout(content): + return r"\write\@auxout" + group(content) + +def scmd(*args): + return string(cmd(*args)) + +def env(name, *args): + content = args[-1] + args = args[0:-1] + out = f"\\begin{{{name}}}" + if len(args) > 0: + out += group(*args) + out += content + out += f"\\end{{{name}}}" + return out + +def esc(plain): + plain = plain.replace("\\", "\\string\\") + plain = plain.replace("#", "\\#") + plain = plain.replace("$", "\\$") + plain = plain.replace("%", "\\%") + return plain + +def tabrule(*cells): + return "&".join(cells) + "\\\\" + -- cgit v1.2.3 From dd2db2b7f62106e6c6c2abdaed73c5f608c690c6 Mon Sep 17 00:00:00 2001 From: Loek Le Blansch Date: Mon, 16 Sep 2024 16:40:46 +0200 Subject: update reqs2tex and add comments to reqs.toml --- reqs.toml | 25 +++++++++++++++++++++++++ scripts/reqs2tex.py | 42 +++++++++++++++++++++++++++++++++++------- scripts/tex.py | 3 +++ 3 files changed, 63 insertions(+), 7 deletions(-) (limited to 'scripts/tex.py') diff --git a/reqs.toml b/reqs.toml index 5e00dd9..c05cf71 100644 --- a/reqs.toml +++ b/reqs.toml @@ -1,10 +1,35 @@ +# This is a TOML file containing all project requirements. The reqs2tex script +# can be used to generate the files necessary to compile requirements.tex and +# cross-reference the requirements from other documents. +# +# Note that TOML has a hash table structure, so keys used for defining +# requirement properties cannot be used for requirement IDs. The properties are: +# label, type, id, index, deleted, done, description, priority + +# This is the requirement cross-reference ID. Requirements can be +# (cross-)referenced from LaTeX by prefixing this ID with `req:` and +# substituting dots for colons (i.e. this requirement is referenced as +# \cref{req:audio:async-api}). [audio.async-api] +# Requirement type ('system' | 'user') type = 'system' +# MoSCoW priority ('must' | 'should' | 'could' | 'will not') priority = 'must' +# Requirement body. Supports LaTeX formatting. (tip: use single quotes so +# backslash doesn't act as an escape character) description = ''' The public audio \gls{api} supports starting audio samples asynchronously (i.e.~fire and forget). ''' +# Definition of done (user requirements only). If 'done' is a string, it is +# treated as LaTeX code (like description), if it is a list of strings, each +# item is treated as the ID of another requirement. +#done = 'When I feel like it' +#done = [ 'audio.handle', 'audio.stream-mix' ] +# Requirements that are no longer applicable should set `deleted` to `true`. +# This will make sure the requirements are numbered consistently across +# different document revisions. +#deleted = true [audio.handle] type = 'system' diff --git a/scripts/reqs2tex.py b/scripts/reqs2tex.py index 9e71a48..c5ab3dd 100755 --- a/scripts/reqs2tex.py +++ b/scripts/reqs2tex.py @@ -9,7 +9,7 @@ def flatten(data): items = flatten(value) for item in items: if 'label' in item: - item['label'] = f"{key}:{item['label']}" + item['label'] = f"{key}.{item['label']}" else: item['label'] = f"{key}" out += items @@ -24,16 +24,44 @@ def make_id(item): counter = id_counter, ) +def sanitize(item, ids): + def die(msg): + print(f"[{item['label']}]: {msg}") + exit(1) + + # ensure properties + item['description'] = item.get('description') + item['done'] = item.get('done') + item['priority'] = item.get('priority') + item['type'] = item.get('type') + + # type checks + if item['type'] not in ['system', 'user']: + die(f"unknown or missing requirement type {repr(item['type'])}") + if item['priority'] not in ['must', 'should', 'could', 'will not']: + die(f"unknown or missing requirement priority {repr(item['type'])}") + + # logic checks + if item['type'] != 'user' and item['done'] is not None: + die("has definition of done but is not a user requirement") + + # conversions + if isinstance(item['done'], list): + # safety check + if not set(item['done']).issubset(ids): + die("definition of done includes unknown requirement(s)") + item['done'] = tex.cmd('Cref', tex.label2ref(*item['done'])) + def convert(data): reqs = flatten(data) - for index, item in enumerate(reqs): + index = 0 + for item in reqs: item['id'] = tex.esc(make_id(item)) - item['index'] = index - item['description'] = item.get('description', '???') - item['done'] = item.get('done', None) - item['priority'] = item.get('priority', 'must') - item['type'] = item.get('type', 'system') item['deleted'] = item.get('deleted', False) + if item['deleted']: continue + item['index'] = index + index += 1 + sanitize(item, [req['label'] for req in reqs]) # skip deleted requirements (but process for make_id) reqs = [item for item in reqs if item['deleted'] == False] diff --git a/scripts/tex.py b/scripts/tex.py index b044857..2fd51d8 100644 --- a/scripts/tex.py +++ b/scripts/tex.py @@ -41,3 +41,6 @@ def esc(plain): def tabrule(*cells): return "&".join(cells) + "\\\\" +def label2ref(*labels): + return ",".join(["req:" + label.replace('.', ':') for label in labels]) + -- cgit v1.2.3 From 2e49e0e0db184295eb08e930a3ccdf10e80e40fe Mon Sep 17 00:00:00 2001 From: Loek Le Blansch Date: Mon, 16 Sep 2024 19:07:50 +0200 Subject: implement simple requirements dump --- glossary.bib | 5 +++++ projdoc.cls | 25 +++++++++++++++---------- requirements.tex | 12 +++++++++++- scripts/reqs2tex.py | 32 +++++++++++++++++++------------- scripts/tex.py | 8 +++++++- 5 files changed, 57 insertions(+), 25 deletions(-) (limited to 'scripts/tex.py') diff --git a/glossary.bib b/glossary.bib index 4d02e4a..437db86 100644 --- a/glossary.bib +++ b/glossary.bib @@ -28,3 +28,8 @@ description = {Graphics library developed by \hbox{Microsoft}}, } +@acronym{api, + short = {API}, + long = {Application Programming Interface}, +} + diff --git a/projdoc.cls b/projdoc.cls index 8a592e3..fe8c8bc 100644 --- a/projdoc.cls +++ b/projdoc.cls @@ -121,16 +121,23 @@ itemsep=\dimexpr\style@itemsep-\style@parsep\relax, parsep=\style@parsep, } -\def\projdoc@setdescriptionstyle{% +\def\projdoc@description@before{% \renewcommand\makelabel[1]{% {\bfseries ##1}:% }% } -\setdescription{ - before={\projdoc@setdescriptionstyle}, - leftmargin=3em, - labelindent=3ex, +\newlength\projdoc@description@leftmargin% +\projdoc@description@leftmargin=3em% +\newlength\projdoc@description@labelindent% +\projdoc@description@labelindent=3ex% +\def\projdoc@setdescriptionstyle{% + \setdescription{ + before={\projdoc@description@before}, + leftmargin=\projdoc@description@leftmargin, + labelindent=\projdoc@description@labelindent, + }% } +\projdoc@setdescriptionstyle% \makeatother % create a label using \customlabel[]{}{} that displays @@ -230,11 +237,9 @@ }{}% % glossary \ifbool{projdoc@used@gls}{% - \setdescription{ - before={\projdoc@setdescriptionstyle}, - leftmargin=2ex, - labelindent=0pt, - }% + \projdoc@description@leftmargin=2ex% + \projdoc@description@labelindent=0pt% + \projdoc@setdescriptionstyle% \section*{Glossary}% \begin{multicols}{2}% \renewcommand{\glossarysection}[2][]{}% diff --git a/requirements.tex b/requirements.tex index 1b51220..dee529d 100644 --- a/requirements.tex +++ b/requirements.tex @@ -1,10 +1,20 @@ \documentclass{projdoc} \input{meta.tex} -\input{reqs.tex} + +\makeatletter +\projdoc@description@leftmargin=2ex +\projdoc@description@labelindent=0pt +\projdoc@setdescriptionstyle +\makeatother \title{Requirements} \begin{document} +\section{Requirements} +\begin{multicols}{2} +\input{reqs.tex} +\end{multicols} + \end{document} diff --git a/scripts/reqs2tex.py b/scripts/reqs2tex.py index 667eeb6..3bf0501 100755 --- a/scripts/reqs2tex.py +++ b/scripts/reqs2tex.py @@ -68,22 +68,28 @@ def convert(data): return reqs -def req2aux(req): - ref = tex.label2ref(req['label']) - out = [ - tex.cmd('newlabel', f"{ref}", tex.group(req['id'], req['id'], 'ggg', 'hhh', 'iii')), - tex.cmd('newlabel', f"{ref}@cref", tex.group(f"[requirement][aaa][bbb]{req['id']}", '[ccc][ddd][eee]fff')), - ] - return "\n".join(out) - def fmt_aux(data): - out = "\n".join([req2aux(req) for req in data]) - return out + out = [] + for req in data: + ref = tex.label2ref(req['label']) + out += [ + tex.cmd('newlabel', f"{ref}", tex.group(req['id'], req['id'], 'ggg', 'hhh', 'iii')), + tex.cmd('newlabel', f"{ref}@cref", tex.group(f"[requirement][aaa][bbb]{req['id']}", '[ccc][ddd][eee]fff')), + ] + return "\n".join(out) def fmt_tex(data): - return "\n".join([ - tex.cmd('relax') - ]) + out = [] + for req in data: + out.append( + tex.cmd('subsection', req['id']) + "\n\n" +\ + tex.env('description', + tex.cmd('item', ['Priority']) + req['priority'].title() +\ + tex.cmd('item', ['Requirement']) + req['description'] +\ + (tex.cmd('item', ['Definition of done']) + req['done'] if req['type'] == 'user' else "") + ) + ) + return "\n\n".join(out) def main(input_file): data = {} diff --git a/scripts/tex.py b/scripts/tex.py index 2fd51d8..2509a87 100644 --- a/scripts/tex.py +++ b/scripts/tex.py @@ -1,7 +1,13 @@ # utility function for converting latex code def group(*args): - return "".join("{" + arg + "}" for arg in args) + out = "" + for arg in args: + if isinstance(arg, list): + out += "[" + arg[0] + "]" + if isinstance(arg, str): + out += "{" + arg + "}" + return out def string(content): return r"\string" + content -- cgit v1.2.3 From 581044887a16d37c90116da544f5d9d600faa80c Mon Sep 17 00:00:00 2001 From: Loek Le Blansch Date: Tue, 17 Sep 2024 16:56:36 +0200 Subject: more fixes for reqs2tex --- scripts/reqs2tex.py | 103 ++++++++++++++++++++++++++++++++++------------------ scripts/tex.py | 3 -- 2 files changed, 68 insertions(+), 38 deletions(-) (limited to 'scripts/tex.py') diff --git a/scripts/reqs2tex.py b/scripts/reqs2tex.py index 6b7b77a..db7e174 100755 --- a/scripts/reqs2tex.py +++ b/scripts/reqs2tex.py @@ -1,17 +1,47 @@ #!/bin/python3 import sys, tomllib, tex - +from enum import StrEnum + +def label2ref(*labels): + return ",".join(["req:" + label.replace('.', ':') for label in labels]) + +class KEY(StrEnum): + LABEL = 'label' + TYPE = 'type' + ID = 'id' + INDEX = 'index' + DELETED = 'deleted' + DONE = 'done' + DESCRIPTION = 'description' + PRIORITY = 'priority' + +class REQ_TYPE(StrEnum): + SYSTEM = 'system' + USER = 'user' + +class REQ_PRIORITY(StrEnum): + MUST = 'must' + SHOULD = 'should' + COULD = 'could' + WONT = 'will not' + +# this doesn't work right def flatten(data): - if 'description' in data: - return [ data ] out = [] + # this key is a requirement + if KEY.DESCRIPTION in data: + out.append(data) + # check for children for key, value in data.items(): + # skip over reserved keys + if key in KEY: continue + items = flatten(value) for item in items: - if 'label' in item: - item['label'] = f"{key}.{item['label']}" + if KEY.LABEL in item: + item[KEY.LABEL] = f"{key}.{item[KEY.LABEL]}" else: - item['label'] = f"{key}" + item[KEY.LABEL] = f"{key}" out += items return out @@ -20,72 +50,75 @@ def make_id(item): global id_counter id_counter += 1 return "{type_short}#{counter:03d}".format( - type_short = item['type'][0].upper(), + type_short = item[KEY.TYPE][0].upper(), counter = id_counter, ) def sanitize(item, ids): def die(msg): - print(f"[{item['label']}]: {msg}") + print(f"[{item[KEY.LABEL]}]: {msg}") exit(1) # ensure properties - item['description'] = item.get('description') - item['done'] = item.get('done') - item['priority'] = item.get('priority') - item['type'] = item.get('type') + item[KEY.DESCRIPTION] = item.get(KEY.DESCRIPTION) + item[KEY.DONE] = item.get(KEY.DONE) + item[KEY.PRIORITY] = item.get(KEY.PRIORITY) + item[KEY.TYPE] = item.get(KEY.TYPE) # type checks - if item['type'] not in ['system', 'user']: - die(f"unknown or missing requirement type {repr(item['type'])}") - if item['priority'] not in ['must', 'should', 'could', 'will not']: - die(f"unknown or missing requirement priority {repr(item['type'])}") + if item[KEY.TYPE] not in REQ_TYPE: + die(f"unknown or missing requirement type: {repr(item[KEY.TYPE])}") + if item[KEY.PRIORITY] not in REQ_PRIORITY: + die(f"unknown or missing requirement priority: {repr(item[KEY.PRIORITY])}") # conversions - if isinstance(item['done'], list): + if isinstance(item[KEY.DONE], list): # safety check - if not set(item['done']).issubset(ids): + if not set(item[KEY.DONE]).issubset(ids): die("definition of done includes unknown requirement(s)") - item['done'] = tex.cmd('Cref', tex.label2ref(*item['done'])) + item[KEY.DONE] = tex.cmd('Cref', label2ref(*item[KEY.DONE])) def convert(data): reqs = flatten(data) + all_ids = [item[KEY.LABEL] for item in reqs] index = 0 for item in reqs: - item['id'] = tex.esc(make_id(item)) - item['deleted'] = item.get('deleted', False) - if item['deleted']: continue - item['index'] = index + item[KEY.ID] = tex.esc(make_id(item)) + item[KEY.DELETED] = item.get(KEY.DELETED, False) + if item[KEY.DELETED]: continue + item[KEY.INDEX] = index index += 1 - sanitize(item, [req['label'] for req in reqs]) + sanitize(item, all_ids) # skip deleted requirements (but process for make_id) - reqs = [item for item in reqs if item['deleted'] == False] + reqs = [item for item in reqs if item[KEY.DELETED] == False] return reqs def fmt_aux(data): out = [] - for req in data: - ref = tex.label2ref(req['label']) + for item in data: + ref = label2ref(item[KEY.LABEL]) out += [ - tex.cmd('newlabel', f"{ref}", tex.group(req['id'], req['id'], 'ggg', 'hhh', 'iii')), - tex.cmd('newlabel', f"{ref}@cref", tex.group(f"[requirement][aaa][bbb]{req['id']}", '[ccc][ddd][eee]fff')), + tex.cmd('newlabel', f"{ref}", tex.group(item[KEY.ID], item[KEY.ID], 'ggg', 'hhh', 'iii')), + tex.cmd('newlabel', f"{ref}@cref", tex.group(f"[requirement][aaa][bbb]{item[KEY.ID]}", '[ccc][ddd][eee]fff')), ] return "\n".join(out) def fmt_tex(data): out = [] - for req in data: + for item in data: out.append( - tex.cmd('subsection', req['id']) + "\n\n" +\ + tex.cmd('subsection', item[KEY.ID]) +\ + tex.cmd('label', label2ref(item[KEY.LABEL])) +\ + tex.cmd('par') +\ tex.env('description', - tex.cmd('item', ['Priority']) + req['priority'].title() +\ - tex.cmd('item', ['Requirement']) + req['description'] +\ - (tex.cmd('item', ['Definition of done']) + req['done'] if req['done'] is not None else "") + tex.cmd('item', ['Priority']) + item[KEY.PRIORITY].title() +\ + tex.cmd('item', ['Requirement']) + item[KEY.DESCRIPTION] +\ + (tex.cmd('item', ['Definition of done']) + item[KEY.DONE] if item[KEY.DONE] is not None else "") ) ) - return "\n\n".join(out) + return "".join(out) def main(input_file): data = {} diff --git a/scripts/tex.py b/scripts/tex.py index 2509a87..59c6895 100644 --- a/scripts/tex.py +++ b/scripts/tex.py @@ -47,6 +47,3 @@ def esc(plain): def tabrule(*cells): return "&".join(cells) + "\\\\" -def label2ref(*labels): - return ",".join(["req:" + label.replace('.', ':') for label in labels]) - -- cgit v1.2.3 From 1df61d671706436c17e23bc9dcdc3bbd0f14a167 Mon Sep 17 00:00:00 2001 From: Loek Le Blansch Date: Tue, 17 Sep 2024 17:35:19 +0200 Subject: labels/refs working inside requirements.tex --- scripts/reqs2tex.py | 28 +++++++++++++++++----------- scripts/tex.py | 17 +++++++++++++++-- 2 files changed, 32 insertions(+), 13 deletions(-) (limited to 'scripts/tex.py') diff --git a/scripts/reqs2tex.py b/scripts/reqs2tex.py index 8c2236a..700d05f 100755 --- a/scripts/reqs2tex.py +++ b/scripts/reqs2tex.py @@ -107,19 +107,25 @@ def fmt_aux(data): return "\n".join(out) def fmt_tex(data): - out = [] + out = "" for item in data: - out.append( - tex.cmd('subsection', item[KEY.ID]) +\ - tex.cmd('label', label2ref(item[KEY.LABEL])) +\ - tex.cmd('par') +\ - tex.env('description', - tex.cmd('item', ['Priority']) + item[KEY.PRIORITY].title() +\ - tex.cmd('item', ['Requirement']) + item[KEY.DESCRIPTION] +\ - (tex.cmd('item', ['Definition of done']) + item[KEY.DONE] if item[KEY.DONE] is not None else "") - ) + out += tex.join( + tex.cmd('subsection', item[KEY.ID]), + tex.withatletter( + tex.cmd('cref@constructprefix', 'requirement', r'\cref@result'), + tex.pedef('@currentlabel', item[KEY.ID]), + tex.pedef('@currentlabelname', item[KEY.ID]), + tex.pedef('cref@currentlabel', tex.group(['requirement'], [''], [r'\cref@result']) + item[KEY.ID]), + ), + tex.cmd('label', ['requirement'], label2ref(item[KEY.LABEL])), + tex.cmd('par'), + tex.env('description', tex.join( + tex.cmd('item', ['Priority']) + item[KEY.PRIORITY].title(), + tex.cmd('item', ['Requirement']) + item[KEY.DESCRIPTION], + (tex.cmd('item', ['Definition of done']) + item[KEY.DONE] if item[KEY.DONE] is not None else ""), + )) ) - return "".join(out) + return out def main(input_file): data = {} diff --git a/scripts/tex.py b/scripts/tex.py index 59c6895..eebf8ec 100644 --- a/scripts/tex.py +++ b/scripts/tex.py @@ -9,6 +9,9 @@ def group(*args): out += "{" + arg + "}" return out +def join(*things): + return "".join(things) + def string(content): return r"\string" + content @@ -18,11 +21,14 @@ def cmd(*args): if len(args) == 0: args = [""] return f"\\{name}" + group(*args) +def pedef(*args): + return r"\protected@edef" + cmd(*args) + def csdef(*args): return r"\def" + cmd(*args) -def auxout(content): - return r"\write\@auxout" + group(content) +def auxout(*content): + return r"\write\@auxout" + group(join(*content)) def scmd(*args): return string(cmd(*args)) @@ -47,3 +53,10 @@ def esc(plain): def tabrule(*cells): return "&".join(cells) + "\\\\" +def withatletter(*content): + return join( + cmd('makeatletter'), + *content, + cmd('makeatother'), + ) + -- cgit v1.2.3 From de6821389604dc5254b285a1ca13b19ffb1905b5 Mon Sep 17 00:00:00 2001 From: Loek Le Blansch Date: Tue, 17 Sep 2024 19:33:16 +0200 Subject: cleanup --- scripts/tex.py | 9 +++++ scripts/time2tex.py | 111 ++++++++++++++++++++++++++-------------------------- 2 files changed, 65 insertions(+), 55 deletions(-) (limited to 'scripts/tex.py') diff --git a/scripts/tex.py b/scripts/tex.py index eebf8ec..e8fc65b 100644 --- a/scripts/tex.py +++ b/scripts/tex.py @@ -60,3 +60,12 @@ def withatletter(*content): cmd('makeatother'), ) +def explist(*items): + out = [] + for item in items: + if isinstance(item, str) or not hasattr(item, '__iter__'): + out.append(item) + else: + out += explist(*item) + return out + diff --git a/scripts/time2tex.py b/scripts/time2tex.py index 8c3dd9b..a5d6802 100755 --- a/scripts/time2tex.py +++ b/scripts/time2tex.py @@ -35,35 +35,30 @@ def fmt_member_overview(times): tracked[time["name"]] += time["duration"] total_time += time["duration"] - out = "" - - # header - out += tex.cmd('toprule') - out += tex.tabrule(tex.cmd('textbf', 'Member'), tex.cmd('textbf', 'Tracked'), '') - out += tex.cmd('midrule') - - # member overview members = sorted(list(set(time["name"] for time in times))) - for name in members: - out += tex.tabrule(name, fmt_duration(tracked[name]), fmt_percentage(tracked[name] / total_time)) - out += tex.cmd('midrule') - - # sum - out += tex.tabrule('', fmt_duration(total_time), '') - out += tex.cmd('bottomrule') - - out = tex.env('tabular', 'lr@{~}l', out) - out = tex.cmd('centering') +\ - out +\ - tex.cmd('caption', 'Tracked time per group member') +\ - tex.cmd('label', 'tab:time-member') - out = tex.env('table', out) - - return out + return tex.env('table', tex.join( + tex.cmd('centering'), + tex.env('tabular', 'lr@{~}l', tex.join( + tex.cmd('toprule'), + tex.tabrule(tex.cmd('textbf', 'Member'), tex.cmd('textbf', 'Tracked')), + tex.cmd('midrule'), + *[ + tex.tabrule( + name, + fmt_duration(tracked[name]), + fmt_percentage(tracked[name] / total_time)) + for name in members + ], + tex.cmd('midrule'), + tex.tabrule('', fmt_duration(total_time), ''), + tex.cmd('bottomrule'), + )), + tex.cmd('caption', 'Tracked time per group member'), + tex.cmd('label', 'tab:time-member'), + )) def fmt_weekly_overview(times): # calculations - out = "" weeks = [] member_totals = {} total_time = sum(time["duration"] for time in times) @@ -93,34 +88,40 @@ def fmt_weekly_overview(times): for member in members: member_totals[member] = sum(time["duration"] for time in times if time["name"] == member) - # TODO: refactor - # begin table - out += r"\begin{table}\centering" - out += r"\fitimg{" - out += f"\\begin{{tabular}}{{l{'r@{~}l' * len(members)}@{{\\qquad}}r}}\\toprule" - out += r"\textbf{\#}" - for member in members: - out += f"&\\textbf{{{member}}}&" - out += r"&\textbf{Subtotal}\\\midrule{}" - - for entry in weeks: - out += f"{entry['num']}" - for member in members: - out += f"&{fmt_duration(entry['members'][member])}&{fmt_percentage(entry['members'][member] / entry['total'])}" - out += f"&{fmt_duration(entry['total'])}\\\\" - - out += r"\midrule{}" - for member in members: - out += f"&{fmt_duration(member_totals[member])}&{fmt_percentage(member_totals[member] / total_time)}" - out += f"&{fmt_duration(total_time)}\\\\" - - # end table - out += r"\bottomrule\end{tabular}" - out += r"}" # \fitimg - out += r"\caption{Tracked time per week}\label{tab:time-weekly}" - out += r"\end{table}" - - return out + return tex.env('table', tex.join( + tex.cmd('centering'), + tex.cmd('fitimg', + tex.env('tabular', r'l' + r'r@{~}l' * len(members) + r'@{\qquad}r', tex.join( + tex.cmd('toprule'), + tex.tabrule(*[ + tex.cmd('textbf', cell) + for cell in [ + tex.esc("#"), + *tex.explist([ member, "" ] for member in members), + "Subtotal", + ] + ]), + tex.cmd('midrule'), + *[ + tex.tabrule(*[ + str(entry['num']), + *tex.explist( + [ + fmt_duration(entry['members'][member]), + fmt_percentage(entry['members'][member] / entry['total']), + ] + for member in members + ), + fmt_duration(entry['total']), + ]) + for entry in weeks + ], + tex.cmd('bottomrule'), + )), + ), + tex.cmd('caption', 'Tracked time per week'), + tex.cmd('label', 'tab:time-weekly'), + )) def duration2secs(duration): out = 0 # output (seconds) @@ -182,13 +183,13 @@ def parse(content): return out def fmt(times): - return "\n\n".join([ + return tex.join( tex.cmd('section', 'Overviews'), tex.cmd('subsection', 'Members'), fmt_member_overview(times), tex.cmd('subsection', 'Weekly'), fmt_weekly_overview(times), - ]) + ) def main(input_file): content = "" -- cgit v1.2.3 From 0027f5df316892f121bb9f4b5b6b641646273ff0 Mon Sep 17 00:00:00 2001 From: Loek Le Blansch Date: Wed, 18 Sep 2024 14:54:48 +0200 Subject: add requirements + improve generated reqs.tex --- projdoc.cls | 7 +++++-- reqs.toml | 39 ++++++++++++++++++++++++++++++--------- requirements.tex | 1 + scripts/reqs2tex.py | 15 ++++++++------- scripts/tex.py | 10 ++++++++++ 5 files changed, 54 insertions(+), 18 deletions(-) (limited to 'scripts/tex.py') diff --git a/projdoc.cls b/projdoc.cls index 7420d38..fccf8c1 100644 --- a/projdoc.cls +++ b/projdoc.cls @@ -215,8 +215,11 @@ selection={recorded and deps and see}, ] -% requirements -\externaldocument{reqs}[requirements.pdf] +% allow cross-references to requirements.pdf from all documents except +% requirements.pdf itself +\IfEq*{\jobname}{requirements}{}{ + \externaldocument{reqs}[requirements.pdf] +} % default document header/trailer \makeatletter diff --git a/reqs.toml b/reqs.toml index c05cf71..6645ea4 100644 --- a/reqs.toml +++ b/reqs.toml @@ -10,33 +10,46 @@ # (cross-)referenced from LaTeX by prefixing this ID with `req:` and # substituting dots for colons (i.e. this requirement is referenced as # \cref{req:audio:async-api}). -[audio.async-api] +[audio] # Requirement type ('system' | 'user') -type = 'system' +type = 'user' # MoSCoW priority ('must' | 'should' | 'could' | 'will not') priority = 'must' # Requirement body. Supports LaTeX formatting. (tip: use single quotes so # backslash doesn't act as an escape character) description = ''' -The public audio \gls{api} supports starting audio samples asynchronously -(i.e.~fire and forget). +The engine allows the game programmer to easily start, pause and stop +background music, while simultaniously playing sound effects. ''' -# Definition of done (user requirements only). If 'done' is a string, it is -# treated as LaTeX code (like description), if it is a list of strings, each -# item is treated as the ID of another requirement. +# Definition of done. If 'done' is a string, it is treated as LaTeX code, if it +# is a list of strings, each item is treated as the ID of another requirement, +# and the references are checked before LaTeX runs. +done = [ + 'audio.async-api', + 'audio.handle', + 'audio.stream-mix', + 'audio.volume', +] #done = 'When I feel like it' -#done = [ 'audio.handle', 'audio.stream-mix' ] # Requirements that are no longer applicable should set `deleted` to `true`. # This will make sure the requirements are numbered consistently across # different document revisions. #deleted = true +[audio.async-api] +type = 'system' +priority = 'must' +description = ''' +The public audio \gls{api} supports starting audio samples asynchronously +(i.e.~fire and forget). +''' + [audio.handle] type = 'system' priority = 'must' description = ''' The public audio \gls{api} allows the game programmer to control (i.e.~play, -pause and stop) audio samples after they are created/initialized. +pause, resume and stop) audio samples after they are created/initialized. ''' [audio.stream-mix] @@ -46,6 +59,14 @@ description = ''' The audio system supports playing multiple audio streams simultaniously. ''' +[audio.volume] +type = 'system' +priority = 'must' +description = ''' +The public audio \gls{api} allows the game programmer to control the volume of +audio samples. +''' + [aux.license] type = 'system' priority = 'must' diff --git a/requirements.tex b/requirements.tex index 2936272..cbaba81 100644 --- a/requirements.tex +++ b/requirements.tex @@ -6,6 +6,7 @@ \projdoc@description@labelindent=0pt \projdoc@setdescriptionstyle \makeatother +\setcounter{secnumdepth}{1} \title{Requirements} diff --git a/scripts/reqs2tex.py b/scripts/reqs2tex.py index 82b0aae..ff9f3bb 100755 --- a/scripts/reqs2tex.py +++ b/scripts/reqs2tex.py @@ -122,7 +122,7 @@ def fmt_tex(data): out = "" for item in data: out += tex.join( - tex.cmd('subsection', item[KEY.ID]), + tex.cmd('subsection', f"{item[KEY.ID]}: {item[KEY.LABEL]}".upper()), tex.withatletter( tex.cmd('cref@constructprefix', 'requirement', r'\cref@result'), tex.pedef('@currentlabel', item[KEY.ID]), @@ -130,12 +130,13 @@ def fmt_tex(data): tex.pedef('cref@currentlabel', tex.group(['requirement'], [''], [r'\cref@result']) + item[KEY.ID]), ), tex.cmd('label', ['requirement'], label2ref(item[KEY.LABEL])), - tex.cmd('par'), - tex.env('description', tex.join( - tex.cmd('item', ['Priority']) + item[KEY.PRIORITY].title(), - tex.cmd('item', ['Requirement']) + item[KEY.DESCRIPTION], - (tex.cmd('item', ['Definition of done']) + item[KEY.DONE] if item[KEY.DONE] is not None else ""), - )) + tex.cmd('parbox', tex.cmd('linewidth'), + tex.env('description', tex.join( + tex.cmd('item', ['Priority']) + item[KEY.PRIORITY].title(), + tex.cmd('item', ['Requirement']) + item[KEY.DESCRIPTION], + (tex.cmd('item', ['Definition of done']) + item[KEY.DONE] if item[KEY.DONE] is not None else ""), + )), + ) ) return out diff --git a/scripts/tex.py b/scripts/tex.py index e8fc65b..07d275a 100644 --- a/scripts/tex.py +++ b/scripts/tex.py @@ -69,3 +69,13 @@ def explist(*items): out += explist(*item) return out +def sec(level, heading): + level = max(min(3, level), 0) + section = [ + 'section', + 'subsection', + 'subsubsection', + 'paragraph', + ][level] + return cmd(section, heading) + -- cgit v1.2.3