Add generator for reStructuredText

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

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 reStructuredText.
+
+    :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.
 

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
+
+   <br/>
+
+{{ make_title(title , '=') }}
+
+Created with `Corsair <https://github.com/esynr3z/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 %}

examples/regmap_yaml/csrconfig

@@ -47,6 +47,14 @@ image_dir = md_img
 print_conventions = True
 generator = Markdown
 
+[rst_doc]
+path = doc/regs.rst
+title = Register map
+print_images = True
+image_dir = md_img
+print_conventions = True
+generator = RST
+
 [asciidoc_doc]
 path = doc/regs.adoc
 title = Register map