Vermaete/sphinx

.circleci/config.yml

@@ -16,7 +16,7 @@ jobs:
           name: Install dependencies
           command: |
             sudo apt-get update
-            sudo apt-get install -y pandoc ghdl gtkwave verilator python3-pip
+            sudo apt-get install -y pandoc ghdl gtkwave verilator python3-pip texlive-latex-extra latexmk
             pip install -e .
 
       - run: python --version
@@ -25,4 +25,3 @@ jobs:
       - run: make compile_verilator
       - run: make test_c
       - run: make test_rst
-

Makefile

@@ -42,6 +42,12 @@ gen:
 	bin/ipxact2vhdl --srcFile example/input/test.xml --destDir example/output_no_default  --config example/input/no_default.ini
 	bin/ipxact2c --srcFile example/input/test.xml --destDir example/output_no_default  --config example/input/no_default.ini
 
+        # RestructuredText and Sphinx with Wavedrom
+	bin/ipxact2rst --srcFile example/input/test.xml --destDir example/output_sphinx  --config example/input/sphinx.ini
+	sphinx-build example/output_sphinx example/output_sphinx/build -q -b latex
+	make -C example/output_sphinx/build
+	cp example/output_sphinx/build/example.pdf example/output_sphinx
+
         #  test
 	bin/ipxact2systemverilog --srcFile example/input/test2.xml --destDir example/output
 	bin/ipxact2rst --srcFile example/input/test2.xml --destDir example/output
@@ -50,6 +56,7 @@ gen:
 	bin/ipxact2md --srcFile example/input/test2.xml --destDir example/output
 	bin/ipxact2c --srcFile example/input/test2.xml --destDir example/output
 
+
 compile: 
 	test -d work || vlib work
 	vlog  +incdir+example/output  example/output/example_sv_pkg.sv example/tb/sv_dut.sv example/tb/tb.sv

README.md

@@ -65,7 +65,7 @@ These are not needed for ipxact2systemverilog, but used for generating
 some of the files in example/output
 
 ```bash
-brew install pandoc
+brew install pandoc texlive-latex-extra latexmk
 ```
 
 ## Working in development mode for pypi

example/input/default.ini

@@ -34,3 +34,12 @@ PublicConvFunct = no
 # if resoved: std_logic_vector will be used
 # if unresoved: std_ulogic_vector will be used (default)
 std = unresolved
+
+# RestructuredText
+[rst]
+# if yes, insert the bitfield json content of Wavedrom into the RestructredText file.
+# Only Sphinx with the sphinxcontrib-wavedrom plugin will be able to use this.
+# @see:
+#     - https://github.com/bavovanachte/sphinx-wavedrom
+#     - https://github.com/wavedrom/bitfield
+wavedrom = no

example/input/sphinx.ini

@@ -0,0 +1,10 @@
+[global]
+UnusedHoles = no
+OneBitEnum = yes
+
+[vhdl]
+PublicConvFunct = yes
+std = resolved
+
+[rst]
+wavedrom = yes

example/output_sphinx/conf.py

@@ -0,0 +1,22 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = 'example'
+copyright = '2023, IEEE'
+author = 'ipxact2systemverilog'
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = ['sphinxcontrib.wavedrom']
+
+templates_path = ['_templates']
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+# Use the Python implementation of wavedrom-cli and not the npx one
+render_using_wavedrompy = True

example/output_sphinx/index.rst

@@ -0,0 +1,13 @@
+.. IPXACT documentation master file, created by
+   sphinx-quickstart on Sat Oct 14 18:45:45 2023.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+Welcome to IPXACT's documentation!
+==================================
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   example.rst

ipxact2systemverilog/ipxact2hdlCommon.py

@@ -23,14 +23,16 @@
 import math
 import os
 import sys
+import json
 import xml.etree.ElementTree as ETree
 from mdutils.mdutils import MdUtils
 from rstcloth import RstCloth
 
 DEFAULT_INI = {'global': {'unusedholes': 'yes',
                           'onebitenum': 'no'},
                'vhdl': {'PublicConvFunct': 'no',
-                        'std': 'unresolved'}}
+                        'std': 'unresolved'},
+               'rst': {'wavedrom': 'no'}}
 
 
 def sortRegisterAndFillHoles(regName,
@@ -256,6 +258,48 @@ def returnAsString(self):
             if reg.resetValue:
                 _headers.append('Reset')
             _headers.append('Description')
+
+            # insert the wavedrom bitfield register (only when using Sphinx)
+            current_index = -1
+            if self.config['rst'].getboolean('wavedrom'):
+                py = []
+
+                i = 0
+                fieldIndex = 0
+                while i < reg.size:
+                    # search if bit i is the start of an defined register field
+                    temp = [x for x in reg.bitOffsetList if x == i]
+                    f = {}
+                    if temp:  # yes, i is the start of an register field
+                        f['name'] = reg.fieldNameList[fieldIndex]
+                        f['bits'] = reg.bitWidthList[fieldIndex]
+                        i +=  reg.bitWidthList[fieldIndex]  # next search position
+                        fieldIndex += 1
+                    else:  # detected a gap in the register
+                        # not f['name'] -> gray field with Wavedrom
+                        try:
+                            f['bits'] = reg.bitOffsetList[fieldIndex] - i
+                            i += reg.bitWidthList[fieldIndex]
+                        except IndexError:  # no next field defined
+                            f['bits'] = reg.size - i
+                            i = reg.size
+
+                    if reg.resetValue:
+                        temp = (int(reg.resetValue, 0) >> i)
+                        mask = (2 ** f['bits']) - 1
+                        temp &= mask
+                        f['attr'] = temp
+
+                    py.append(f)
+
+                wd = {'reg': py,
+                      'config': {'lanes': reg.size//8}}
+                r.newline()
+                r.directive(name="wavedrom",
+                            fields=[("alt", reg.name)],
+                            content=json.dumps(wd, indent=1).splitlines())
+
+            # table of the register
             r.table(header=_headers,
                     data=reg_table)
 

requirements.txt

@@ -2,4 +2,6 @@ docutils
 lxml
 mdutils
 restructuredtext-lint
+sphinx
+sphinxcontrib-wavedrom
 rstcloth