diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml deleted file mode 100644 index 25be91a1..00000000 --- a/.github/workflows/docs.yml +++ /dev/null @@ -1,57 +0,0 @@ -name: Documentation - -on: - schedule: - # run at 5am every day - - cron: '0 5 * * *' - push: - paths: - - '.github/workflows/docs.yml' - - 'settings.json' - - 'doc/exclude_patterns.inc' - - '**/doc/**' - pull_request: - paths: - - '.github/workflows/docs.yml' - - 'settings.json' - - 'doc/exclude-patterns.inc' - - '**/doc/**' - - # Allow manually triggering the workflow. - workflow_dispatch: {} - -env: - XCORE_DOC_BUILDER: 'ghcr.io/xmos/doc_builder:v3.0.0' - -jobs: - build_documentation: - name: Build and package documentation - if: github.repository_owner == 'xmos' - runs-on: ubuntu-latest - steps: - - name: Checkout this repo - uses: actions/checkout@v3 - - - uses: actions/setup-python@v4 - with: - python-version: '3.10.x' - - - name: Pull doc_builder container - run: | - docker pull ${XCORE_DOC_BUILDER} - - - name: Build documentation - run: | - pwd - docker run --user "$(id -u):$(id -g)" --rm -v ${{ github.workspace }}:/build -e EXCLUDE_PATTERNS="/build/doc/exclude-patterns.inc" -e OUTPUT_DIR="/build/doc/_build" -e PDF=1 -e SKIP_LINK=1 -e DOXYGEN_INCLUDE=/build/doc/Doxyfile.inc -e DOXYGEN_INPUT=ignore ${XCORE_DOC_BUILDER} - tree - DOC_VERSION=$(grep version settings.json | grep -o "[0-9]*\.[0-9]*\.[0-9]") - mv doc/_build/pdf/programming_guide.pdf doc/_build/pdf/programming_guide_v${DOC_VERSION}.pdf - - - name: Save documentation artifacts - uses: actions/upload-artifact@v3 - with: - name: docs lib_src - path: doc/_build - if-no-files-found: error # 'warn' or 'ignore' are also available, defaults to `warn` - retention-days: 30 diff --git a/Jenkinsfile b/Jenkinsfile index e501e57e..bb71a1e3 100644 --- a/Jenkinsfile +++ b/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() - } + } } diff --git a/doc/exclude-patterns.inc b/doc/exclude_patterns.inc similarity index 78% rename from doc/exclude-patterns.inc rename to doc/exclude_patterns.inc index e568e88a..934f156d 100644 --- a/doc/exclude-patterns.inc +++ b/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 \ No newline at end of file +**/resource_usage_ssrc.rst diff --git a/doc/rst/programming_guide/fixed_ratio_src.rst b/doc/programming_guide/fixed_ratio_src.rst similarity index 99% rename from doc/rst/programming_guide/fixed_ratio_src.rst rename to doc/programming_guide/fixed_ratio_src.rst index 26e9afea..9e8d62f0 100644 --- a/doc/rst/programming_guide/fixed_ratio_src.rst +++ b/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 --------------------- diff --git a/doc/rst/programming_guide/images/asrc_fft_176_48.pdf b/doc/programming_guide/images/asrc_fft_176_48.pdf similarity index 100% rename from doc/rst/programming_guide/images/asrc_fft_176_48.pdf rename to doc/programming_guide/images/asrc_fft_176_48.pdf diff --git a/doc/rst/programming_guide/images/asrc_fft_44_192.pdf b/doc/programming_guide/images/asrc_fft_44_192.pdf similarity index 100% rename from doc/rst/programming_guide/images/asrc_fft_44_192.pdf rename to doc/programming_guide/images/asrc_fft_44_192.pdf diff --git a/doc/rst/programming_guide/images/asrc_fft_96_88.pdf b/doc/programming_guide/images/asrc_fft_96_88.pdf similarity index 100% rename from doc/rst/programming_guide/images/asrc_fft_96_88.pdf rename to doc/programming_guide/images/asrc_fft_96_88.pdf diff --git a/doc/rst/programming_guide/images/asrc_structure.pdf b/doc/programming_guide/images/asrc_structure.pdf similarity index 100% rename from doc/rst/programming_guide/images/asrc_structure.pdf rename to doc/programming_guide/images/asrc_structure.pdf diff --git a/doc/rst/programming_guide/images/quad_dual_instance.pdf b/doc/programming_guide/images/quad_dual_instance.pdf similarity index 100% rename from doc/rst/programming_guide/images/quad_dual_instance.pdf rename to doc/programming_guide/images/quad_dual_instance.pdf diff --git a/doc/rst/programming_guide/images/src_ff3_vpu.png b/doc/programming_guide/images/src_ff3_vpu.png similarity index 100% rename from doc/rst/programming_guide/images/src_ff3_vpu.png rename to doc/programming_guide/images/src_ff3_vpu.png diff --git a/doc/rst/programming_guide/images/src_ff3_vpu_pb.png b/doc/programming_guide/images/src_ff3_vpu_pb.png similarity index 100% rename from doc/rst/programming_guide/images/src_ff3_vpu_pb.png rename to doc/programming_guide/images/src_ff3_vpu_pb.png diff --git a/doc/rst/programming_guide/images/src_proc.pdf b/doc/programming_guide/images/src_proc.pdf similarity index 100% rename from doc/rst/programming_guide/images/src_proc.pdf rename to doc/programming_guide/images/src_proc.pdf diff --git a/doc/rst/programming_guide/images/src_rat_vpu.png b/doc/programming_guide/images/src_rat_vpu.png similarity index 100% rename from doc/rst/programming_guide/images/src_rat_vpu.png rename to doc/programming_guide/images/src_rat_vpu.png diff --git a/doc/rst/programming_guide/images/src_rat_vpu_pb.png b/doc/programming_guide/images/src_rat_vpu_pb.png similarity index 100% rename from doc/rst/programming_guide/images/src_rat_vpu_pb.png rename to doc/programming_guide/images/src_rat_vpu_pb.png diff --git a/doc/rst/programming_guide/images/ssrc_fft_176_48.pdf b/doc/programming_guide/images/ssrc_fft_176_48.pdf similarity index 100% rename from doc/rst/programming_guide/images/ssrc_fft_176_48.pdf rename to doc/programming_guide/images/ssrc_fft_176_48.pdf diff --git a/doc/rst/programming_guide/images/ssrc_fft_44_192.pdf b/doc/programming_guide/images/ssrc_fft_44_192.pdf similarity index 100% rename from doc/rst/programming_guide/images/ssrc_fft_44_192.pdf rename to doc/programming_guide/images/ssrc_fft_44_192.pdf diff --git a/doc/rst/programming_guide/images/ssrc_fft_96_88.pdf b/doc/programming_guide/images/ssrc_fft_96_88.pdf similarity index 100% rename from doc/rst/programming_guide/images/ssrc_fft_96_88.pdf rename to doc/programming_guide/images/ssrc_fft_96_88.pdf diff --git a/doc/rst/programming_guide/images/ssrc_structure.pdf b/doc/programming_guide/images/ssrc_structure.pdf similarity index 100% rename from doc/rst/programming_guide/images/ssrc_structure.pdf rename to doc/programming_guide/images/ssrc_structure.pdf diff --git a/doc/rst/programming_guide/images/stereo_dual_instance.pdf b/doc/programming_guide/images/stereo_dual_instance.pdf similarity index 100% rename from doc/rst/programming_guide/images/stereo_dual_instance.pdf rename to doc/programming_guide/images/stereo_dual_instance.pdf diff --git a/doc/rst/programming_guide/images/stereo_single_instance.pdf b/doc/programming_guide/images/stereo_single_instance.pdf similarity index 100% rename from doc/rst/programming_guide/images/stereo_single_instance.pdf rename to doc/programming_guide/images/stereo_single_instance.pdf diff --git a/doc/programming_guide/index.rst b/doc/programming_guide/index.rst new file mode 100644 index 00000000..0e8c0b41 --- /dev/null +++ b/doc/programming_guide/index.rst @@ -0,0 +1,9 @@ +Programming Guide +################# + +.. toctree:: + + ../../README + multi_rate_hifi_src + fixed_ratio_src + ../../CHANGELOG diff --git a/doc/rst/programming_guide/multi_rate_hifi_src.rst b/doc/programming_guide/multi_rate_hifi_src.rst similarity index 99% rename from doc/rst/programming_guide/multi_rate_hifi_src.rst rename to doc/programming_guide/multi_rate_hifi_src.rst index 0a7cc6da..17d12ce0 100644 --- a/doc/rst/programming_guide/multi_rate_hifi_src.rst +++ b/doc/programming_guide/multi_rate_hifi_src.rst @@ -46,11 +46,11 @@ There is an initialization call which sets up the variables within the structure Initialization ensures the correct selection, ordering and configuration of the filtering stages, be they decimators, interpolators or pass-through blocks. This initialization call contains arguments defining selected input and output nominal sample rates as well as settings for the sample rate converter: -.. doxygenfunction:: ssrc_init +:c:func:`ssrc_init` The initialization call is the same for ASRC: -.. doxygenfunction:: asrc_init +:c:func:`asrc_init` The input block size must be a power of 2 and is set by the ``n_in_samples`` argument. In the case where more than one channel is to be processed per SRC instance, the total number of input samples expected for each processing call is ``n_in_samples * n_channels_per_instance``. @@ -75,11 +75,11 @@ The logic is designed so that the final filtering stage always receives a sample The processing function call is passed the input and output buffers and a reference to the control structure: -.. doxygenfunction:: ssrc_process +:c:func:`ssrc_process` In the case of ASRC a fractional frequency ratio argument is also supplied: -.. doxygenfunction:: asrc_process +:c:func:`asrc_process` The SRC processing call always returns a whole number of output samples produced by the sample rate conversion. Depending on the sample ratios selected, this number may be between zero and ``(n_in_samples * n_channels_per_instance * SRC_N_OUT_IN_RATIO_MAX)``. ``SRC_N_OUT_IN_RATIO_MAX`` is the maximum number of output samples for a single input sample. For example, if the input frequency is 44.1 kHz and the output rate is 192 kHz then a sample rate conversion of one sample input may produce up to 5 output samples. @@ -477,4 +477,4 @@ ASRC API -------- .. doxygengroup:: src_asrc - :content-only: \ No newline at end of file + :content-only: diff --git a/doc/rst/programming_guide/resource_usage_asrc.rst b/doc/programming_guide/resource_usage_asrc.rst similarity index 100% rename from doc/rst/programming_guide/resource_usage_asrc.rst rename to doc/programming_guide/resource_usage_asrc.rst diff --git a/doc/rst/programming_guide/resource_usage_ssrc.rst b/doc/programming_guide/resource_usage_ssrc.rst similarity index 100% rename from doc/rst/programming_guide/resource_usage_ssrc.rst rename to doc/programming_guide/resource_usage_ssrc.rst diff --git a/doc/rst/programming_guide/index.rst b/doc/rst/programming_guide/index.rst deleted file mode 100644 index 9453a906..00000000 --- a/doc/rst/programming_guide/index.rst +++ /dev/null @@ -1,10 +0,0 @@ -Programming Guide -################# - -.. include:: ../../../README.rst - -.. include:: ./multi_rate_hifi_src.rst - -.. include:: ./fixed_ratio_src.rst - -.. include:: ../../../CHANGELOG.rst diff --git a/doc/rst/version.rst b/doc/rst/version.rst deleted file mode 100644 index 4bd66311..00000000 --- a/doc/rst/version.rst +++ /dev/null @@ -1 +0,0 @@ -.. version:: 2.4.0 diff --git a/doc/src_html/custom.css b/doc/src_html/custom.css deleted file mode 100644 index 8bca20fb..00000000 --- a/doc/src_html/custom.css +++ /dev/null @@ -1,27 +0,0 @@ -/* no longer needed */ -/* This rule allows scrolling the navigation menu on mobile -@media (max-width: 67em) { - .sidebar-drawer { - overflow-y: scroll; - } -} */ - -/* no longer needed */ -/* this helps with the sticky sidebar scrolling focus issues -.sidebar-sticky, .toc-sticky { - height: auto; -} */ - - -h1, h2, h3, h4, h5, h6{ - font-weight: 300; -} - -table.docutils td p{ - font-size: x-small -} - -table.docutils th p{ - font-size: small; - font-weight: 300; -} \ No newline at end of file diff --git a/index.rst b/index.rst index e94f82ba..6d3b4a84 100644 --- a/index.rst +++ b/index.rst @@ -1,10 +1,10 @@ ###################### -SAMPLE RATE CONVERSION +SAMPLE RATE CONVERSION ###################### .. toctree:: :maxdepth: 5 - ./doc/rst/programming_guide/index.rst - ./doc/python/_build/rst/allPlots.rst \ No newline at end of file + ./doc/programming_guide/index.rst + ./doc/python/_build/rst/allPlots.rst diff --git a/settings.json b/settings.json deleted file mode 100644 index 78f34bed..00000000 --- a/settings.json +++ /dev/null @@ -1,5 +0,0 @@ -{ - "title": "SAMPLE RATE CONVERSION", - "project": "lib_src documentation", - "version": "2.4.0" -} diff --git a/settings.yml b/settings.yml new file mode 100644 index 00000000..1d30cf5f --- /dev/null +++ b/settings.yml @@ -0,0 +1,14 @@ +--- +project: lib_src +title: SAMPLE RATE CONVERSION +version: 2.4.0 + +documentation: + exclude_patterns_path: doc/exclude_patterns.inc + doxygen_projects: + lib_xcore_math: + doxyfile_path: doc/Doxyfile.inc + pdfs: + doc/programming_guide/index: + pdf_title: "{{title}} - Programming Guide" + pdf_filename: "{{project}}_programming_guide_v{{version}}" diff --git a/tests/test_lib_checks.py b/tests/test_lib_checks.py index 02413ad1..07787342 100644 --- a/tests/test_lib_checks.py +++ b/tests/test_lib_checks.py @@ -36,9 +36,9 @@ def test_version_matches(): """ Check docs version vs changelog """ - with open(Path(__file__).resolve().parent / "../settings.json") as sj: + with open(Path(__file__).resolve().parent / "../settings.yml") as sy: with open(Path(__file__).resolve().parent / "../CHANGELOG.rst") as cl: re_string = r"([0-9]*)\.([0-9]*)\.([0-9]*)" - sj_ver = re.search(re_string, sj.readlines()[3]).groups() + sy_ver = re.search(re_string, sy.readlines()[3]).groups() cl_ver = re.search(re_string, cl.readlines()[3]).groups() - assert sj_ver == cl_ver, f"Version match issue between settings.json and CHANGELOG.rst: {sj_ver} {cl_ver}" + assert sy_ver == cl_ver, f"Version match issue between settings.yml and CHANGELOG.rst: {sy_ver} {cl_ver}"