From 260b72f7cbe9bea6ad78ce652cf1301895065a9b Mon Sep 17 00:00:00 2001 From: Greter Raffael Date: Mon, 21 Mar 2022 11:41:55 +0100 Subject: [PATCH] Add generator for reStructuredText --- corsair/__main__.py | 1 + corsair/generators.py | 48 +++++++++++ corsair/templates/regmap_rst.j2 | 142 ++++++++++++++++++++++++++++++++ 3 files changed, 191 insertions(+) create mode 100644 corsair/templates/regmap_rst.j2 diff --git a/corsair/__main__.py b/corsair/__main__.py index 3ab6c45..89e537c 100755 --- a/corsair/__main__.py +++ b/corsair/__main__.py @@ -81,6 +81,7 @@ def generate_templates(format): targets.update(corsair.generators.Python(path="sw/regs.py").make_target('py')) targets.update(corsair.generators.CHeader(path="sw/regs.h").make_target('c_header')) targets.update(corsair.generators.Markdown(path="doc/regs.md", image_dir="md_img").make_target('md_doc')) + targets.update(corsair.generators.RST(path="doc/regs.rst", image_dir="rst_img").make_target('rst_doc')) targets.update(corsair.generators.Asciidoc(path="doc/regs.adoc", image_dir="adoc_img").make_target('asciidoc_doc')) # create templates diff --git a/corsair/generators.py b/corsair/generators.py index 47c9470..4091b20 100755 --- a/corsair/generators.py +++ b/corsair/generators.py @@ -534,6 +534,54 @@ def generate(self): self.draw_regs(Path(self.path).parent / self.image_dir, self.rmap) +class RST(Generator, Jinja2, Wavedrom): + """Create documentation for a register map in Markdown. + + :param rmap: Register map object + :type rmap: :class:`corsair.RegisterMap` + :param path: Path to the output file + :type path: str + :param title: Document title + :type title: str + :param print_images: Enable generating images for bit fields of a register + :type print_images: bool + :param image_dir: Path to directory where all images will be saved + :type image_dir: str + :param print_conventions: Enable generating table with register access modes explained + :type print_conventions: bool + """ + + def __init__(self, rmap=None, path='regs.rst', title='Register map', + print_images=True, image_dir="regs_img", print_conventions=True, **args): + super().__init__(rmap, **args) + self.path = path + self.title = title + self.print_images = print_images + self.image_dir = image_dir + self.print_conventions = print_conventions + + def generate(self): + filename = utils.get_file_name(self.path) + # validate parameters + self.validate() + # prepare jinja2 + j2_template = 'regmap_rst.j2' + j2_vars = {} + j2_vars['corsair_ver'] = __version__ + j2_vars['rmap'] = self.rmap + j2_vars['print_images'] = utils.str2bool(self.print_images) + j2_vars['print_conventions'] = utils.str2bool(self.print_conventions) + j2_vars['image_dir'] = self.image_dir + j2_vars['filename'] = filename + j2_vars['title'] = self.title + j2_vars['config'] = config.globcfg + # render + self.render_to_file(j2_template, j2_vars, self.path) + # draw register images + if self.print_images: + self.draw_regs(Path(self.path).parent / self.image_dir, self.rmap) + + class Asciidoc(Generator, Jinja2, Wavedrom): """Create documentation for a register map in AsciiDoc. diff --git a/corsair/templates/regmap_rst.j2 b/corsair/templates/regmap_rst.j2 new file mode 100644 index 0000000..e222dc7 --- /dev/null +++ b/corsair/templates/regmap_rst.j2 @@ -0,0 +1,142 @@ +{# MACRO #} +{#- generic range #} +{% from "regmap_md.j2" import range with context %} +{#- bit field mode #} +{% from "regmap_md.j2" import mode with context %} +{#- value in hex format #} +{% from "regmap_md.j2" import literal with context %} +{#- linkify title #} +{% macro linkify(title) %} +{{ title | lower | replace('_', '-') }} +{%- endmacro %} +{#- title with underline #} +{% macro make_title(title, symbol) %} +{{ title }} +{{ symbol * title | length }} +{%- endmacro %} +{#- replace newlines #} +{% macro rnl(string) %} +{{ string | replace('\r', '') | replace('\n', ' |br| ') }} +{%- endmacro %} + +{#- TEMPLATE NAMESPACE #} +{% set tmp = namespace() %} + +{#- TEMPLATE #} +.. |br| raw:: html + +
+ +{{ make_title(title , '=') }} + +Created with `Corsair `__ v{{ corsair_ver }}. + +{% if print_conventions %} +{{ make_title("Conventions", '-') }} + +.. list-table:: + :header-rows: 1 + + * - Access mode + - Description + * - rw + - Read and Write + * - rw1c + - Read and Write 1 to Clear + * - rw1s + - Read and Write 1 to Set + * - ro + - Read Only + * - roc + - Read Only to Clear + * - roll + - Read Only / Latch Low + * - rolh + - Read Only / Latch High + * - wo + - Write only + * - wosc + - Write Only / Self Clear +{% endif %} + +{{ make_title("Register map summary", '-') }} + +Base address: {{ "0x%08x" % config['base_address'] }} + +.. list-table:: + :header-rows: 1 + :widths: auto + + * - Name + - Address + - Description +{% for reg in rmap %} + * - `{{ reg.name }} <#{{ linkify(reg.name) }}>`__ + - {{ literal(reg.address, config['address_width']) }} + - {{ rnl(reg.description) }} +{% endfor %} +{% for reg in rmap %} + + +{{ make_title(reg.name, '-') }} + +{{ reg.description }} + +Address offset: {{ literal(reg.address, config['address_width']) }} + +Reset value: {{ literal(reg.reset, config['data_width']) }} + +{% if print_images %} +.. image:: {{ image_dir }}/{{ reg.name.lower()}}.svg + :alt: {{ reg.name.lower()}} +{% endif %} + +.. list-table:: + :header-rows: 1 + :widths: auto + + * - Name + - Bits + - Mode + - Reset + - Description + {% set tmp.reserved_msb = config['data_width'] - 1 %} + {% for bf in reg.bitfields[::-1] %} + {% if tmp.reserved_msb > bf.msb %} + {% set tmp.reserved_lsb = bf.msb + 1 %} + {% set tmp.reserved_width = tmp.reserved_msb - tmp.reserved_lsb + 1 %} + * - -- + - {{ range(tmp.reserved_msb, tmp.reserved_lsb) }} + - -- + - {{ literal(0, tmp.reserved_width) }} + - Reserved + {% endif %} + * - {{ bf.name }} + - {{ range(bf.msb, bf.lsb) }} + - {{ mode(bf) }} + - {{ literal(bf.reset, bf.width) }} + - {{ rnl(bf.description) }} + {% set tmp.reserved_msb = bf.lsb - 1 %} + {% endfor %} + + {% for bf in reg %} + {% if bf.enums %} +{{ make_title('Enumerated values for %s.%s' % (reg.name, bf.name), '.') }} + +.. list-table:: + :header-rows: 1 + :widths: auto + + * - Name + - Value + - Description + {% for enum in bf %} + * - {{ enum.name }} + - {{ literal(enum.value, bf.width) }} + - {{ rnl(enum.description) }} + {% endfor %} + + {% endif %} + {% endfor %} +Back to `Register map <#register-map-summary>`__. +{% endfor %}