docs: Starting to get Sphinx going.

docs/.gitignore

@@ -0,0 +1,4 @@
+_build
+_venv
+tools
+.Makefile.d

docs/Makefile

@@ -1,20 +1,84 @@
 # Minimal makefile for Sphinx documentation
 #
 
+# Disable make's inbuilt rules
+.SUFFIXES:
+
+
 # You can set these variables from the command line.
 SPHINXOPTS    =
-SPHINXBUILD   = sphinx-build
+SPHINXBUILD   = $(VENV_ROOT)/bin/sphinx-build
 SPHINXPROJ    = SymbiFlowArchitectureDefinitions
 SOURCEDIR     = .
 BUILDDIR      = _build
+VENV_ROOT     = $(BUILDDIR)/_venv
+
+# Set up a virtualenv
+$(VENV_ROOT)/bin/python3:
+	virtualenv -p python3 $(VENV_ROOT)
+
+ACTIVATE = source $(VENV_ROOT)/bin/activate
 
 # Put it first so that "make" without argument is like "make help".
-help:
-	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+#-------------------------------------------
+help: $(SPHINXBUILD)
+	@$(SPHINXRUN) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help
+
+# Install the requirements into the virtualenv
+#-------------------------------------------
+$(VENV_ROOT)/requirements.stamp: requirements.txt $(VENV_ROOT)/bin/python3
+	$(ACTIVATE); pip install -r requirements.txt
+	@touch $(VENV_ROOT)/requirements.stamp
+
+$(SPHINXBUILD): $(VENV_ROOT)/requirements.stamp $(VENV_ROOT)/bin/python3
+	@touch $<
+
+distclean:
+	rm -rf _build $(VENV_ROOT) .Makefile.d
+	mkdir -p _build
+	mkdir -p $(VENV_ROOT)
+
+SPHINXRUN = $(ACTIVATE); $(VENV_ROOT)/bin/python3 $(VENV_ROOT)/bin/sphinx-build
+
+.PHONY: distclean
+
+# Generate targets for all the other sphinx commands.
+#-------------------------------------------
+SPHINXCMD = $(SPHINXRUN) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+SPHINXSUBCMD = $(SPHINXRUN) -M $$@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.Makefile.d: $(SPHINXBUILD) Makefile
+	$(SPHINXRUN) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) \
+		| grep "^ " \
+		| sed -e's/^ \+//' -e's|^\([^ ]*\) \+.*$$|\1: $(SPHINXBUILD)\n\t$(SPHINXSUBCMD)\n\n.PHONY: \1\n\n|' \
+		> .Makefile.d
+
+-include .Makefile.d
+
+# Get the intersphinx inventory files.
+#-------------------------------------------
+INTERSPHINX_FILES := $(shell $(ACTIVATE); python -c "import conf; print('\n'.join(n[-1][-1] for n in conf.intersphinx_mapping.values()))")
+# Python only method for downloading the inv files.
+#@URL="$(shell $(ACTIVATE); python3 -c "import conf; print([n[0] for n in conf.intersphinx_mapping.values() if n[-1][-1] == '$@'][0])")"; \
+#    $(ACTIVATE); python -c "import urllib.request; url='$${URL}objects.inv'; print('Downloading '+url+' -> $@'); urllib.request.urlretrieve(url, '$@')"
+$(INTERSPHINX_FILES): conf.py Makefile
+	@mkdir -p _build/intersphinx/
+	@rm -f $@
+	@URL="$(shell $(ACTIVATE); python3 -c "import conf; print([n[0]+'/objects.inv' for n in conf.intersphinx_mapping.values() if n[-1][-1] == '$@'][0])")"; \
+		wget "$$URL" -O "$@"
+	@du -h $@
+	@touch $@
+
+inv: $(INTERSPHINX_FILES)
+	@true
+
+.PHONY: inv
+
 
-.PHONY: help Makefile
+tools:
+	rm -rf tools
+	$(ACTIVATE); sphinx-apidoc --implicit-namespaces -o tools ../utils
 
-# 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)
+.PHONY: utils

docs/conf.py

@@ -52,13 +52,13 @@
     'sphinx.ext.todo',
     'sphinx.ext.viewcode',
     'breathe',
-    'exhale',
+#    'exhale',
     # Sphinx Contrib Packages
-    'sphinxcontrib.ansi',               # .. ansi-block::
-    'sphinxcontrib.argdoc',             # Automatic docs from argparse (maybe 'sphinxcontrib.autoprogram' instead?)
-    'sphinxcontrib.cheader',            # .. c:header:: <libfoobar.h>
-    'sphinxcontrib.cheeseshop',         # :pypi:`Sphinx`
-    'sphinxcontrib.cmakedomain',
+    #'sphinxcontrib.ansi',               # .. ansi-block::
+    #'sphinxcontrib.argdoc',             # Automatic docs from argparse (maybe 'sphinxcontrib.autoprogram' instead?)
+    #'sphinxcontrib.cheader',            # .. c:header:: <libfoobar.h> - No module named 'sphinx.util.compat'
+    #'sphinxcontrib.cheeseshop',         # :pypi:`Sphinx`
+    #'sphinxcontrib.cmakedomain',
     'sphinxcontrib.documentedlist',     # .. documentedlist::
     'sphinxcontrib.examplecode',
     'sphinxcontrib.makedomain',         # https://bitbucket.org/klorenz/sphinxcontrib-makedomain
@@ -215,13 +215,30 @@
 ]
 
 
+breathe_projects = { "verilog": "_doxyxml" }
+breathe_default_project = "verilog"
+
+# Setup the exhale extension
+exhale_args = {
+    # These arguments are required
+    "containmentFolder":     "./verilog",
+    "rootFileName":          "verilog_root.rst",
+    "rootFileTitle":         "Verilog",
+    "doxygenStripFromPath":  "..",
+    # Suggested optional arguments
+    "createTreeView":        True,
+    # TIP: if using the sphinx-bootstrap-theme, you need
+    # "treeViewIsBootstrap": True,
+    "exhaleExecutesDoxygen": False,
+    "exhaleDoxygenStdin":    "INPUT = ../include"
+}
 
 
 # Example configuration for intersphinx: refer to the Python standard library.
 intersphinx_mapping = {
-    'python' : ('https://docs.python.org/', (None, 'python-inv.txt')),
-    'vtr'    : ('http://docs.verilogtorouting.org/', (None, 'vtr-inv.txt')),
-    'prjxray' : ('http://prjxray.rtfd.io/', (None, 'vtr-inv.txt')),
+    'python' : ('https://docs.python.org/3/', (None, '_build/intersphinx/python.inv')),
+    'vtr'    : ('https://docs.verilogtorouting.org/en/latest/', (None, '_build/intersphinx/vtr.inv')),
+    'prjxray' : ('https://prjxray.readthedocs.io/en/latest/', (None, '_build/intersphinx/prjxray.inv')),
 }
 
 
@@ -234,3 +251,7 @@ def linkcode_resolve(domain, info):
         return None
     filename = info['module'].replace('.', '/')
     return "http://somesite/sourcerepo/%s.py" % filename
+
+import sys
+sys.path.append("..")
+sys.path.append("../utils")

docs/index.rst

@@ -3,13 +3,16 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-Welcome to SymbiFlow Architecture Definitions's documentation!
+Welcome to SymbiFlow Architecture Definitions documentation!
 ==============================================================
 
 .. toctree::
    :maxdepth: 2
    :caption: Contents:
 
+   tools/utils
+   tools/utils.lib
+   tools/utils/modules
 
 
 Indices and tables

docs/requirements.txt

@@ -1,29 +1,35 @@
 sphinx
 sphinx-autobuild
 
+# Important core Sphinx extensions
 sphinx_rtd_theme
 recommonmark
 breathe
-napoleon
+exhale
+sphinxcontrib-napoleon
 
-sphinxcontrib-ansi
+-e hg+https://mithro@bitbucket.org/mithro/sphinxcontrib-domaintools@mithro/use-dictitems-instead-of-dictiteritems-f-1519177628123#egg=sphinxcontrib-domaintools
+
+# Unimportant Sphinx extensions
+#sphinxcontrib-ansi
 sphinxcontrib-argdoc
-# sphinxcontrib-autoprogram
+sphinxcontrib-autoprogram
 sphinxcontrib-cheader
-sphinxcontrib-cheeseshop
-sphinxcontrib-cmakedomain
+#sphinxcontrib-cheeseshop
+#sphinxcontrib-cmakedomain
 sphinxcontrib-documentedlist
 sphinxcontrib-examplecode
+sphinxcontrib-inlinesyntaxhighlight
 sphinxcontrib-makedomain
 sphinxcontrib-manpage
 sphinxcontrib-spelling
-
+# Weirdly named Sphinx extensions
 sphinxcontrib-trio
 sphinx-git
+sphinx-autodoc-typehints
 sphinx-autodoc-napoleon-typehints
-# sphinxcontrib-inlinesyntaxhighlight
-
 
+# Sphinx extensions for support HDL stuff.
 symbolator
 sphinxcontrib-wavedrom
 # sphinxcontrib-gtkwave