https://github.com/SymbiFlow/sphinx-verilog-domain

Sphinx domain to allow integration of Verilog / SystemVerilog documentation into Sphinx.
https://github.com/SymbiFlow/sphinx-verilog-domain

hdl rtl sphinx sphinx-domain sphinx-extension systemverilog verilog verilog-library

Last synced: 2 months ago
JSON representation

Sphinx domain to allow integration of Verilog / SystemVerilog documentation into Sphinx.

• Host: GitHub
• URL: https://github.com/SymbiFlow/sphinx-verilog-domain
• Owner: SymbiFlow
• License: apache-2.0
• Created: 2020-08-11T10:27:44.000Z (over 4 years ago)
• Default Branch: master
• Last Pushed: 2021-03-01T19:21:24.000Z (almost 4 years ago)
• Last Synced: 2024-10-28T17:19:32.087Z (3 months ago)
• Topics: hdl, rtl, sphinx, sphinx-domain, sphinx-extension, systemverilog, verilog, verilog-library
• Language: Python
• Homepage: https://sphinx-verilog-domain.rtfd.io
• Size: 17.4 MB
• Stars: 21
• Watchers: 15
• Forks: 7
• Open Issues: 7
• Metadata Files:
  • Readme: README.rst
  • License: LICENSE

Awesome Lists containing this project

• awesome-opensource-hardware - sphinx-verilog-domain

README

        
sphinx-verilog-domain

=====================

.. warning::

    This extension is in development stage.

Dependencies

------------

* ``lark-parser``

Enabling

--------

Add extension in ``conf.py``::

    extensions = [ 'sphinx_verilog_domain' ]

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;

Custom name for use in references::

    .. verilog:module:: module \35(4p3|) (z);

        :refname: module_escaped

References::

    Reference to :verilog:ref:`Top`

    Reference to :verilog:ref:`module_escaped` - links to ``\\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`.

Namespaces

^^^^^^^^^^

There are three directives for changing current Verilog scope:

* ``.. verilog:namespace:: A::B`` - sets current scope to ``A::B``. Using ``$root`` as an argument or using the directive without argument at all sets global namespace.

* ``.. verilog:namespace-push:: C::D`` - sets current scope to ``C::D`` relatively to current scope

* ``.. verilog:namespace-pop::`` - restores scope which was active before previous ``namespace-push`` was called. If there is no matching ``namespace-push``, scope is set to global scope.

.. note::

    ``verilog::namespace`` resets push/pop stack

Example::

    .. verilog:namespace:: A::B

    .. verilog:port:: input inside_a_b;

    .. verilog:namespace-push:: C::D

    .. verilog:port:: input inside_a_b_c_d;

    .. verilog:namespace-pop::

    .. verilog:port:: input inside_a_b_again;

    .. verilog:namespace::

    .. verilog:port:: input in_global_namespace;

Development

-----------

To create and open the development environment with all system

and python packages use::

   make env

   source env/conda/bin/activate sphinx-verilog-domain

Licence

-------

`Apache 2.0 `_