docs: Add sphinx infrastructure

Signed-off-by: Alex Forencich <alex@alexforencich.com>

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.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)

docs/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=source
+set BUILDDIR=build
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

docs/requirements.txt

@@ -0,0 +1,4 @@
+sphinx
+sphinx_rtd_theme
+sphinxcontrib-email
+sphinxcontrib-svg2pdfconverter

docs/source/conf.py

@@ -0,0 +1,78 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+import datetime
+import sys
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+# import os
+# import sys
+# sys.path.insert(0, os.path.abspath('.'))
+
+
+# -- Project information -----------------------------------------------------
+
+project = 'Taxi'
+author = 'FPGA Ninja'
+copyright = f'2024-{datetime.datetime.now().year}, {author}'
+
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+    "sphinxcontrib.email",
+]
+
+# Add any paths that contain templates here, relative to this directory.
+#templates_path = ['_templates']
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = []
+
+root_doc = 'contents'
+
+numfig = True
+
+highlight_language = 'none'
+
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = 'alabaster'
+
+try:
+    import sphinx_rtd_theme
+    html_theme = 'sphinx_rtd_theme'
+except ImportError:
+    sys.stderr.write('Warning: The Sphinx \'sphinx_rtd_theme\' HTML theme was '+
+        'not found. Make sure you have the theme installed to produce pretty '+
+        'HTML output. Falling back to the default theme.\n')
+
+    html_theme = 'default'
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+#html_static_path = ['_static']
+
+
+# -- Options for LaTeX output ------------------------------------------------
+
+latex_show_pagerefs = True
+latex_show_urls = 'footnote'

docs/source/contents.rst

@@ -0,0 +1,12 @@
+.. _contents:
+
+========
+Contents
+========
+
+.. toctree::
+    :numbered:
+    :includehidden:
+
+    index
+    glossary

docs/source/glossary.rst

@@ -0,0 +1,64 @@
+.. _glossary:
+
+========
+Glossary
+========
+
+.. glossary::
+    
+    AXI
+        Advanced eXtensible Interface
+
+    BAR
+        Base Address Register
+
+    CDC
+        Clock Domain Crossing
+
+    CRC
+        Cyclic Redundancy Check
+
+    DMA
+        Direct Memory Access
+
+    FPGA
+        Field-Programmable Gate Array
+
+    I2C
+        Inter-Intergrated Circuit
+
+    JTAG
+        Joint Test Action Group
+
+    LFSR
+        Linear Feedback Shift Register
+
+    MAC
+        Media Access Control(ler)
+
+    MSI
+        Message-Signaled Interrupt
+
+    NIC
+        Network Interface Controller
+
+    PCI
+        Peripheral Component Interconnect
+
+    PCIe
+        PCI Express
+
+    PHY
+        PHYsical layer (interface)
+
+    PRBS
+        Pseudorandom Binary Sequence
+
+    PTP
+        Precision Time Protocol (IEEE 1588)
+
+    RSS
+        Receive Side Scaling
+
+    UART
+        Universal Asynchronous Receiver/Transmitter

docs/source/index.rst

@@ -0,0 +1,61 @@
+.. _intro:
+
+============
+Introduction
+============
+
+The goal of the Taxi transport library is to provide a set of performant, easy-to-use building blocks in modern System Verilog facilitating data transport and interfacing, both internally via :term:`AXI` and AXI stream, and externally via Ethernet, :term:`PCI` express, :term:`UART`, and :term:`I2C`.  The building blocks are accompanied by testbenches and simulation models utilizing `Cocotb <https://www.cocotb.org/>`_ and `Verilator <https://www.veripool.org/verilator/>`_.
+
+This library is currently under development; more components will be added over time as they are developed.
+
+The latest source code is available from the `Taxi GitHub repository <https://github.com/fpganinja/taxi>`_.
+
+License
+=======
+
+Taxi is provided by FPGA Ninja, LLC under either the `CERN Open Hardware Licence <https://cern-ohl.web.cern.ch/>`_ Version 2 - Strongly Reciprocal (CERN-OHL-S 2.0), or a paid commercial license.  Contact info@fpga.ninja for commercial use.  Note that some components may be provided under less restrictive licenses (e.g. example designs).
+
+Under the strongly-reciprocal CERN OHL, you must provide the source code of the entire digital design upon request, including all modifications, extensions, and customizations, such that the design can be rebuilt.  If this is not an acceptable restriction for your product, please contact info@fpga.ninja to inquire about a commercial license without this requirement.  License fees support the continued development and maintenance of this project and related projects.
+
+To facilitate the dual-license model, contributions to the project can only be accepted under a contributor license agreement.
+
+Example Designs
+===============
+
+Example designs are provided for several different FPGA boards, showcasing many of the capabilities of this library.  Building the example designs will require the appropriate vendor toolchain and may also require tool and IP licenses.
+
+*  Alpha Data ADM-PCIE-9V3 (Xilinx Virtex UltraScale+ XCVU3P)
+*  Dini Group DNPCIe_40G_KU_LL_2QSFP (Xilinx Kintex UltraScale XCKU040)
+*  Cisco Nexus K35-S (Xilinx Kintex UltraScale XCKU035)
+*  Cisco Nexus K3P-S (Xilinx Kintex UltraScale+ XCKU3P)
+*  Cisco Nexus K3P-Q (Xilinx Kintex UltraScale+ XCKU3P)
+*  Silicom fb2CG\@KU15P (Xilinx Kintex UltraScale+ XCKU15P)
+*  NetFPGA SUME (Xilinx Virtex 7 XC7V690T)
+*  BittWare 250-SoC (Xilinx Zynq UltraScale+ XCZU19EG)
+*  BittWare XUSP3S (Xilinx Virtex UltraScale+ XCVU095)
+*  BittWare XUP-P3R (Xilinx Virtex UltraScale+ XCVU9P)
+*  BittWare IA-420F (Intel Agilex F 014)
+*  Intel Stratix 10 MX dev kit (Intel Stratix 10 MX 2100)
+*  Intel Stratix 10 DX dev kit (Intel Stratix 10 DX 2800)
+*  Intel Agilex F dev kit (Intel Agilex F 014)
+*  Terasic DE10-Agilex (Intel Agilex F 014)
+*  Xilinx Alveo U50 (Xilinx Virtex UltraScale+ XCU50)
+*  Xilinx Alveo U55N/Varium C1100 (Xilinx Virtex UltraScale+ XCU55N)
+*  Xilinx Alveo U200 (Xilinx Virtex UltraScale+ XCU200)
+*  Xilinx Alveo U250 (Xilinx Virtex UltraScale+ XCU250)
+*  Xilinx Alveo U280 (Xilinx Virtex UltraScale+ XCU280)
+*  Xilinx Kria KR260 (Xilinx Zynq UltraScale+ XCK26)
+*  Xilinx VCU108 (Xilinx Virtex UltraScale XCVU095)
+*  Xilinx VCU118 (Xilinx Virtex UltraScale+ XCVU9P)
+*  Xilinx VCU1525 (Xilinx Virtex UltraScale+ XCVU9P)
+*  Xilinx ZCU102 (Xilinx Zynq UltraScale+ XCZU9EG)
+*  Xilinx ZCU106 (Xilinx Zynq UltraScale+ XCZU7EV)
+
+.. only:: html
+
+    Indices and tables
+    ==================
+
+    * :ref:`genindex`
+    * :ref:`modindex`
+    * :ref:`search`