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