sphinxcontrib-hdl-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-hdl-diagrams.svg
:target: https://pypi.python.org/pypi/sphinxcontrib-hdl-diagrams
:alt: PyPI version
.. 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-hdl-diagrams.svg?branch=master
:target: https://travis-ci.com/SymbiFlow/sphinxcontrib-hdl-diagrams
:alt: Build Status
.. 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 HDL code, supporting Verilog,
nMigen and RTLIL.
`sphinxcontrib-hdl-diagrams <https://github.com/SymbiFlow/sphinxcontrib-hdl-diagrams>`_
is a Sphinx extension to make it easier to write nice documentation from
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-hdl-diagrams.readthedocs.io/en/latest>`_ for examples.
Installation
------------
Python 3.5+ is required.
.. code-block::
pip install sphinxcontrib-hdl-diagrams
Or,
.. code-block::
python3 -m pip install sphinxcontrib-hdl-diagrams
Sphinx Integration
^^^^^^^^^^^^^^^^^^
In your conf.py, add the following lines.
.. code-block:: python
extensions = [
...,
'sphinxcontrib_hdl_diagrams',
]
Non-Python Dependencies
^^^^^^^^^^^^^^^^^^^^^^^
These dependencies can be either installed on your system or install using the
conda ``environment.yml`` file with;
.. code-block:: bash
conda XXXX
Required
~~~~~~~~
* |yosys|_
.. |yosys| replace:: ``yosys``
.. _yosys: https://github.com/YosysHQ/yosys
By default, ``verilog-diagram`` uses the ``yowasp-yosys`` package provided in PyPI.
It can be installed by running ``pip install -r requirements.txt``.
However, you could also use Yosys that is installed on your system,
or point to the specific Yosys binary using ``verilog_diagram_yosys`` variable
in the Sphinx ``conf.py`` file:
To use Yosys that is available in your system, use the following setting::
verilog_diagram_yosys = "system"
If you want to point to the specific Yosys binary, provide the path to the program::
verilog_diagram_yosys = "<path-to-Yosys>"
Optional
~~~~~~~~
* |netlistsvg|_
.. |netlistsvg| replace:: ``netlistsvg``
.. _netlistsvg: https://github.com/nturley/netlistsvg
Usage
-----
``hdl-diagram``
^^^^^^^^^^^^^^^^^^^
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
.. hdl-diagram:: file.v
:type: XXXXX
:module: XXXX
:skin: XXXX
:yosys_script: XXXX
:flatten:
Options
~~~~~~~
``:type:`` - HDL Diagram Types;
* ``yosys-blackbox`` - Netlist rendered by Yosys.
* ``yosys-aig`` - Verilog file run through ``aigmap`` before image is generated directly in Yosys.
* ``netlistsvg`` - Render output with `netlistsvg <https://github.com/nturley/netlistsvg>`_
``:module:`` - Which module to diagram.
``:flatten:`` - Use the Yosys ``flatten`` command before generating the image.
Example
~~~~~~~
Here is a diagram of a 4-bit carry chain.
.. image:: ./carry4-flatten.svg
:target: ./carry4-flatten.svg
:alt: 4-bit carry chain
``no-license``
^^^^^^^^^^^^^^
This extension also provides the ``no-license`` directive which can be used to include code blocks from a file, but omitting the license header
at the top of the file. It behaves like the ``literalinclude`` directive, but the ``lines`` option is overridden to only show the lines after the license header.
.. code-block:: rst
.. no-license:: verilog/dff.v
:language: verilog
:linenos:
:caption: verilog/dff.v
Example
~~~~~~~
Here is a comparison between the ``literalinclude`` and ``no-license`` directives.
.. code-block:: rst
.. literalinclude:: verilog/dff.v
:language: verilog
:caption: verilog/dff.v
.. code-block:: verilog
/*
* Copyright (C) 2020-2021 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
*/
// Single flip-flip test.
module top(input clk, input di, output do);
always @( posedge clk )
do <= di;
endmodule // top
.. code-block:: rst
.. no-license:: verilog/dff.v
:language: verilog
:caption: verilog/dff.v
.. code-block:: verilog
// Single flip-flip test.
module top(input clk, input di, output do);
always @( posedge clk )
do <= di;
endmodule // top
Licence
-------
`Apache 2.0 <LICENSE>`_
Raw data
{
"_id": null,
"home_page": "https://github.com/SymbiFlow/sphinxcontrib-hdl-diagrams",
"name": "sphinxcontrib-hdl-diagrams",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "Verilog nMigen RTLIL yosys HDL sphinx sphinx-extension netlistsvg FPGA",
"author": "SymbiFlow Authors",
"author_email": "symbiflow@lists.librecores.org",
"download_url": "https://files.pythonhosted.org/packages/0d/ad/b51f1b2b4c3b3fd1c854f705d3d97addf47354c1c3d41ba7d7c0b9b58f94/sphinxcontrib-hdl-diagrams-0.0.post160.tar.gz",
"platform": null,
"description": "sphinxcontrib-hdl-diagrams\n==============================\n\n\n.. image:: https://img.shields.io/pypi/v/sphinxcontrib-hdl-diagrams.svg\n :target: https://pypi.python.org/pypi/sphinxcontrib-hdl-diagrams\n :alt: PyPI\n\n\n.. image:: https://img.shields.io/pypi/pyversions/sphinxcontrib-hdl-diagrams.svg\n :target: https://pypi.python.org/pypi/sphinxcontrib-hdl-diagrams\n :alt: PyPI version\n\n\n.. image:: https://readthedocs.org/projects/sphinxcontrib-hdl-diagrams/badge\n :target: https://sphinxcontrib-hdl-diagrams.readthedocs.io/en/latest/\n :alt: Documentation\n\n\n.. image:: https://travis-ci.com/SymbiFlow/sphinxcontrib-hdl-diagrams.svg?branch=master\n :target: https://travis-ci.com/SymbiFlow/sphinxcontrib-hdl-diagrams\n :alt: Build Status\n\n\n.. image:: https://codecov.io/gh/SymbiFlow/sphinxcontrib-hdl-diagrams/branch/master/graph/badge.svg\n :target: https://codecov.io/gh/SymbiFlow/sphinxcontrib-hdl-diagrams\n :alt: codecov\n\n\n----\n\nSphinx Extension which generates various types of diagrams from HDL code, supporting Verilog,\nnMigen and RTLIL.\n\n`sphinxcontrib-hdl-diagrams <https://github.com/SymbiFlow/sphinxcontrib-hdl-diagrams>`_\nis a Sphinx extension to make it easier to write nice documentation from\nHDL source files. It primarily uses `Yosys <https://github.com/YosysHQ/yosys>`_ to read the source files\nand generate the diagrams.\n\nCheck out the `documentation <https://sphinxcontrib-hdl-diagrams.readthedocs.io/en/latest>`_ for examples.\n\nInstallation\n------------\n\nPython 3.5+ is required.\n\n.. code-block::\n\n pip install sphinxcontrib-hdl-diagrams\n\nOr,\n\n.. code-block::\n\n python3 -m pip install sphinxcontrib-hdl-diagrams\n\nSphinx Integration\n^^^^^^^^^^^^^^^^^^\n\nIn your conf.py, add the following lines.\n\n.. code-block:: python\n\n extensions = [\n ...,\n 'sphinxcontrib_hdl_diagrams',\n ]\n\nNon-Python Dependencies\n^^^^^^^^^^^^^^^^^^^^^^^\n\nThese dependencies can be either installed on your system or install using the\nconda ``environment.yml`` file with;\n\n.. code-block:: bash\n\n conda XXXX\n\nRequired\n~~~~~~~~\n\n* |yosys|_\n\n.. |yosys| replace:: ``yosys``\n.. _yosys: https://github.com/YosysHQ/yosys\n\nBy default, ``verilog-diagram`` uses the ``yowasp-yosys`` package provided in PyPI.\nIt can be installed by running ``pip install -r requirements.txt``.\nHowever, you could also use Yosys that is installed on your system,\nor point to the specific Yosys binary using ``verilog_diagram_yosys`` variable\nin the Sphinx ``conf.py`` file:\n\nTo use Yosys that is available in your system, use the following setting::\n\n verilog_diagram_yosys = \"system\"\n\nIf you want to point to the specific Yosys binary, provide the path to the program::\n\n verilog_diagram_yosys = \"<path-to-Yosys>\"\n\nOptional\n~~~~~~~~\n\n* |netlistsvg|_\n\n.. |netlistsvg| replace:: ``netlistsvg``\n.. _netlistsvg: https://github.com/nturley/netlistsvg\n\nUsage\n-----\n\n``hdl-diagram``\n^^^^^^^^^^^^^^^^^^^\n\nThe ``hdl-diagram`` RST directive can be used to generate a diagram from Verilog code and include it in your documentation.\nCheck out the `examples <https://sphinxcontrib-hdl-diagrams.readthedocs.io/en/latest/>`_ to see how to use it.\n\n.. code-block:: rst\n\n .. hdl-diagram:: file.v\n :type: XXXXX\n :module: XXXX\n :skin: XXXX\n :yosys_script: XXXX\n :flatten:\n\nOptions\n~~~~~~~\n\n``:type:`` - HDL Diagram Types;\n\n\n* ``yosys-blackbox`` - Netlist rendered by Yosys.\n* ``yosys-aig`` - Verilog file run through ``aigmap`` before image is generated directly in Yosys.\n* ``netlistsvg`` - Render output with `netlistsvg <https://github.com/nturley/netlistsvg>`_\n\n``:module:`` - Which module to diagram.\n\n``:flatten:`` - Use the Yosys ``flatten`` command before generating the image.\n\nExample\n~~~~~~~\n\nHere is a diagram of a 4-bit carry chain.\n\n\n.. image:: ./carry4-flatten.svg\n :target: ./carry4-flatten.svg\n :alt: 4-bit carry chain\n\n\n``no-license``\n^^^^^^^^^^^^^^\n\nThis extension also provides the ``no-license`` directive which can be used to include code blocks from a file, but omitting the license header\nat the top of the file. It behaves like the ``literalinclude`` directive, but the ``lines`` option is overridden to only show the lines after the license header.\n\n.. code-block:: rst\n\n\n .. no-license:: verilog/dff.v\n :language: verilog\n :linenos:\n :caption: verilog/dff.v\n\nExample\n~~~~~~~\n\nHere is a comparison between the ``literalinclude`` and ``no-license`` directives.\n\n.. code-block:: rst\n\n .. literalinclude:: verilog/dff.v\n :language: verilog\n :caption: verilog/dff.v\n\n.. code-block:: verilog\n\n /*\n * Copyright (C) 2020-2021 The SymbiFlow Authors.\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n * https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n *\n * SPDX-License-Identifier: Apache-2.0\n */\n\n // Single flip-flip test.\n module top(input clk, input di, output do);\n always @( posedge clk )\n do <= di;\n endmodule // top\n\n.. code-block:: rst\n\n .. no-license:: verilog/dff.v\n :language: verilog\n :caption: verilog/dff.v\n\n.. code-block:: verilog\n\n // Single flip-flip test.\n module top(input clk, input di, output do);\n always @( posedge clk )\n do <= di;\n endmodule // top\n\nLicence\n-------\n\n`Apache 2.0 <LICENSE>`_\n",
"bugtrack_url": null,
"license": "Apache 2.0",
"summary": "Generate diagrams from HDL in Sphinx.",
"version": "0.0.post160",
"project_urls": {
"Homepage": "https://github.com/SymbiFlow/sphinxcontrib-hdl-diagrams"
},
"split_keywords": [
"verilog",
"nmigen",
"rtlil",
"yosys",
"hdl",
"sphinx",
"sphinx-extension",
"netlistsvg",
"fpga"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "d54d2fd3394f327f52b8fea18b91e0e746ed245c893064a20ace06f23c87ea51",
"md5": "59915e88e01d2d3bcb4edb8b5bd5b363",
"sha256": "143b489e8c5a9082e8b00d4052e2781992e948f36ccdeedee39dcad226859c1a"
},
"downloads": -1,
"filename": "sphinxcontrib_hdl_diagrams-0.0.post160-py3-none-any.whl",
"has_sig": false,
"md5_digest": "59915e88e01d2d3bcb4edb8b5bd5b363",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 13747,
"upload_time": "2023-09-21T05:39:46",
"upload_time_iso_8601": "2023-09-21T05:39:46.762278Z",
"url": "https://files.pythonhosted.org/packages/d5/4d/2fd3394f327f52b8fea18b91e0e746ed245c893064a20ace06f23c87ea51/sphinxcontrib_hdl_diagrams-0.0.post160-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "0dadb51f1b2b4c3b3fd1c854f705d3d97addf47354c1c3d41ba7d7c0b9b58f94",
"md5": "919218e694e605b6e0de91ada44de9be",
"sha256": "7c05a7a0532247d06a21a121919ec902e9e7b8109b0da875c89311603ef4099d"
},
"downloads": -1,
"filename": "sphinxcontrib-hdl-diagrams-0.0.post160.tar.gz",
"has_sig": false,
"md5_digest": "919218e694e605b6e0de91ada44de9be",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 15436,
"upload_time": "2023-09-21T05:39:48",
"upload_time_iso_8601": "2023-09-21T05:39:48.512588Z",
"url": "https://files.pythonhosted.org/packages/0d/ad/b51f1b2b4c3b3fd1c854f705d3d97addf47354c1c3d41ba7d7c0b9b58f94/sphinxcontrib-hdl-diagrams-0.0.post160.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-09-21 05:39:48",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "SymbiFlow",
"github_project": "sphinxcontrib-hdl-diagrams",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "sphinxcontrib-hdl-diagrams"
}
JSON
