doc: use BuildTheDocs, add CI workflow

Author: umarcor

.btd.yml

@@ -0,0 +1,5 @@
+input: doc
+output: _build
+target: gh-pages
+formats: [ html ]
+theme: https://codeload.github.com/buildthedocs/sphinx.theme/tar.gz/v1

.github/workflows/Test.yml

@@ -0,0 +1,28 @@
+name: Doc
+
+on:
+  push:
+  schedule:
+    - cron: '0 0 * * 5'
+  workflow_dispatch:
+
+jobs:
+
+  BTD:
+    name: '📓 Docs'
+    runs-on: ubuntu-latest
+    steps:
+
+      - name: '🧰 Checkout'
+        uses: actions/checkout@v2
+
+      - name: '📓 BuildTheDocs (BTD)'
+        uses: buildthedocs/btd@v0
+        with:
+          token: ${{ github.token }}
+
+      - name: '📤 Upload artifact: HTML'
+        uses: actions/upload-artifact@master
+        with:
+          name: doc
+          path: doc/_build/html

.gitignore

@@ -4,3 +4,5 @@ build/
 
 .idea/
 
+/doc/_build
+/doc/_theme

README.rst

@@ -1,34 +1,43 @@
-
-========
 Hdlparse
-========
+########
 
-Hdlparse is a simple package implementing a rudimentary parser for VHDL and Verilog. It is not capable of fully parsing the entire language. Rather, it is meant to extract enough key information from a source file to create generated documentation.
+Hdlparse is a simple package implementing a rudimentary parser for VHDL and Verilog.
+It is not capable of fully parsing the entire language.
+Rather, it is meant to extract enough key information from a source file to create generated documentation.
 
-This library is forked from `kevinpt <https://github.com/kevinpt/hdlparse>`_ via `zhelnio <https://github.com/zhelnio/hdlparse>`_. The aim of this fork is to provide some bug fixes and additional features to zhelnio's version of Hdlparse. A list of changes is included at the bottom of this README.
+This library is used by the `Symbolator <https://github.com/hdl/symbolator>`_ diagram generator.
 
-For VHDL this library can extract component, subprogram, type, subtype, and constant declarations from a package. For Verilog it can extract module declarations (both 1995 and 2001 syntax).
+For VHDL this library can extract component, subprogram, type, subtype, and constant declarations from a package.
+For Verilog it can extract module declarations (both 1995 and 2001 syntax).
 
 
 Requirements
 ------------
 
-Hdlparse requires Python 3.x and no additional libraries. This version of Hdlparse is not compatible with Python2.
+Hdlparse requires Python3 and no additional libraries. This version of Hdlparse is not compatible with Python2.
 
 
 Download
 --------
 
-You can access the Hdlparse Git repository from `Github
-<https://github.com/vvvverre/hdlparse>`_. You can install direct from PyPI with the "pip"
-command if you have it available.
+You can access the Hdlparse Git repository from `Github <https://github.com/hdl/pyHDLParser>`_.
+You can install direct from PyPI with the "pip" command if you have it available.
+
 
 Installation
 ------------
 
-Hdlparse is a Python library. You must have Python installed first to use it. Most modern Linux distributions and OS/X have it available by default. There are a number of options available for Windows. If you don't already have a favorite, I recommend getting one of the `"full-stack" Python distros <http://www.scipy.org/install.html>`_ that are geared toward scientific computing such as Anaconda or Python(x,y).
+Hdlparse is a Python library.
+You must have Python installed first to use it.
+Most modern Linux distributions and OS/X have it available by default.
+There are a number of options available for Windows.
+If you don't already have a favorite, I recommend getting one of the
+`"full-stack" Python distros <http://www.scipy.org/install.html>`_
+that are geared toward scientific computing such as Anaconda or Python(x,y).
 
-You need to have the Python setuptools installed first. If your OS has a package manager, it may be preferable to install setuptools through that tool. Otherwise you can use Pip:
+You need to have the Python setuptools installed first.
+If your OS has a package manager, it may be preferable to install setuptools through that tool.
+Otherwise you can use Pip:
 
 .. code-block:: sh
 
@@ -40,7 +49,9 @@ The easiest way to install Hdlparse is from `PyPI <https://pypi.python.org/pypi/
 
   > pip install --upgrade hdlparse
 
-This will download and install the latest release, upgrading if you already have it installed. If you don't have ``pip`` you may have the ``easy_install`` command available which can be used to install ``pip`` on your system:
+This will download and install the latest release, upgrading if you already have it installed.
+If you don't have ``pip`` you may have the ``easy_install`` command available which can be used to install ``pip`` on
+your system:
 
 .. code-block:: sh
 
@@ -51,9 +62,10 @@ You can also use ``pip`` to get the latest development code from Github:
 
 .. code-block:: sh
 
-  > pip install --upgrade https://github.com/vvvverre/hdlparse/tarball/master
+  > pip install --upgrade https://github.com/hdl/pyHDLParser/tarball/main
 
-If you manually downloaded a source package or created a clone with Git you can install with the following command run from the base Hdlparse directory:
+If you manually downloaded a source package or created a clone with Git you can install with the following command run
+from the base Hdlparse directory:
 
 .. code-block:: sh
 
@@ -68,7 +80,7 @@ Documentation
 -------------
 
 The full documentation is available online at the `main Hdlparse site
-<http://kevinpt.github.io/hdlparse/>`_.
+<http://hdl.github.io/pyHDLParser/>`_.
 
 
 Changes

doc/.nojekyll

@@ -1,20 +1,37 @@
-# Minimal makefile for Sphinx documentation
-#
-
-# You can set these variables from the command line.
+# Sphinx options.
 SPHINXOPTS    =
-SPHINXBUILD   = python -msphinx
-SPHINXPROJ    = HdlParse
-SOURCEDIR     = .
+SPHINXBUILD   = sphinx-build
+SPHINXPROJ    = pyHDLParser
+PAPER         =
 BUILDDIR      = _build
 
-# Put it first so that "make" without argument is like "make help".
+PAPEROPT_a4     = -D latex_paper_size=a4
+PAPEROPT_letter = -D latex_paper_size=letter
+ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees -T -D language=en $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+
 help:
 	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
+#---
+
+man:
+	$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
+
+#---
+
+html:
+	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+
+#---
+
+latex:
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+
+#---
+
 .PHONY: help Makefile
 
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
 %: Makefile
-	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)