Add documentation on using GHDL/VHDL

Author: nobodywasishere

README.rst

@@ -30,7 +30,7 @@ sphinxcontrib-hdl-diagrams
 ----
 
 Sphinx Extension which generates various types of diagrams from HDL code, supporting Verilog,
-nMigen and RTLIL.
+nMigen, RTLIL, and VHDL.
 
 `sphinxcontrib-hdl-diagrams <https://github.com/SymbiFlow/sphinxcontrib-hdl-diagrams>`_
 is a Sphinx extension to make it easier to write nice documentation from
@@ -106,6 +106,25 @@ Optional
 .. |netlistsvg| replace:: ``netlistsvg``
 .. _netlistsvg: https://github.com/nturley/netlistsvg
 
+* |ghdl|_
+
+.. |ghdl| replace:: ``ghdl``
+.. _ghdl: https://github.com/ghdl/ghdl
+
+GHDL and ghdl-yosys-plugin are required for VHDL support. If GHDL is prebuilt into Yosys,
+add this configuration option to let Yosys know::
+
+    hdl_diagram_ghdl = "prebuilt"
+
+Otherwise, to load GHDL as a runtime module, set this configuration option to::
+
+    hdl_diagram_ghdl = "module"
+
+Which will pass ``-m ghdl`` to Yosys when calling it. Similarly, setting this to the path of a
+ghdl-yosys-plugin shared library will also work.
+
+Unfortunately, at this time GHDL and ghdl-yosys-plugin aren't supported by YoWASP.
+
 Usage
 -----
 

docs/code/vhdl/alu.vhdl

@@ -0,0 +1,23 @@
+library IEEE;
+use IEEE.std_logic_1164.all;
+use IEEE.numeric_std.all;
+
+entity top is
+    port(
+        a : in unsigned(3 downto 0);
+        b : in unsigned(3 downto 0);
+        s : in unsigned(1 downto 0);
+        y : out unsigned(3 downto 0)
+    );
+end top;
+
+architecture rtl of top is
+
+begin
+
+    y <= a when s="00" else
+        b when s="01" else
+        "0000" when s="10" else
+        a + b when s="11" else (others => '0');
+
+end;

docs/conf.py

@@ -58,6 +58,10 @@
     'sphinxcontrib_hdl_diagrams',
 ]
 
+# Uncomment for YosysHQ/fpga-toolchain
+# hdl_diagram_yosys = "system"
+# hdl_diagram_ghdl = "prebuilt"
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 

docs/examples/alu-vhdl.rst

@@ -0,0 +1,89 @@
+4 bit ALU in VHDL
+=================
+
+VHDL Code
++++++++++
+
+RST Directive
+*************
+
+.. code-block:: rst
+   :linenos:
+
+   .. no-license:: ../code/vhdl/alu.vhdl
+      :language: vhdl
+      :linenos:
+
+
+Result
+******
+
+.. no-license:: ../code/vhdl/alu.vhdl
+   :language: vhdl
+   :linenos:
+
+Yosys BlackBox Diagram
+++++++++++++++++++++++
+
+RST Directive
+*************
+
+.. code-block:: rst
+   :linenos:
+   :emphasize-lines: 2
+
+   .. hdl-diagram:: ../code/vhdl/alu.vhdl
+      :type: yosys-bb
+      :module: top
+
+Result
+******
+
+.. hdl-diagram:: ../code/vhdl/alu.vhdl
+   :type: yosys-bb
+   :module: top
+
+
+Yosys AIG Diagram
++++++++++++++++++
+
+RST Directive
+*************
+
+.. code-block:: rst
+   :linenos:
+   :emphasize-lines: 2
+
+   .. hdl-diagram:: ../code/vhdl/alu.vhdl
+      :type: yosys-aig
+      :module: top
+
+Result
+******
+
+.. hdl-diagram:: ../code/vhdl/alu.vhdl
+   :type: yosys-aig
+   :module: top
+
+
+NetlistSVG Diagram
+++++++++++++++++++
+
+RST Directive
+*************
+
+.. code-block:: rst
+   :linenos:
+   :emphasize-lines: 2
+
+   .. hdl-diagram:: ../code/vhdl/alu.vhdl
+      :type: netlistsvg
+      :module: top
+
+
+Result
+******
+
+.. hdl-diagram:: ../code/vhdl/alu.vhdl
+   :type: netlistsvg
+   :module: top

docs/examples/index.rst

@@ -4,6 +4,7 @@ Examples
 .. toctree::
    :maxdepth: 1
    :glob:
-   
+
    comb-full-adder
-   carry4
+   carry4
+   alu-vhdl

docs/index.rst

@@ -3,7 +3,7 @@ Sphinx HDL Diagrams
 
 sphinx-hdl-diagrams is an extension to Sphinx to make it easier to write
 nice documentation from HDL source files, in the form of Verilog, nMigen,
-or RTLIL code.
+RTLIL, or VHDL code.
 
 You use the |hdl-diagram|_ RST directive to generate various styles of
 diagrams from HDL code.
@@ -56,6 +56,7 @@ conda `environment.yml <https://github.com/SymbiFlow/sphinxcontrib-hdl-diagrams/
 
 - `yosys <https://github.com/YosysHQ/yosys>`_ (required)
 - `netlistsvg <https://github.com/nturley/netlistsvg>`_ (optional)
+- `GHDL <https://github.com/ghdl/ghdl>`_ (required for VHDL)
 
 Usage
 -----