Merge pull request #56 from antmicro/nmigen

Continuation: Support nMigen and RTLIL inputs

Author: mithro

.gitignore

@@ -104,4 +104,4 @@ venv.bak/
 .mypy_cache/
 
 # version number
-sphinxcontrib_verilog_diagrams/version.py
+sphinxcontrib_hdl_diagrams/version.py

.readthedocs.yml

@@ -8,6 +8,7 @@ version: 2
 # Build documentation in the docs/ directory with Sphinx
 sphinx:
   configuration: docs/conf.py
+  fail_on_warning: true
 
 formats:
  - htmlzip

.travis.yml

@@ -2,6 +2,7 @@ language: minimal
 
 before_install:
     - make env
+    - source env/conda/bin/activate sphinxcontrib-hdl-diagrams
 
 stages:
     - name:
@@ -13,28 +14,41 @@ jobs:
     - stage: Tests
       name: "Test :skin: option"
       script:
-        - source env/conda/bin/activate sphinxcontrib-verilog-diagrams
         - cd tests && python3 -m unittest test.TestSkins
 
     - stage: Tests
       name: "Test :yosys_script: option"
       script:
-        - source env/conda/bin/activate sphinxcontrib-verilog-diagrams
         - cd tests && python3 -m unittest test.TestYosysScript
 
     - stage: Tests
       name: "Test verilog_diagram_yosys config variable"
       script:
-        - source env/conda/bin/activate sphinxcontrib-verilog-diagrams
         - cd tests && python3 -m unittest test.TestYosysType
 
+    - stage: Tests
+      name: "Test nMigen input format"
+      script:
+        - cd tests && python3 -m unittest test.TestNMigen
+
+    - stage: Tests
+      name: "Test RTLIL input format"
+      script:
+        - cd tests && python3 -m unittest test.TestRTLIL
+
+    - stage: Tests
+      name: "Test compatibility package"
+      script:
+        - cd tests && python3 -m unittest test.TestCompat
+
     - stage: Build
       name: "Build"
       script:
         - make build
 
     - stage: Deploy
       name: "PyPI"
+      before_install: null
       before_deploy:
         - make clean
         - make sphinxcontrib_verilog_diagrams/version.py

Makefile

@@ -20,7 +20,7 @@ ENVIRONMENT_FILE := environment.yml
 include third_party/make-env/conda.mk
 
 # Create a version.py file
-VERSION_PY = sphinxcontrib_verilog_diagrams/version.py
+VERSION_PY = sphinxcontrib_hdl_diagrams/version.py
 $(VERSION_PY):
 	echo "__version__ = '$$(git describe | sed -e's/v\([0-9]\+\)\.\([0-9]\+\)-\([0-9]\+\)-g[0-9a-f]\+/\1.\2.post\3/')'" > $@
 
@@ -33,35 +33,57 @@ version-clean:
 
 clean: version-clean
 
-# Build and upload commands
+# Build and upload main package
+
+#PYPI_TEST = --repository-url https://test.pypi.org/legacy/
+PYPI_TEST = --repository testpypi
+
 build: $(VERSION_PY) | $(CONDA_ENV_PYTHON)
 	$(IN_CONDA_ENV) python setup.py sdist bdist_wheel && twine check dist/*
 
-.PHONY: build
-
 build-clean:
 	rm -rf env/downloads/conda-pkgs
 	rm -rf build dist *.egg-info
 	find -name *.pyc -delete
 	find -name __pycache__ -delete
 
-clean: build-clean
-
-#PYPI_TEST = --repository-url https://test.pypi.org/legacy/
-#PYPI_TEST = --repository testpypi
-
 upload-test: build | $(CONDA_ENV_PYTHON)
 	$(IN_CONDA_ENV) twine upload ${PYPI_TEST}  dist/*
 
-.PHONY: upload-test
-
 upload: build | $(CONDA_ENV_PYTHON)
 	$(IN_CONDA_ENV) twine upload --verbose dist/*
 
-.PHONY: upload
+.PHONY: build build-clean upload upload-test
+
+# Build and upload compatibility package
+
+COMPAT_PACKAGE_DIR = compat
+
+build_compat: $(VERSION_PY) | $(CONDA_ENV_PYTHON)
+	$(IN_CONDA_ENV) cd $(COMPAT_PACKAGE_DIR); python setup.py sdist bdist_wheel && twine check dist/*
+
+build_compat-clean:
+	cd $(COMPAT_PACKAGE_DIR); rm -rf env/downloads/conda-pkgs
+	cd $(COMPAT_PACKAGE_DIR); rm -rf build dist *.egg-info
+	cd $(COMPAT_PACKAGE_DIR); find -name *.pyc -delete
+	cd $(COMPAT_PACKAGE_DIR); find -name __pycache__ -delete
+
+upload_compat-test: build_compat | $(CONDA_ENV_PYTHON)
+	$(IN_CONDA_ENV) cd $(COMPAT_PACKAGE_DIR); twine upload ${PYPI_TEST}  dist/*
+
+upload_compat: build_compat | $(CONDA_ENV_PYTHON)
+	$(IN_CONDA_ENV) cd $(COMPAT_PACKAGE_DIR); twine upload --verbose dist/*
+
+.PHONY: build_compat build_compat-clean upload_compat-test upload_compat
+
+# Tests
 
 test: $(VERSION_PY) | $(CONDA_ENV_PYTHON)
 	$(IN_CONDA_ENV) cd docs; make html
 	$(IN_CONDA_ENV) cd tests; make test
 
 .PHONY: test
+
+# Cleanup
+
+clean: build-clean build_compat-clean

README.rst

@@ -1,41 +1,43 @@
-sphinxcontrib-verilog-diagrams
+sphinxcontrib-hdl-diagrams
 ==============================
 
 
-.. image:: https://img.shields.io/pypi/v/sphinxcontrib-verilog-diagrams.svg
-   :target: https://pypi.python.org/pypi/sphinxcontrib-verilog-diagrams
+.. image:: https://img.shields.io/pypi/v/sphinxcontrib-hdl-diagrams.svg
+   :target: https://pypi.python.org/pypi/sphinxcontrib-hdl-diagrams
    :alt: PyPI
 
 
-.. image:: https://img.shields.io/pypi/pyversions/sphinxcontrib-verilog-diagrams.svg
-   :target: https://pypi.python.org/pypi/sphinxcontrib-verilog-diagrams
+.. image:: https://img.shields.io/pypi/pyversions/sphinxcontrib-hdl-diagrams.svg
+   :target: https://pypi.python.org/pypi/sphinxcontrib-hdl-diagrams
    :alt: PyPI version
 
 
-.. image:: https://readthedocs.org/projects/sphinxcontrib-verilog-diagrams/badge
-   :target: https://sphinxcontrib-verilog-diagrams.readthedocs.io/en/latest/
+.. image:: https://readthedocs.org/projects/sphinxcontrib-hdl-diagrams/badge
+   :target: https://sphinxcontrib-hdl-diagrams.readthedocs.io/en/latest/
    :alt: Documentation
 
 
-.. image:: https://travis-ci.com/SymbiFlow/sphinxcontrib-verilog-diagrams.svg?branch=master
-   :target: https://travis-ci.com/SymbiFlow/sphinxcontrib-verilog-diagrams
+.. image:: https://travis-ci.com/SymbiFlow/sphinxcontrib-hdl-diagrams.svg?branch=master
+   :target: https://travis-ci.com/SymbiFlow/sphinxcontrib-hdl-diagrams
    :alt: Build Status
 
 
-.. image:: https://codecov.io/gh/SymbiFlow/sphinxcontrib-verilog-diagrams/branch/master/graph/badge.svg
-   :target: https://codecov.io/gh/SymbiFlow/sphinxcontrib-verilog-diagrams
+.. image:: https://codecov.io/gh/SymbiFlow/sphinxcontrib-hdl-diagrams/branch/master/graph/badge.svg
+   :target: https://codecov.io/gh/SymbiFlow/sphinxcontrib-hdl-diagrams
    :alt: codecov
 
 
 ----
 
-Sphinx Extension which generates various types of diagrams from Verilog code.
+Sphinx Extension which generates various types of diagrams from HDL code, supporting Verilog,
+nMigen and RTLIL.
 
-`sphinxcontrib-verilog-diagrams <https://github.com/SymbiFlow/sphinxcontrib-verilog-diagrams>`_
+`sphinxcontrib-hdl-diagrams <https://github.com/SymbiFlow/sphinxcontrib-hdl-diagrams>`_
 is a Sphinx extension to make it easier to write nice documentation from
-Verilog files. It primarily uses `Yosys <https://github.com/YosysHQ/yosys>`_ to do the Verilog reading.
+HDL source files. It primarily uses `Yosys <https://github.com/YosysHQ/yosys>`_ to read the source files
+and generate the diagrams.
 
-Check out the `documentation <https://sphinxcontrib-verilog-diagrams.readthedocs.io/en/latest>`_ for examples.
+Check out the `documentation <https://sphinxcontrib-hdl-diagrams.readthedocs.io/en/latest>`_ for examples.
 
 Installation
 ------------
@@ -44,13 +46,13 @@ Python 3.5+ is required.
 
 .. code-block::
 
-   pip install sphinxcontrib-verilog-diagrams
+   pip install sphinxcontrib-hdl-diagrams
 
 Or,
 
 .. code-block::
 
-   python3 -m pip install sphinxcontrib-verilog-diagrams
+   python3 -m pip install sphinxcontrib-hdl-diagrams
 
 Sphinx Integration
 ^^^^^^^^^^^^^^^^^^
@@ -61,7 +63,7 @@ In your conf.py, add the following lines.
 
    extensions = [
        ...,
-       'sphinxcontrib_verilog_diagrams',
+       'sphinxcontrib_hdl_diagrams',
    ]
 
 Non-Python Dependencies
@@ -107,15 +109,15 @@ Optional
 Usage
 -----
 
-``verilog-diagram``
+``hdl-diagram``
 ^^^^^^^^^^^^^^^^^^^
 
-The ``verilog-diagram`` RST directive can be used to generate a diagram from Verilog code and include it in your documentation.
-Check out the `examples <https://sphinxcontrib-verilog-diagrams.readthedocs.io/en/latest/>`_ to see how to use it.
+The ``hdl-diagram`` RST directive can be used to generate a diagram from Verilog code and include it in your documentation.
+Check out the `examples <https://sphinxcontrib-hdl-diagrams.readthedocs.io/en/latest/>`_ to see how to use it.
 
 .. code-block:: rst
 
-   .. verilog-diagram:: file.v
+   .. hdl-diagram:: file.v
       :type: XXXXX
       :module: XXXX
       :skin: XXXX
@@ -125,7 +127,7 @@ Check out the `examples <https://sphinxcontrib-verilog-diagrams.readthedocs.io/e
 Options
 ~~~~~~~
 
-``:type:`` - Verilog Diagram Types;
+``:type:`` - HDL Diagram Types;
 
 
 * ``yosys-blackbox`` - Netlist rendered by Yosys.

compat/setup.py

@@ -0,0 +1,63 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+#
+# Copyright (C) 2020  The SymbiFlow Authors.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+# SPDX-License-Identifier: Apache-2.0
+
+import sys
+from os import path
+
+from setuptools import setup, find_packages
+
+__dir__ = path.dirname(path.abspath(__file__))
+readme_file = path.join(__dir__, '../README.rst')
+try:
+    with open(readme_file) as f:
+        readme = f.read()
+except FileNotFoundError as e:
+    import traceback
+    traceback.print_exc()
+    readme = ''
+    __version__ = 'error'
+
+install_requires = [
+    'sphinxcontrib-hdl-diagrams'
+]
+
+setup(
+    name='sphinxcontrib-verilog-diagrams',
+    version="0.1.0",
+    description='Generate diagrams from Verilog in Sphinx.',
+    long_description=readme,
+    long_description_content_type="text/x-rst",
+    author="The SymbiFlow Authors",
+    author_email='symbiflow@lists.librecores.org',
+    url='https://github.com/SymbiFlow/sphinxcontrib-hdl-diagrams',
+    packages=find_packages(),
+    license="Apache 2.0",
+    keywords='Verilog sphinx sphinx-extension netlistsvg FPGA',
+    classifiers=[
+        'Development Status :: 4 - Beta',
+        'Framework :: Sphinx :: Extension',
+        'Intended Audience :: Developers',
+        'License :: OSI Approved :: Apache Software License',
+        'Natural Language :: English',
+        'Programming Language :: Python :: 3.5',
+        'Programming Language :: Python :: 3.6',
+        'Topic :: Text Processing',
+    ],
+    install_requires=install_requires,
+)

compat/sphinxcontrib_verilog_diagrams/__init__.py

@@ -0,0 +1,11 @@
+import warnings
+import sphinxcontrib_hdl_diagrams
+
+def setup(app):
+    deprecation_msg = """
+    sphinxcontrib-verilog-diagram extension is depreciated!
+    Please use sphinxcontrib-hdl-diagrams instead:
+    https://github.com/SymbiFlow/sphinxcontrib-hdl-diagrams"""
+    warnings.warn(deprecation_msg, DeprecationWarning)
+
+    return sphinxcontrib_hdl_diagrams.setup(app)

docs/Makefile

@@ -7,7 +7,7 @@ MAKEDIR := $(dir $(lastword $(MAKEFILE_LIST)))
 SPHINXOPTS      =
 SPHINXBUILD     = [ -e env/bin/activate ] && source env/bin/activate; sphinx-build
 SPHINXAUTOBUILD = [ -e env/bin/activate ] && source env/bin/activate; sphinx-autobuild
-SPHINXPROJ      = SphinxVerilog
+SPHINXPROJ      = SphinxContribHDLDiagramsDocs
 SOURCEDIR       = .
 BUILDDIR        = _build
 

docs/code/nmigen/counter.py

@@ -0,0 +1,35 @@
+# Copyright (C) 2020  The SymbiFlow Authors.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+# SPDX-License-Identifier: Apache-2.0
+
+
+from nmigen import *
+from nmigen.back import rtlil
+
+
+class Counter(Elaboratable):
+    def __init__(self, width):
+        self.v = Signal(width, reset=2**width-1)
+        self.o = Signal()
+
+    def elaborate(self, platform):
+        m = Module()
+        m.d.sync += self.v.eq(self.v + 1)
+        m.d.comb += self.o.eq(self.v[-1])
+        return m
+
+
+ctr = Counter(width=16)
+print(rtlil.convert(ctr, ports=[ctr.o]))