Skip to content

Commit

Permalink
Merge pull request #203 from BrennanGit/feature/doc_builder_v4
Browse files Browse the repository at this point in the history 
fixes for xmosdoc v4
  • Loading branch information
@BrennanGit
BrennanGit authored Oct 20, 2023
2 parents 6655c03 + abf837a commit cb9c336
Show file tree
Hide file tree
Showing 34 changed files with 200 additions and 188 deletions.
44 changes: 0 additions & 44 deletions .github/workflows/docs.yml
View file

This file was deleted.

236 changes: 134 additions & 102 deletions Jenkinsfile
View file
Original file line number Diff line number Diff line change
@@ -1,11 +1,9 @@
@Library('xmos_jenkins_shared_library@v0.20.0') _
@Library('xmos_jenkins_shared_library@v0.27.0') _

getApproval()

pipeline {
agent {
label 'xcore.ai-explorer-us'
}
agent none
options {
disableConcurrentBuilds()
skipDefaultCheckout()
Expand All @@ -32,117 +30,151 @@ pipeline {
LOCAL_WIFI_PASS = credentials('hampton-office-network-wifi-password')
}
stages {
stage('Checkout') {
steps {
checkout scm
sh 'git submodule update --init --recursive --depth 1 --jobs \$(nproc)'
}
}
stage('Build tests and host apps') {
steps {
script {
uid = sh(returnStdout: true, script: 'id -u').trim()
gid = sh(returnStdout: true, script: 'id -g').trim()
}
// pull docker
sh "docker pull ghcr.io/xmos/xcore_voice_tester:develop"
withTools(params.TOOLS_VERSION) {
sh "bash tools/ci/build_rtos_tests.sh"
sh "bash tools/ci/build_host_apps.sh"
}
// List built files for log
sh "ls -la dist/"
sh "ls -la dist_host/"
}
}
stage('Create virtual environment') {
steps {
// Create venv
sh "pyenv install -s $PYTHON_VERSION"
sh "~/.pyenv/versions/$PYTHON_VERSION/bin/python -m venv $VENV_DIRNAME"
// Install dependencies
withVenv() {
sh "pip install git+https://github0.xmos.com/xmos-int/xtagctl.git"
sh "pip install -r test/requirements.txt"
}
}
}
stage('Cleanup xtagctl') {
steps {
// Cleanup any xtagctl cruft from previous failed runs
withTools(params.TOOLS_VERSION) {
withVenv {
sh "xtagctl reset_all $RTOS_TEST_RIG_TARGET"
stage('Build and Docs') {
parallel {
stage('Build Docs') {
agent { label "docker" }
environment { XMOSDOC_VERSION = "v4.0" }
steps {
checkout scm
sh 'git submodule update --init --recursive --depth 1'
sh "docker pull ghcr.io/xmos/xmosdoc:$XMOSDOC_VERSION"
sh """docker run -u "\$(id -u):\$(id -g)" \
--rm \
-v ${WORKSPACE}:/build \
ghcr.io/xmos/xmosdoc:$XMOSDOC_VERSION -v"""
archiveArtifacts artifacts: "doc/_build/**", allowEmptyArchive: true
}
}
sh "rm -f ~/.xtag/status.lock ~/.xtag/acquired"
}
}
stage('Run RTOS Drivers WiFi test') {
steps {
withTools(params.TOOLS_VERSION) {
withVenv {
script {
withXTAG(["$RTOS_TEST_RIG_TARGET"]) { adapterIDs ->
sh "test/rtos_drivers/wifi/check_wifi.sh " + adapterIDs[0]
}
sh "pytest test/rtos_drivers/wifi"
post {
cleanup {
xcoreCleanSandbox()
}
}
}
}
}
stage('Run RTOS Drivers HIL test') {
steps {
withTools(params.TOOLS_VERSION) {
withVenv {
script {
withXTAG(["$RTOS_TEST_RIG_TARGET"]) { adapterIDs ->
sh "test/rtos_drivers/hil/check_drivers_hil.sh " + adapterIDs[0]

stage('Build and Test') {
when {
expression { !env.GH_LABEL_DOC_ONLY.toBoolean() }
}
agent {
label 'xcore.ai-explorer-us'
}
stages {
stage('Checkout') {
steps {
checkout scm
sh 'git submodule update --init --recursive --depth 1 --jobs \$(nproc)'
}
sh "pytest test/rtos_drivers/hil"
}
}
}
}
}
stage('Run RTOS Drivers HIL_Add test') {
steps {
withTools(params.TOOLS_VERSION) {
withVenv {
script {
withXTAG(["$RTOS_TEST_RIG_TARGET"]) { adapterIDs ->
sh "test/rtos_drivers/hil_add/check_drivers_hil_add.sh " + adapterIDs[0]
stage('Build tests and host apps') {
steps {
script {
uid = sh(returnStdout: true, script: 'id -u').trim()
gid = sh(returnStdout: true, script: 'id -g').trim()
}
// pull docker
sh "docker pull ghcr.io/xmos/xcore_voice_tester:develop"
withTools(params.TOOLS_VERSION) {
sh "bash tools/ci/build_rtos_tests.sh"
sh "bash tools/ci/build_host_apps.sh"
}
// List built files for log
sh "ls -la dist/"
sh "ls -la dist_host/"
}
sh "pytest test/rtos_drivers/hil_add"
}
}
}
}
}
stage('Run RTOS Drivers USB test') {
steps {
withTools(params.TOOLS_VERSION) {
withVenv {
script {
uid = sh(returnStdout: true, script: 'id -u').trim()
gid = sh(returnStdout: true, script: 'id -g').trim()
withXTAG(["$RTOS_TEST_RIG_TARGET"]) { adapterIDs ->
sh "docker run --rm -u $uid:$gid --privileged -v /dev:/dev -w /fwk_rtos -v $WORKSPACE:/fwk_rtos ghcr.io/xmos/xcore_voice_tester:develop bash -l test/rtos_drivers/usb/check_usb.sh " + adapterIDs[0]
stage('Create virtual environment') {
steps {
// Create venv
sh "pyenv install -s $PYTHON_VERSION"
sh "~/.pyenv/versions/$PYTHON_VERSION/bin/python -m venv $VENV_DIRNAME"
// Install dependencies
withVenv() {
sh "pip install git+https://github0.xmos.com/xmos-int/xtagctl.git"
sh "pip install -r test/requirements.txt"
}
}
}
stage('Cleanup xtagctl') {
steps {
// Cleanup any xtagctl cruft from previous failed runs
withTools(params.TOOLS_VERSION) {
withVenv {
sh "xtagctl reset_all $RTOS_TEST_RIG_TARGET"
}
}
sh "rm -f ~/.xtag/status.lock ~/.xtag/acquired"
}
}
stage('Run RTOS Drivers WiFi test') {
steps {
withTools(params.TOOLS_VERSION) {
withVenv {
script {
withXTAG(["$RTOS_TEST_RIG_TARGET"]) { adapterIDs ->
sh "test/rtos_drivers/wifi/check_wifi.sh " + adapterIDs[0]
}
sh "pytest test/rtos_drivers/wifi"
}
}
}
}
sh "pytest test/rtos_drivers/usb"
}
stage('Run RTOS Drivers HIL test') {
steps {
withTools(params.TOOLS_VERSION) {
withVenv {
script {
withXTAG(["$RTOS_TEST_RIG_TARGET"]) { adapterIDs ->
sh "test/rtos_drivers/hil/check_drivers_hil.sh " + adapterIDs[0]
}
sh "pytest test/rtos_drivers/hil"
}
}
}
}
}
stage('Run RTOS Drivers HIL_Add test') {
steps {
withTools(params.TOOLS_VERSION) {
withVenv {
script {
withXTAG(["$RTOS_TEST_RIG_TARGET"]) { adapterIDs ->
sh "test/rtos_drivers/hil_add/check_drivers_hil_add.sh " + adapterIDs[0]
}
sh "pytest test/rtos_drivers/hil_add"
}
}
}
}
}
stage('Run RTOS Drivers USB test') {
steps {
withTools(params.TOOLS_VERSION) {
withVenv {
script {
uid = sh(returnStdout: true, script: 'id -u').trim()
gid = sh(returnStdout: true, script: 'id -g').trim()
withXTAG(["$RTOS_TEST_RIG_TARGET"]) { adapterIDs ->
sh "docker run --rm -u $uid:$gid --privileged -v /dev:/dev -w /fwk_rtos -v $WORKSPACE:/fwk_rtos ghcr.io/xmos/xcore_voice_tester:develop bash -l test/rtos_drivers/usb/check_usb.sh " + adapterIDs[0]
}
sh "pytest test/rtos_drivers/usb"
}
}
}
}
}
}
post {
cleanup {
// cleanWs removes all output and artifacts of the Jenkins pipeline
// Comment out this post section to leave the workspace which can be useful for running items on the Jenkins agent.
// However, beware that this pipeline will not run if the workspace is not manually cleaned.
xcoreCleanSandbox()
}
}
}
}
}
}
post {
cleanup {
// cleanWs removes all output and artifacts of the Jenkins pipeline
// Comment out this post section to leave the workspace which can be useful for running items on the Jenkins agent.
// However, beware that this pipeline will not run if the workspace is not manually cleaned.
cleanWs()
}
}
}
50 changes: 42 additions & 8 deletions doc/README.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,9 @@
Documentation Source
####################

This folder contains source files for the documentation. The sources do not render well in GitHub or an RST viewer.
In addition, some information is not visible at all and some links will not be functional.

**********************
Building Documentation
**********************
Expand All @@ -10,13 +13,7 @@ Building Documentation
Prerequisites
=============

Install `Docker <https://www.docker.com/>`_.

Pull the docker container:

.. code-block:: console
$ docker pull ghcr.io/xmos/doc_builder:latest
Use the `xmosdoc tool <https://github.com/xmos/xmosdoc>`_ either via docker or install it into a pip environment.

========
Building
Expand All @@ -26,4 +23,41 @@ To build the documentation, run the following command in the root of the reposit

.. code-block:: console
$ docker run --rm -t -u "$(id -u):$(id -g)" -v $(pwd):/build -e PDF=1 -e REPO:/build -e DOXYGEN_INCLUDE=/build/doc/Doxyfile.inc -e EXCLUDE_PATTERNS=/build/doc/exclude_patterns.inc -e DOXYGEN_INPUT=ignore ghcr.io/xmos/doc_builder:latest
# via pip package
xmosdoc clean html latex
# via docker
$ docker run --rm -t -u "$(id -u):$(id -g)" -v $(pwd):/build ghcr.io/xmos/xmosdoc clean html latex
HTML document output is saved in the ``doc/_build/html`` folder. Open ``index.html`` to preview the saved documentation.

Please refer to the ``xmosdoc`` documentation for a complete guide on how to use the tool.

**********************
Adding a New Component
**********************

Follow the following steps to add a new component.

- Add an entry for the new component's top-level document to the appropriate TOC in the documents tree.
- If the new component uses `Doxygen`, append the appropriate path(s) to the INPUT variable in `Doxyfile.inc`.
- If the new component includes `.rst` files that should **not** be part of the documentation build, append the appropriate pattern(s) to `exclude_patterns.inc`.

***
FAQ
***

Q: Is it possible to build just a subset of the documentation?

A: Yes, however it is not recommended at this time.

Q: Is it possible to used the ``livehtml`` feature of Sphinx?

A: Yes, run xmosdoc with the ``--auto`` option.

Q: Where can I learn more about the XMOS ``xmosdoc`` tools?

A: See the https://github.com/xmos/xmosdoc repository. See the ``xmosdoc`` repository README for details on additional build options.

Q: How do I suggest enhancements to the XMOS ``xmosdoc`` tool?

A: Create a new issue here: https://github.com/xmos/xmosdoc/issues
1 change: 0 additions & 1 deletion doc/build_system_guide/introduction.rst
View file
Original file line number Diff line number Diff line change
@@ -1,4 +1,3 @@
.. include:: ../substitutions.rst

.. _build_system_guide:

Expand Down
1 change: 0 additions & 1 deletion doc/build_system_guide/targets.rst
View file
Original file line number Diff line number Diff line change
@@ -1,4 +1,3 @@
.. include:: ../substitutions.rst

.. _build_system_targets:

Expand Down
Loading

0 comments on commit cb9c336

Please sign in to comment.