Use doc builder v4

Jenkinsfile

@@ -17,17 +17,17 @@ def localRunPytest(String extra_args="") {
 getApproval()
 
 pipeline {
-  agent {
-    label 'x86_64&&macOS' // These agents have 24 cores so good for parallel xsim runs
-  }
+  agent none
   environment {
     REPO = 'lib_src'
     VIEW = getViewName(REPO)
     PYTHON_VERSION = "3.10.5"
     VENV_DIRNAME = ".venv"
+    XMOSDOC_VERSION = "pr-67"
   }
   options {
     skipDefaultCheckout()
+    timestamps()
   }
   parameters {
     string(
@@ -37,135 +37,150 @@ pipeline {
     )
   }
   stages {
-    stage('Get repo') {
-      steps {
-        sh "mkdir ${REPO}"
-        // source checks require the directory
-        // name to be the same as the repo name
-        dir("${REPO}") {
-          // checkout repo
-          checkout scm
-          sh 'git submodule update --init --recursive --depth 1'
-        }
+    stage('Build and Test') {
+      when {
+        expression { !env.GH_LABEL_DOC_ONLY.toBoolean() }
       }
-    }
-    stage ("Create Python environment")
-    {
-      steps {
-        dir("${REPO}") {
-          createVenv('requirements.txt')
-          withVenv {
-            sh 'pip install -r requirements.txt'
+      agent {
+        label 'x86_64&&docker' // These agents have 24 cores so good for parallel xsim runs
+      }
+      stages {
+        stage('Get repo') {
+          steps {
+            sh "mkdir ${REPO}"
+            // source checks require the directory
+            // name to be the same as the repo name
+            dir("${REPO}") {
+              // checkout repo
+              checkout scm
+              sh 'git submodule update --init --recursive --depth 1'
+            }
           }
         }
-      }
-    }
-    stage('Library checks') {
-      steps {
-        dir("${REPO}") {
-          sh 'git clone git@github.com:xmos/infr_apps.git'
-          sh 'git clone git@github.com:xmos/infr_scripts_py.git'
-          // These are needed for xmake legacy build and also changelog check
-          sh 'git clone git@github.com:xmos/lib_logging.git'
-          sh 'git clone git@github.com:xmos/lib_xassert.git'
-          withVenv {
-            sh 'pip install -e infr_scripts_py'
-            sh 'pip install -e infr_apps'
-            dir("tests") {
-              withEnv(["XMOS_ROOT=.."]) {
-                localRunPytest('-s test_lib_checks.py -vv')
+        stage ("Create Python environment") {
+          steps {
+            dir("${REPO}") {
+              createVenv('requirements.txt')
+              withVenv {
+                sh 'pip install -r requirements.txt'
               }
             }
           }
         }
-      }
-    }
-    stage('Test xmake build') {
-      steps {
-        runningOn(env.NODE_NAME)
-        dir("${REPO}") {
-          withTools(params.TOOLS_VERSION) {
-            withVenv {
-              dir("tests") {
-                localRunPytest('-k "legacy" -vv')
+        stage('Library checks') {
+          steps {
+            dir("${REPO}") {
+              sh 'git clone git@github.com:xmos/infr_apps.git'
+              sh 'git clone git@github.com:xmos/infr_scripts_py.git'
+              // These are needed for xmake legacy build and also changelog check
+              sh 'git clone git@github.com:xmos/lib_logging.git'
+              sh 'git clone git@github.com:xmos/lib_xassert.git'
+              withVenv {
+                sh 'pip install -e infr_scripts_py'
+                sh 'pip install -e infr_apps'
+                dir("tests") {
+                  withEnv(["XMOS_ROOT=.."]) {
+                    localRunPytest('-s test_lib_checks.py -vv')
+                  }
+                }
               }
             }
           }
         }
-      }
-    }
-    stage('Run doc python') {
-      steps {
-        runningOn(env.NODE_NAME)
-        dir("${REPO}") {
-          withTools(params.TOOLS_VERSION) {
-            withVenv {
-              dir("doc/python") {
-                sh "python -m doc_asrc.py"
-                sh "zip -r snr_build.zip _build"
-                archiveArtifacts artifacts: "snr_build.zip"
+        stage('Test xmake build') {
+          steps {
+            runningOn(env.NODE_NAME)
+            dir("${REPO}") {
+              withTools(params.TOOLS_VERSION) {
+                withVenv {
+                  dir("tests") {
+                    localRunPytest('-k "legacy" -vv')
+                  }
+                }
               }
             }
           }
         }
-      }
-    }
-    stage('Tests XS2') {
-      steps {
-        runningOn(env.NODE_NAME)
-        dir("${REPO}") {
-          withTools(params.TOOLS_VERSION) {
-            withVenv {
-              sh 'mkdir -p build'
-              dir("build") {
-                sh 'rm CMakeCache.txt'
-                sh 'cmake --toolchain ../xmos_cmake_toolchain/xs2a.cmake ..'
-                sh 'make test_ds3_voice test_us3_voice test_unity_gain_voice -j'
-              }
-              dir("tests") {
-                localRunPytest('-n auto -k "xs2" -vv')
+        stage('Run doc python') {
+          steps {
+            runningOn(env.NODE_NAME)
+            dir("${REPO}") {
+              withTools(params.TOOLS_VERSION) {
+                withVenv {
+                  dir("doc/python") {
+                    sh "python -m doc_asrc.py"
+                  }
+                  sh "docker pull ghcr.io/xmos/doc_builder:$XMOSDOC_VERSION"
+                  sh """docker run -u "\$(id -u):\$(id -g)" \
+                        --rm \
+                        -v ${WORKSPACE}/${REPO}:/build \
+                        ghcr.io/xmos/doc_builder:$XMOSDOC_VERSION -v"""
+                  sh "zip -r doc_build.zip doc/_build"
+                  archiveArtifacts artifacts: "doc_build.zip", allowEmptyArchive: true
+                }
               }
-              dir("build") {
-                sh 'rm CMakeCache.txt' // Cleanup XS2 cmake cache for next stage
+            }
+          }
+        }
+        stage('Tests XS2') {
+          steps {
+            runningOn(env.NODE_NAME)
+            dir("${REPO}") {
+              withTools(params.TOOLS_VERSION) {
+                withVenv {
+                  sh 'mkdir -p build'
+                  dir("build") {
+                    sh 'rm CMakeCache.txt'
+                    sh 'cmake --toolchain ../xmos_cmake_toolchain/xs2a.cmake ..'
+                    sh 'make test_ds3_voice test_us3_voice test_unity_gain_voice -j'
+                  }
+                  dir("tests") {
+                    localRunPytest('-n auto -k "xs2" -vv')
+                  }
+                  dir("build") {
+                    sh 'rm CMakeCache.txt' // Cleanup XS2 cmake cache for next stage
+                  }
+                }
               }
             }
           }
         }
-      }
-    }
-    stage('Tests XS3') {
-      steps {
-        runningOn(env.NODE_NAME)
-        dir("${REPO}") {
-          withTools(params.TOOLS_VERSION) {
-            withVenv {
-              dir("tests") {
-                localRunPytest('-m prepare') // Do all pre work like building and generating golden ref where needed
+        stage('Tests XS3') {
+          steps {
+            runningOn(env.NODE_NAME)
+            dir("${REPO}") {
+              withTools(params.TOOLS_VERSION) {
+                withVenv {
+                  dir("tests") {
+                    localRunPytest('-m prepare') // Do all pre work like building and generating golden ref where needed
 
-                // FF3 HiFi tests for OS3 and DS3
-                localRunPytest('-m main -n auto -k "hifi_ff3" -vv')
+                    // FF3 HiFi tests for OS3 and DS3
+                    localRunPytest('-m main -n auto -k "hifi_ff3" -vv')
 
-                // ASRC and SSRC tests across all in/out freqs and deviations (asrc only)
-                localRunPytest('-m main -n auto -k "mrhf" -vv')
-                archiveArtifacts artifacts: "mips_report*.csv", allowEmptyArchive: true
+                    // ASRC and SSRC tests across all in/out freqs and deviations (asrc only)
+                    localRunPytest('-m main -n auto -k "mrhf" -vv')
+                    archiveArtifacts artifacts: "mips_report*.csv", allowEmptyArchive: true
 
-                // VPU enabled ff3 and rat tests
-                localRunPytest('-m main -k "vpu" -vv') // xdist not working yet so no -n auto
+                    // VPU enabled ff3 and rat tests
+                    localRunPytest('-m main -k "vpu" -vv') // xdist not working yet so no -n auto
 
-                // Profile the ASRC
-                localRunPytest('-m main -k "profile_asrc" -vv')
-                sh 'tree'
-                archiveArtifacts artifacts: "gprof_results/*.png", allowEmptyArchive: true
+                    // Profile the ASRC
+                    localRunPytest('-m main -k "profile_asrc" -vv')
+                    sh 'tree'
+                    archiveArtifacts artifacts: "gprof_results/*.png", allowEmptyArchive: true
+                  }
+                }
               }
             }
           }
         }
       }
+      post {
+        cleanup {
+          xcoreCleanSandbox()
+        }
+      }
     }
-  }
-  post {
-    cleanup {
-      xcoreCleanSandbox()
-    }
+
   }
 }

doc/exclude-patterns.inc → doc/exclude_patterns.inc

@@ -1,14 +1,15 @@
 # The following patterns are to be excluded from the documentation build
 tests/*
 build/*
+**LICENSE*
 
 # Do not build .md files
 
 *.md
 **/*.md
+lib_logging/**
+lib_xassert/**
 
 # We need to ensure these are not processed twice which breaks figure numbering. They are included via index.rst.
-**/multi_rate_hifi_src.rst
-**/fixed_ratio_src.rst
 **/resource_usage_asrc.rst
-**/resource_usage_ssrc.rst
+**/resource_usage_ssrc.rst

doc/rst/programming_guide/fixed_ratio_src.rst → doc/programming_guide/fixed_ratio_src.rst

@@ -121,7 +121,9 @@ They have been designed for voice applications and, in particular, conformance t
 .. note::
     These filters will only run on XCORE-AI due to the inner dot product calculation employing the XS3 VPU.
 
+
 .. _ff3_voice_vpu_hdr:
+
 Fixed factor of 3 VPU
 ---------------------
 

doc/programming_guide/index.rst

@@ -0,0 +1,9 @@
+Programming Guide
+#################
+
+.. toctree::
+
+   ../../README
+   multi_rate_hifi_src
+   fixed_ratio_src
+   ../../CHANGELOG