Add configuration documentation

Signed-off-by: Michael Riegert <[email protected]>

README.rst

@@ -84,19 +84,19 @@ Required
 .. |yosys| replace:: ``yosys``
 .. _yosys: https://github.com/YosysHQ/yosys
 
-By default, ``verilog-diagram`` uses the ``yowasp-yosys`` package provided in PyPI.
+By default, ``hdl-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
+or point to the specific Yosys binary using ``hdl_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"
+    hdl_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>"
+    hdl_diagram_yosys = "<path-to-Yosys>"
 
 Optional
 ~~~~~~~~

docs/configuration/index.rst

@@ -0,0 +1,75 @@
+Configuration
+=============
+
+This is the list of possible configurations that go in ``conf.py``.
+
+Yosys
++++++
+
+``hdl_diagram_yosys`` tells the program what version or binary of Yosys to use.
+By default it is set to ``YoWASP``. Setting it to ``system``, the program will
+use Yosys available in the current PATH. It can also contain the path to a specific
+Yosys binary.::
+
+    hdl_diagram_yosys = "yowasp" # default
+
+    hdl_diagram_yosys = "system" # use yosys from PATH
+
+    hdl_diagram_yosys = "<path-to-Yosys>" # use specific yosys binary
+
+
+netlistsvg
+++++++++++
+
+netlistsvg can take various skin files for use when creating diagrams. It is
+set to ``default`` by default, using the built-in netlistsvg skin.::
+
+    hdl_diagram_skin = "<path-to-skin>"
+
+
+Output format
++++++++++++++
+
+The output format for the generated diagrams can either be set to ``svg`` or ``png``.::
+
+    hdl_diagram_output_format = "svg"
+
+    hdl_diagram_output_format = "png"
+
+
+GHDL
+++++
+
+GHDL can either be prebuilt into Yosys or loaded at runtime. If it is loaded at
+runtime, then this can either be set to ``module`` if GHDL is in the PATH, or
+a path to the ``ghdl.so`` shared library. ::
+
+    hdl_diagram_ghdl = "module" # default, passes `-m ghdl` to Yosys
+
+    hdl_diagram_ghdl = "prebuilt" # if GHDL is built into Yosys
+
+    hdl_diagram_ghdl = "<path-to-GHDL-shared-library>" # path to specific ghdl.so
+
+
+Common Errors
++++++++++++++
+
+.. code-block::
+
+    ERROR:
+      This version of Yosys cannot load plugins at runtime.
+      Some plugins may have been included at build time.
+      Use option `-H' to see the available built-in and plugin commands.
+
+This error signifies that the current version of Yosys cannot load plugins
+at runtime, and so all plugins must be prebuit. For VHDL, ``hdl_diagram_ghdl``
+must be set to ``prebuilt``.
+
+.. code-block::
+
+    ERROR: Can't guess frontend for input file `' (missing -f option)!
+
+This error signifies that the version of Yosys being used cannot figure out
+how to interpret the input file. For VHDL, this signifies that either GHDL
+isn't being loaded properly, or that the current version of Yosys isn't compatible
+with GHDL.

docs/index.rst

@@ -8,9 +8,9 @@ RTLIL, or VHDL code.
 You use the |hdl-diagram|_ RST directive to generate various styles of
 diagrams from HDL code.
 
-Most of the time there will be a license header at the top of source code, 
-which we might not want to show in the documentation. 
-This extension also provides the |no-license|_ RST directive which works exactly 
+Most of the time there will be a license header at the top of source code,
+which we might not want to show in the documentation.
+This extension also provides the |no-license|_ RST directive which works exactly
 like the `.. literalinclude` directive, but the `lines` option is overridden
 to only show the lines after the license header.
 
@@ -107,6 +107,7 @@ So, refer to `literalinclude` for the available options.
    :maxdepth: 1
    :glob:
    :hidden:
-
+
+   configuration/index
    directives/index
    examples/index