Initial commit

Author: Mariusz Glebocki

README.rst

@@ -0,0 +1,65 @@
+Sphinx Verilog Domain
+=====================
+
+.. warning::
+    This extension is in development stage.
+
+.. note::
+    This extension is not a part of sphinxcontrib yet.
+
+Dependencies
+------------
+
+* ``lark-parser``
+
+Enabling
+--------
+
+Add extension in ``conf.py``::
+
+    extensions = [ 'sphinxcontrib.verilogdomain' ]
+
+Usage
+-----
+
+Module headers (non-ANSI-style only for now)::
+
+    .. verilog::module:: module Top(a, b);
+
+Port declarations::
+
+    .. verilog:port:: input wire [31:0] a, b;
+
+Parameter declarations::
+
+    .. verilog:parameter:: parameter logic param_name_05 = 1, param_name_05_b = 2;
+
+Declaration aliases (for use with references)::
+
+    .. verilog:module:: module \35(4p3|) (z);
+        :alias: module_escaped
+
+References::
+
+    Reference to :verilog:ref:`Top`
+    Reference to :verilog:ref:`module_escaped`, or just :verilog:ref:`\\35(4p3|)`
+
+Nesting::
+
+    .. verilog:module:: module Top1(a, b, c);
+
+        .. verilog:port:: input a;
+
+            Description of port ``a``
+
+        .. verilog:port:: input b;
+
+            Description of port ``b``
+
+        .. verilog:module:: module Nested(a);
+
+            .. verilog:port:: output a;
+
+                Description of port ``a`` in ``Nested``
+
+            Reference to module ``Top1``'s port ``a``: :verilog:ref:`Top1.a`.

example/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    = -E -v
+SPHINXBUILD   = python -msphinx
+SPHINXPROJ    = verilogdomain-test
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%:
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

example/source/conf.py

@@ -0,0 +1,67 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+#
+import os
+import sys
+
+# -- General configuration ------------------------------------------------
+
+extensions = [
+]
+
+import warnings
+
+sys.path.append(os.path.abspath(os.path.dirname(__file__) + '/../../'))
+extensions = ['sphinxcontrib.verilogdomain']
+
+verilog_domain_debug = [
+    # "add_debug_content",
+    # "print_parser_tree",
+    # "print_add_target",
+    # "print_objects_tree",
+]
+
+source_suffix = '.rst'
+
+master_doc = 'index'
+
+html_theme = "alabaster"
+
+# General information about the project.
+project = 'sphinx-verilog-domain'
+copyright = '2018, Various'
+author = 'Various'
+
+# The version info for the project you're documenting, acts as replacement for
+# |version| and |release|, also used in various other places throughout the
+# built documents.
+#
+# The short X.Y version.
+version = '0.1'
+# The full version, including alpha/beta/rc tags.
+release = '0.1'
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#
+# This is also used if you do content translation via gettext catalogs.
+# Usually you set "language" from the command line for these cases.
+language = None
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This patterns also effect to html_static_path and html_extra_path
+exclude_patterns = []
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'default'
+
+# If true, `todo` and `todoList` produce output, else they produce nothing.
+todo_include_todos = False
+
+# -- Options for HTML output ----------------------------------------------
+
+html_js_files = [
+    'http://livejs.com/live.js'
+]
+

example/source/index.rst

@@ -0,0 +1,60 @@
+Verilog Domain test
+###################
+
+.. toctree::
+
+    port
+    parameter
+    module
+    nesting
+    nesting2
+
+----
+
+.. verilog:module:: module d (  \
+                        cos_z0, \
+                        sin_z0, \
+                        done,   \
+                        z0,     \
+                        start,  \
+                        clock,  \
+                        reset   \
+                    );
+
+   Sine and cosine computer. `Source <https://github.com/YosysHQ/yosys/blob/master/tests/simple/sincos.v>`_
+
+   This module computes the sine and cosine of an input angle. The
+   floating point numbers are represented as integers by scaling them
+   up with a factor corresponding to the number of bits after the point.
+
+   .. verilog:port:: output signed [19:0] cos_z0;
+                     reg signed [19:0] cos_z0;
+
+      cosine of the input angle
+
+   .. verilog:port:: output signed [19:0] sin_z0;
+                     reg signed [19:0] sin_z0;
+
+      sine of the input angle
+
+   .. verilog:port:: output done;
+                     reg done;
+
+      output flag indicated completion of the computation
+
+   .. verilog:port:: input signed [19:0] z0;
+
+      input angle
+
+   .. verilog:port:: input start;
+
+      input that starts the computation on a posedge
+
+   .. verilog:port:: input clock;
+
+      clock input
+
+   .. verilog:port:: input reset;
+
+      reset input
+

example/source/module.rst

@@ -0,0 +1,12 @@
+verilog:module
+**************
+
+.. verilog:module:: (* attr = 2 * 2 *) module test1(a,b,c,d,e,f,g,h);
+.. verilog:module:: module test2(a,b,c,d,e,f,g,h);
+.. verilog:module:: module complex_ports ( {c,d}, .e(f) );
+.. verilog:module:: module split_ports (a[7:4], a[3:0]);
+.. verilog:module:: module same_port (.a(i), .b(i));
+.. verilog:module:: module renamed_concat (.a({b,c}), f, .g(h[1]));
+.. verilog:module:: module same_input (a,a);
+.. verilog:module:: module mixed_direction (.p({a, e}));
+