Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

fixes for xmosdoc v4 #203

Merged
merged 6 commits into from
Oct 20, 2023
Merged

fixes for xmosdoc v4 #203

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
2b9fa5b
fixes for xmosdoc v4
BrennanGit Sep 22, 2023
7b23dcf
move docs build to jenkins
BrennanGit Sep 22, 2023
db522c6
update xjsl for PR labels
BrennanGit Sep 22, 2023
3373be1
doc_Builder -> xmosdoc
BrennanGit Oct 3, 2023
26e5bd3
Update doc README.rst
BrennanGit Oct 3, 2023
abf837a
set xmosdoc version to v4
BrennanGit Oct 10, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
44 changes: 0 additions & 44 deletions .github/workflows/docs.yml
View file
Open in desktop

This file was deleted.

236 changes: 134 additions & 102 deletions Jenkinsfile
View file
Open in desktop
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
Open in desktop
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
Open in desktop
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
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,3 @@
.. include:: ../substitutions.rst

.. _build_system_targets:

Expand Down
Loading