doc: Modernize documentation, platforms, algorithms, architecture, and binary releases

.github/workflows/deploy.yml

@@ -0,0 +1,94 @@
+---
+name: Build and Deploy SOF Documentation
+
+on:
+  push:
+    branches:
+      - master
+      - main
+    tags:
+      - 'v*'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  build:
+    name: Build Documentation
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout Documentation Source
+        uses: actions/checkout@v4
+
+      - name: Set up Python 3.13
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.13'
+
+      - name: Install Base System Dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y doxygen graphviz ninja-build cmake default-jre
+
+      - name: Install Python Documentation Dependencies
+        run: |
+          pip install -r scripts/requirements.txt -c scripts/constraints.txt
+          pip install pyyaml
+
+      - name: Optional API Docs (Clone SOF & Doxygen)
+        continue-on-error: true
+        run: |
+          git clone --depth 1 https://github.com/thesofproject/sof.git _deps/sof
+          if ! grep -q "zephyr/include" _deps/sof/doc/sof.doxygen.in; then
+            echo "INPUT += @top_srcdir@/zephyr/include" >> _deps/sof/doc/sof.doxygen.in
+          fi
+          cmake -GNinja -S _deps/sof/doc -B _build_doxy
+          ninja -C _build_doxy doc
+
+      - name: Generate Dynamic Platform & Algorithm Matrices
+        run: |
+          python3 scripts/generate_matrices.py
+
+      - name: Build Sphinx Documentation
+        run: |
+          if [ -d "_build_doxy" ]; then
+            make html VERBOSE=1 SOF_DOC_BUILD=_build_doxy
+          else
+            make html VERBOSE=1
+          fi
+
+      - name: Prepare Publish Directory Structure
+        run: |
+          mkdir -p _site/latest
+          cp -r _build/html/* _site/latest/
+          # Landing redirect to /latest/
+          echo '<meta http-equiv="refresh" content="0; url=latest/">' > _site/index.html
+          echo '<a href="latest/">Redirecting to latest SOF documentation...</a>' >> _site/index.html
+          touch _site/.nojekyll
+
+      - name: Upload Pages Artifact
+        if: github.ref == 'refs/heads/master' || github.ref == 'refs/heads/main' || startsWith(github.ref, 'refs/tags/v')
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: _site
+
+  deploy:
+    name: Deploy to GitHub Pages
+    needs: build
+    if: github.ref == 'refs/heads/master' || github.ref == 'refs/heads/main' || startsWith(github.ref, 'refs/tags/v')
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.github/workflows/pull-request.yml

@@ -64,7 +64,7 @@ jobs:
 
       - name: configure and build SOF API docs (Doxygen)
         run: |
-          git clone https://github.com/thesofproject/sof
+          git clone --depth 1 https://github.com/thesofproject/sof
           if ! grep -q "zephyr/include" sof/doc/sof.doxygen.in; then
             echo "INPUT += @top_srcdir@/zephyr/include" \
               >> sof/doc/sof.doxygen.in
@@ -156,7 +156,7 @@ jobs:
 
       - name: configure and build SOF API docs (Doxygen)
         run: |
-          git clone https://github.com/thesofproject/sof
+          git clone --depth 1 https://github.com/thesofproject/sof
           if ! grep -q "zephyr/include" sof/doc/sof.doxygen.in; then
             echo "INPUT += @top_srcdir@/zephyr/include" \
               >> sof/doc/sof.doxygen.in

.github/workflows/woke_pr.yml

@@ -16,6 +16,11 @@ on:
     branches:
       - master
 
+permissions:
+  contents: read
+  pull-requests: write
+  checks: write
+
 jobs:
   woke_pr:
     name: woke check for patch
@@ -27,7 +32,7 @@ jobs:
           github-token: ${{ secrets.GITHUB_TOKEN }}
           # Change reviewdog reporter if you need
           # [github-pr-check,github-check,github-pr-review].
-          reporter: github-pr-review
+          reporter: github-pr-check
           # Change reporter level if you need.
           # GitHub Status Check won't become failure with warning.
           level: warning

.gitignore

@@ -6,3 +6,4 @@ _build
 *.warnings
 .tox
 MANIFEST
+_generated_*.rst

.wokeignore

@@ -1,6 +1,7 @@
 # The following files can be ignored when running Woke.
 
 rules-woke.yaml
+.wokeignore
 conf.py
 *.pu
 tox.ini
@@ -12,7 +13,13 @@ release.rst
 introduction/index.rst
 maintainers/merge_rights.rst
 contribute/process/bug-tracking.rst
+contribute/process/images/*
 getting_started/setup/setup_up_2_board.rst
+developer_guides/setup_special_device/setup_up_2_board.rst
+developer_guides/virtualization/virtualization.rst
+developer_guides/firmware/component-tutorial/tut-ii-topology.rst
+developer_guides/subsystem_architecture/host/linux_driver/architecture/sof_driver_arch.rst
+developer_guides/tech/compile_wsl.rst
 developer_guides/virtualization/files/q-v6.sh
 developer_guides/topology/topology.rst
 developer_guides/fuzzing/testbench_afl_fuzzing.rst

Makefile

@@ -51,7 +51,12 @@ else
 	# by disabling UML diagrams in the conf.py file.
 endif
 
-html: apidocs
+PYTHON ?= python3
+
+generate_data:
+	$(PYTHON) scripts/generate_matrices.py
+
+html: generate_data apidocs
 	$(SPHINXBUILD) -j auto -t $(DOC_TAG) -b html               \
 -d $(BUILDDIR)/doctrees $(SOURCEDIR) $(BUILDDIR)/html $(SPHINXOPTS)    \
 -D breathe_projects.'SOF Project'="${SOF_DOC_BUILD}"/doxygen/xml \

algos/index.rst

@@ -10,34 +10,8 @@ SOF contains several permissively-licensed and royalty-free audio processing
 algorithms that can be used alongside proprietary processing components to
 build pipelines.
 
-.. csv-table:: Supplied Audio Processing Algorithms
-   :header: "Processing", "Description", "Generic C", "SIMD Support", "Status", "Milestone"
-   :widths: 10, 30, 10, 10, 10, 10
+.. include:: _generated_modules_table.rst
 
-   "Acoustical Echo Cancellation (mockup)", "Attenuates speaker originated acoustical coupling in microphone capture signal", "Yes", "N/A", "Planned", "1.6"
-   "Asynchronous sample rate conversion", "Converts between common sample rates and connects pipelines with different clock domains", "Yes", "Xtensa HiFi3", "Upstream", "1.5"
-   "Channel selector", "Copies the selected channel from the source buffer to the sink buffer", "Yes", "N/A", "Upstream", "1.4"
-   "Crossover", "Splits up audio into at most four different bands for individual processing", "Yes", "(Possible via IIR)", "Upstream", "1.5"
-   "DCBlocker", "Simple highpass filter to remove DC components from audio", "Yes", "N/A", "Upstream", "1.4"
-   "Demultiplexer", "Copies PCM sample frames from one source buffer to multiple sink buffers with configurable channels", "Yes", "N/A", "Upstream", "1.4"
-   "Dynamic Range Processor", "Compresses and expands an audio signal to bring out quiet sounds and dampening loud sounds", "Yes", "Yes", "In Progress", "1.7 (expected)"
-   "FIR equalizer", "Enhances frequency response with a finite impulse response filter, e.g. improve speaker sound", "Yes", "Xtensa HiFi3", "Upstream", "1.4"
-   "IIR equalizer", "Enhances frequency response with an infinite impulse response filter, e.g. cancel DC component or improve speaker sound", "Yes", "Xtensa HiFi3", "Upstream", "1.4"
-   "Mixer", "Sums with unity gain and saturation source buffers of multiple pipelines to a single output sink buffer", "Yes", "No", "Upstream", "1.0"
-   "Multi-microphone beamformer", "Enhances directivity of microphone array towards steer direction and attenuates diffuse noise", "Yes", "Yes", "Upstream", "1.6"
-   "PCM converter", "Not a dedicated component but provides for DAI and host components conversion between PCM formats e.g. S16_LE, S24_LE, and S32_LE", "Yes", "Xtensa HiFi3", "Upstream", "1.5"
-   "Sample rate conversion", "Converts between common sample rates to connect multi-rate synchronous pipelines", "Yes", "Xtensa HiFi3", "Upstream", "1.3"
-   "Volume", "Provides real-time stream gain controls to the user", "Yes", "Xtensa HiFi3", "Upstream", "1.0"
+.. note::
 
-Algorithm Specific Information
-******************************
-
-Further information on specific algorithms is forthcoming.
-
-.. toctree::
-   :maxdepth: 1
-
-   demux/demux.rst
-   eq/equalizers_tuning
-   src/sample_rate_conversion
-   tdfb/time_domain_fixed_beamformer
+   For detailed algorithm implementation guides, filter tuning workflows, and design tools, consult the :ref:`algorithm-specific-information` section in Developer Guides.