Migrate documentation to Sphinx + GH pages (#50)

.github/workflows/documentation.yml

@@ -0,0 +1,26 @@
+name: documentation
+
+on: [push, pull_request, workflow_dispatch]
+
+permissions:
+  contents: write
+
+jobs:
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/checkout@v4
+      - uses: pdm-project/setup-pdm@v4
+      - run: |
+          pdm install
+          pdm document
+        working-directory: gateware
+      - name: Deploy to GitHub Pages
+        uses: peaceiris/actions-gh-pages@v4
+        if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/main' }}
+        with:
+          publish_branch: gh-pages
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: gateware/docs/_build/
+          force_orphan: true

README.md

@@ -8,183 +8,25 @@ For updates, subscribe to the [Crowd Supply page](https://www.crowdsupply.com/ap
 
 <img src="doc/img/tiliqua-front-left.jpg" width="500">
 
-## Hardware
-
-#### Audio Interface
-- 8 (4 in + 4 out) DC-coupled audio channels, 192 KHz / 24-bit sampling supported
-- Touch and proximity sensing on all 8 audio jacks (if unused)
-- PWM-controlled, user-programmable red/green LEDs on each audio channel
-- Jack insertion detection on all 8 jacks
-
-#### Motherboard
-- Switched rotary encoder with bar graph display.
-- Dual USB ports:
-    - `dbg`: Included RP2040-based JTAG debugger supported by `openFPGAloader`
-    - `usb2`: USB PHY connected directly to FPGA for high-speed USB Audio support
-- Display output for video synthesis (maximum resolution 720/60P)
-- 2x expansion ports for up to 24 simultaneous audio channels (PMOD-compatible)
-- MIDI-In jack (TRS-A standard)
-
-#### Embedded FPGA SoM (`soldiercrab`)
-
-- Lattice ECP5 (25 K) FPGA, supported by open-source FPGA toolchains
-- 128 Mbit (16 MByte) HyperRAM / oSPI RAM (for long audio buffers or video framebuffers)
-- 128 Mbit (16 MByte) SPI flash for user bitstreams
-- High-speed USB HS PHY (ULPI)
-
 ## Where do I get a Tiliqua?
 
 Tiliqua will launch on [Crowd Supply](https://www.crowdsupply.com/apfelaudio/tiliqua). Subscribing there is the best place to get production updates.
 
 <img src="doc/img/tiliqua-rear-left.jpg" width="700">
 
-# Getting Started (hardware beta R2)
-
-## Connecting
-
-Tiliqua uses an ordinary 10-pin power cable for +/- 12V ingress. You will notice however, that there are 2 such connectors on the module. *Only ONE of these should be connected*:
-
-- Use the 10-pin power ingress on the Tiliqua Motherboard, not the Audio Interface Board. Technically both will work, but only the former is fused (on beta R2 units).
-- Both connectors on the audio interface board (`eurorack-pmod`) should remain unconnected.
-
-For flashing bitstreams, usually you want to be connected to the `dbg` USB port. This is directly connected to the on-board RP2040 which is flashed with `dirtyJtag`, such that you can flash bitstreams using `openFPGALoader`.
-
-Particularly for bitstreams with touch sensing, ensure all jacks are disconnected when the tiliqua is powered on. This is because the capacitive sensing is calibrated when the system boots. In the future I'll change this to happen every time something is dis/re-connected.
-
-# Getting Started (gateware/firmware)
-
-## Prerequisites
-
-On an Ubuntu system, the following are the main dependencies:
-- The build system: install [pdm](https://github.com/pdm-project/pdm)
-- For synthesis: install [oss-cad-suite](https://github.com/YosysHQ/oss-cad-suite-build)
-- For examples that include a softcore: [rust](https://rustup.rs/).
-    - To build stripped images for RISC-V, you also need:
-        - `rustup target add riscv32imac-unknown-none-elf`
-        - `rustup component add rustfmt clippy llvm-tools`
-        - `cargo install cargo-binutils svd2rust form`
-
-To set up the environment:
-```bash
-cd gateware
-git submodule update --init --recursive
-pdm install
-```
-
-## Building example projects
-
-Each top-level bitstream has a command-line interface. You can see the options by running (for example):
-
-```bash
-# from `gateware` directory
-pdm dsp
-```
-
-The available options change depending on the top-level project. For example, many projects have video output, and from the CLI you can select the video resolution.
-
-A few examples of building top-level bitstreams:
-```bash
-# from `gateware` directory
-
-# for the selftest bitstream (prints diagnostics out DVI and serial)
-pdm selftest build
-# for a vectorscope / oscilloscope
-pdm xbeam build
-# for a polyphonic MIDI synth
-pdm polysyn build
-# for the LUNA-based 4in + 4out USB soundcard example
-# note: LUNA USB port presents itself on the second USB port (not dbg)!
-pdm usb_audio build
-# for a 4-channel waveshaping oscillator
-pdm dsp build --dsp-core nco
-# for a diffusion delay effect
-pdm dsp build --dsp-core diffuser
-# simplified vectorscope (no SoC / menu system)
-pdm vectorscope_no_soc build
-```
-
-Generally, bitstreams are also built in CI - check `.github/workflows` if you need more gruesome details on how systems are built.
-
-## Flashing example projects
-
-The built-in RP2040 JTAG debugger is based on the `dirtyJtag` project. You can flash the bitstreams above to the SRAM of the FPGA like so (add an `-f` to instead flash it to SPI flash permanently):
-
-```bash
-sudo openFPGALoader -c dirtyJtag build/top.bit
-```
-
-If you are running an SoC, it will give you serial output that you can monitor like so:
-
-```bash
-sudo picocom -b 115200 /dev/ttyACM0
-```
-
-## Simulating DSP cores
-
-The easiest way to debug the internals of a DSP project is to simulate it. This project provides some shortcuts to enable simulating designs end-to-end with Verilator (at some point these will be migrated to Amaranths CXXRTL simulation backend, once it lands).
-
-For example, to simulate the waveshaping oscillator example:
-
-```bash
-# from `gateware` directory
-pdm dsp sim --dsp-core nco
-```
-
-In short this command:
-- Elaborates your Amaranth HDL and convert it to Verilog
-- Verilates your verilog into a C++ implementation, compiling it against `sim_dsp_core.cpp` provided in `gateware/top/dsp` that excites the audio inputs (you can modify this).
-- Runs the verilated binary itself and spits out a trace you can view with `gtkwave` to see exactly what every net in the whole design is doing.
-
-## Simulating SoC cores
-
-A subset of SoC-based top-level projects also support end-to-end simulation (i.e including firmware co-simulation). For example, for the selftest SoC:
-
-```bash
-# from `gateware` directory
-pdm selftest sim
-
-# ...
-
-run verilated binary 'build/obj_dir/Vtiliqua_soc'...
-sync domain is: 60000 KHz (16 ns/cycle)
-pixel clock is: 74250 KHz (13 ns/cycle)
-[INFO] Hello from Tiliqua selftest!
-[INFO] PSRAM memtest (this will be slow if video is also active)...
-[INFO] write speed 1687 KByte/seout frame00.bmp
-c
-[INFO] read speed 1885 KByte/sec
-[INFO] PASS: PSRAM memtest
-```
-
-UART traffic from the firmware is printed to the terminal, and each video frame is emitted as a bitmap. This kind of simulation is useful for debugging the integration of top-level SoC components.
-
-## Simulating vectorscope core
-
-There is a top-level `vectorscope_no_soc` provided which is also useful for debugging integration issues between the video and memory controller cores. This can be simulated end-to-end as follows (`--trace-fst` is also useful for saving waveform traces):
-
-```bash
-# from `gateware` directory
-pdm vectorscope_no_soc sim --trace-fst
-```
-
-## Using the ILA
-
-Some cores support using a built-in ILA (integrated logic analyzer), to collect waveform traces on the hardware into on-FPGA block RAM, which is sampled at the system clock and dumped out the serial port.
+# Documentation
 
-For example:
-```bash
-# from `gateware` directory
-pdm vectorscope_no_soc build --ila --ila-port /dev/ttyACM0
-```
+(🚧 under construction) documentation is available at [apfelaudio.github.io/tiliqua](https://apfelaudio.github.io/tiliqua/)
 
-This will build the bitstream containing the ILA, flash the bitstream, then open the provided serial port waiting for an ILA dump from the Tiliqua to arrive. Once recieved, the dump will be saved to a waveform trace file.
+Documentation is built from source in `gateware/docs`.
 
-Note: you may have to play with permissions for flashing to work correctly - make sure `openFPGALoader` can run locally under your user without `sudo`.
+## Builds on the following (awesome) open projects
 
-## Builds on the following (awesome) open-hardware projects
+- The [Amaranth HDL](https://github.com/amaranth-lang/amaranth) and [Amaranth SoC](https://github.com/amaranth-lang/amaranth-soc) projects.
 - Audio interface and gateware from my existing [eurorack-pmod](https://github.com/apfelaudio/eurorack-pmod) project.
 - USB interface and gateware based on [LUNA and Cynthion](https://github.com/greatscottgadgets/luna/) projects.
 - USB Audio gateware and descriptors based on [adat-usb2-audio-interface](https://github.com/hansfbaier/adat-usb2-audio-interface).
+- Some gateware is also inherited from the [Glasgow](https://github.com/GlasgowEmbedded/glasgow) project.
 
 # License
 

gateware/docs/.gitignore

@@ -0,0 +1,2 @@
+_build/
+_linkcheck/

gateware/docs/conf.py

@@ -0,0 +1,73 @@
+import os, sys
+sys.path.insert(0, os.path.abspath("."))
+
+import time
+from importlib.metadata import version as package_version
+
+
+project = "Tiliqua Project"
+copyright = time.strftime("2024—%Y, S. Holzapfel and Tiliqua contributors")
+
+extensions = [
+    "sphinx.ext.napoleon",
+	"sphinx.ext.intersphinx",
+	"sphinx.ext.doctest",
+    "sphinx.ext.todo",
+    "sphinx.ext.autodoc",
+    "sphinx_rtd_theme",
+    "sphinxcontrib.platformpicker",
+]
+
+with open(".gitignore") as f:
+    exclude_patterns = [line.strip() for line in f.readlines()]
+
+root_doc = "cover"
+
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3", None),
+}
+
+todo_include_todos = True
+
+autodoc_member_order = "bysource"
+autodoc_default_options = {
+    "members": True
+}
+autodoc_preserve_defaults = True
+autodoc_inherit_docstrings = False
+
+# Tiliqua mostly does not include typehints, and showing them in some places but not others is
+# worse than not showing them at all.
+autodoc_typehints = "none"
+
+napoleon_google_docstring = False
+napoleon_numpy_docstring = True
+napoleon_use_ivar = True
+napoleon_include_init_with_doc = True
+napoleon_include_special_with_doc = True
+napoleon_custom_sections = [
+    ("Attributes", "params_style"), # by default displays as "Variables", which is confusing
+    ("Members", "params_style"), # `lib.wiring` signature members
+    "Platform overrides"
+]
+
+html_theme = "sphinx_rtd_theme"
+html_static_path = ["_static"]
+html_css_files = ["custom.css"]
+html_logo = "_static/logo.jpg"
+
+rst_prolog = """
+.. role:: py(code)
+   :language: python
+"""
+
+linkcheck_ignore = [
+    r"^http://127\.0\.0\.1:8000$",
+]
+
+linkcheck_anchors_ignore_for_url = [
+    r"^https://matrix\.to/",
+    r"^https://web\.libera\.chat/",
+    # React page with README content included as a JSON payload.
+    r"^https://github\.com/[^/]+/[^/]+/$",
+]

gateware/docs/cover.rst

@@ -0,0 +1,10 @@
+Tiliqua project documentation
+##############################
+
+.. toctree::
+   :maxdepth: 1
+
+   index
+   (external) GitHub <https://github.com/apfelaudio/tiliqua>
+   (external) CrowdSupply <https://www.crowdsupply.com/apfelaudio/tiliqua>
+   (external) apfelaudio.com <https://apfelaudio.com/>

gateware/docs/dsp.rst

@@ -0,0 +1,28 @@
+Tiliqua DSP Library
+###################
+
+Overview
+--------
+
+TODO short overview of the DSP library philosophy.
+
+TODO link to Amaranth documentation on streams.
+
+Stream helpers
+--------------
+
+.. autoclass:: tiliqua.dsp.Split
+
+.. autoclass:: tiliqua.dsp.Merge
+
+VCAs
+----
+
+.. autoclass:: tiliqua.dsp.VCA
+
+.. autoclass:: tiliqua.dsp.GainVCA
+
+Delay Lines
+-----------
+
+.. autoclass:: tiliqua.delay_line.DelayLine