Merge pull request #11 from PyFPGA/dev

Dev

Author: rodrigomelo9

.github/workflows/docs.yml

@@ -0,0 +1,26 @@
+name: 'docs'
+
+on:
+  push:
+    paths:
+      - 'docs/**'
+      - 'hdlconv/**'
+    branches:
+      - main
+      - dev
+
+jobs:
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+    - name: Checkout repository
+      uses: actions/checkout@v4
+    - name: Install dependencies
+      run: pip install . && pip install sphinx sphinx-rtd-theme
+    - name: Build documentation
+      run: make docs
+    - name: Deploy to GitHub Pages
+      uses: peaceiris/actions-gh-pages@v4
+      with:
+        github_token: ${{ secrets.GITHUB_TOKEN }}
+        publish_dir: docs/build/html

Makefile

@@ -5,7 +5,7 @@
 all: docs lint test
 
 docs:
-	bash docgen.sh
+	cd docs; make html
 
 lint:
 	pycodestyle hdlconv
@@ -17,5 +17,7 @@ test:
 
 clean:
 	py3clean .
+	rm -fr docs/build
 	rm -fr .pytest_cache
+	rm -fr `find . -name results`
 	rm -fr `find . -name __pycache__`

README.md

@@ -3,92 +3,6 @@
 HDL converter (between VHDL, SystemVerilog and/or Verilog), based on [GHDL](https://github.com/ghdl/ghdl), [Yosys](https://github.com/YosysHQ/yosys), [Synlig](https://github.com/chipsalliance/synlig) and the plugins [ghdl-yosys-plugin](https://github.com/ghdl/ghdl-yosys-plugin) and [yosys-slang](https://github.com/povik/yosys-slang).
 It relies on [Docker](https://docs.docker.com/get-docker) and [PyFPGA containers](https://github.com/PyFPGA/containers).
 
-> Known limitation: the files must be located either under the `$HOME` directory or under the current working directory (`$PWD`) for Docker to be able to find and access them.
-
 * `vhdl2vhdl`: converts from a newer VHDL to VHDL'93 (using `ghdl`).
 * `vhdl2vlog`: converts from VHDL to Verilog (backends: `ghdl` or `yosys`).
 * `slog2vlog`: converts from SystemVerilog to Verilog (frontends: `slang`, `synlig` or `yosys`).
-
-# Documentation
-
-```
-usage: vhdl2vhdl [-h] [-v] [--no-docker] [-g GENERIC VALUE] [-a ARCH]
-                 [-f FILENAME] [-o PATH] -t TOPNAME
-                 FILE[,LIBRARY] [FILE[,LIBRARY] ...]
-
-VHDL to VHDL
-
-positional arguments:
-  FILE[,LIBRARY]        VHDL file/s (with an optional LIBRARY specification)
-
-optional arguments:
-  -h, --help            show this help message and exit
-  -v, --version         show program's version number and exit
-  --no-docker           do not use Docker (use system tools instead)
-  -g GENERIC VALUE, --generic GENERIC VALUE
-                        specify a top-level Generic (can be specified multiple
-                        times)
-  -a ARCH, --arch ARCH  specify a top-level Architecture
-  -f FILENAME, --filename FILENAME
-                        resulting file name [<TOPNAME>.<EXT>]
-  -o PATH, --odir PATH  output directory [results]
-  -t TOPNAME, --top TOPNAME
-                        specify the top-level of the design
-```
-
-```
-usage: vhdl2vlog [-h] [-v] [--no-docker] [--backend TOOL] [-g GENERIC VALUE]
-                 [-a ARCH] [-f FILENAME] [-o PATH] -t TOPNAME
-                 FILE[,LIBRARY] [FILE[,LIBRARY] ...]
-
-VHDL to Verilog
-
-positional arguments:
-  FILE[,LIBRARY]        VHDL file/s (with an optional LIBRARY specification)
-
-optional arguments:
-  -h, --help            show this help message and exit
-  -v, --version         show program's version number and exit
-  --no-docker           do not use Docker (use system tools instead)
-  --backend TOOL        backend tool [ghdl]
-  -g GENERIC VALUE, --generic GENERIC VALUE
-                        specify a top-level Generic (can be specified multiple
-                        times)
-  -a ARCH, --arch ARCH  specify a top-level Architecture
-  -f FILENAME, --filename FILENAME
-                        resulting file name [<TOPNAME>.<EXT>]
-  -o PATH, --odir PATH  output directory [results]
-  -t TOPNAME, --top TOPNAME
-                        specify the top-level of the design
-```
-
-```
-usage: slog2vlog [-h] [-v] [--no-docker] [--frontend TOOL] [-p PARAM VALUE]
-                 [-d DEFINE VALUE] [-i PATH] [-f FILENAME] [-o PATH] -t
-                 TOPNAME
-                 FILE [FILE ...]
-
-SystemVerilog to Verilog
-
-positional arguments:
-  FILE                  System Verilog file/s
-
-optional arguments:
-  -h, --help            show this help message and exit
-  -v, --version         show program's version number and exit
-  --no-docker           do not use Docker (use system tools instead)
-  --frontend TOOL       frontend tool [slang]
-  -p PARAM VALUE, --param PARAM VALUE
-                        specify a top-level Parameter (can be specified
-                        multiple times)
-  -d DEFINE VALUE, --define DEFINE VALUE
-                        specify a Define (can be specified multiple times)
-  -i PATH, --include PATH
-                        specify an Include Path (can be specified multiple
-                        times)
-  -f FILENAME, --filename FILENAME
-                        resulting file name [<TOPNAME>.<EXT>]
-  -o PATH, --odir PATH  output directory [results]
-  -t TOPNAME, --top TOPNAME
-                        specify the top-level of the design
-```

docgen.sh

@@ -0,0 +1,20 @@
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = build
+HELPERS       = $(BUILDDIR)/vhdl2vhdl $(BUILDDIR)/vhdl2vlog $(BUILDDIR)/slog2vlog
+
+PYTHONPATH := $(PWD)/..
+export PYTHONPATH
+
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+$(HELPERS):
+	@mkdir -p $(@D)
+	@python3 ../hdlconv/$(@F).py -h > $@
+
+%: Makefile $(HELPERS)
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/Makefile

@@ -0,0 +1,39 @@
+# -*- coding: utf-8 -*-
+
+import sys, re
+from pathlib import Path
+
+sys.path.insert(0, str(Path.cwd().resolve().parent))
+
+# -- Project information -----------------------------------------------------
+
+project = 'HDLconv'
+copyright = '2023-2025, HDLconv Project'
+author = 'HDLconv contributors'
+
+# -- General configuration ---------------------------------------------------
+
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.extlinks',
+    'sphinx.ext.intersphinx',
+    'sphinx.ext.todo',
+    'sphinx.ext.viewcode',
+]
+
+autodoc_default_options = {
+    "members": True,
+    'undoc-members': True,
+    'inherited-members': True,
+}
+
+extlinks = {
+   'repositoy': ('https://github.com/PyFPGA/HDLconv/tree/main/%s', None)
+}
+
+exclude_patterns = ['build']
+
+# -- Options for HTML output -------------------------------------------------
+
+html_theme = 'sphinx_rtd_theme'
+html_static_path = ['images']

docs/conf.py

@@ -0,0 +1,19 @@
+HDLconv's documentation
+=======================
+
+.. image:: images/logo.png
+   :width: 200 px
+   :align: center
+   :target: https://github.com/PyFPGA/HDLconv
+
+.. toctree::
+
+   intro
+   tutorial
+   scripts
+
+.. |timestamp| date:: %Y-%m-%d %H:%M (%Z)
+
+.. note::
+
+   Documentation generated on |timestamp|.

docs/images/logo.png

@@ -0,0 +1,29 @@
+Introduction
+============
+
+HDL converter provides a set of command-line utilities for converting between VHDL, SystemVerilog, and Verilog.
+Those, gathers files and options, then orchestrates the execution of the following tools - either separately or in combination when required.
+
+* `GHDL <https://github.com/ghdl/ghdl>`_
+* `Yosys <https://github.com/YosysHQ/yosys>`_
+* `Synlig <https://github.com/chipsalliance/synlig>`_
+* `ghdl-yosys-plugin <https://github.com/ghdl/ghdl-yosys-plugin>`_
+* `yosys-slang <https://github.com/povik/yosys-slang>`_
+
+To avoid the need to install multiple tools, it relies on `Docker <https://docs.docker.com/get-docker>`_ and `PyFPGA containers <https://github.com/PyFPGA/containers>`_.
+
+Command-line utilities
+----------------------
+
+* ``vhdl2vhdl``: converts from a newer VHDL to VHDL'93.
+    * Solved using ``ghdl``.
+* ``vhdl2vlog``: converts from VHDL to Verilog. This has two alternatives:
+    * Purely ``ghdl`` (**default**).
+    * Uses ``ghdl-yosys-plugin`` as frontend and ``yosys`` as backend.
+* ``slog2vlog``: converts from SystemVerilog to Verilog. This has three alternatives:
+    * Uses ``yosys-slang`` as frontend and ``yosys`` as backend (**default**).
+    * Purely ``synlig`` (based on ``Surelog`` and ``yosys``).
+    * Purely ``yosys`` (simpler SV support, but could be sufficient in some cases).
+
+.. note::
+   Multiple alternatives are provided so you can try different options if one does not work.

docs/index.rst

@@ -0,0 +1,17 @@
+Scripts reference
+=================
+
+vhdl2vhdl
+---------
+
+.. literalinclude:: build/vhdl2vhdl
+
+vhdl2vlog
+---------
+
+.. literalinclude:: build/vhdl2vlog
+
+slog2vlog
+---------
+
+.. literalinclude:: build/slog2vlog