From 7425f3d44000febb8a22c4fd78d91a790ddf6493 Mon Sep 17 00:00:00 2001 From: Alex Stewart Date: Fri, 5 Sep 2025 16:28:28 -0400 Subject: [PATCH 1/9] docs: remove make.bat We do not support building the sources on Windows, so remove the unneeded batch file. Signed-off-by: Alex Stewart --- docs/make.bat | 35 ----------------------------------- 1 file changed, 35 deletions(-) delete mode 100644 docs/make.bat diff --git a/docs/make.bat b/docs/make.bat deleted file mode 100644 index 747ffb7..0000000 --- a/docs/make.bat +++ /dev/null @@ -1,35 +0,0 @@ -@ECHO OFF - -pushd %~dp0 - -REM Command file for Sphinx documentation - -if "%SPHINXBUILD%" == "" ( - set SPHINXBUILD=sphinx-build -) -set SOURCEDIR=source -set BUILDDIR=build - -%SPHINXBUILD% >NUL 2>NUL -if errorlevel 9009 ( - echo. - echo.The 'sphinx-build' command was not found. Make sure you have Sphinx - echo.installed, then set the SPHINXBUILD environment variable to point - echo.to the full path of the 'sphinx-build' executable. Alternatively you - echo.may add the Sphinx directory to PATH. - echo. - echo.If you don't have Sphinx installed, grab it from - echo.https://www.sphinx-doc.org/ - exit /b 1 -) - -if "%1" == "" goto help - -%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% -goto end - -:help -%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% - -:end -popd From 8cb0a9044cacb6c09f3ce892bb666a4a2f80830e Mon Sep 17 00:00:00 2001 From: Alex Stewart Date: Fri, 5 Sep 2025 16:41:36 -0400 Subject: [PATCH 2/9] Add a python requirements.txt file Sphinx documentation output can vary substantially between sphinx build environments, if there is no way to coordinate python module versions between build systems. Use a requirements.txt file to do that coordination. Signed-off-by: Alex Stewart --- requirements.txt | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) create mode 100644 requirements.txt diff --git a/requirements.txt b/requirements.txt new file mode 100644 index 0000000..f3d57b2 --- /dev/null +++ b/requirements.txt @@ -0,0 +1,22 @@ +alabaster==1.0.0 +babel==2.17.0 +certifi==2025.8.3 +charset-normalizer==3.4.3 +docutils==0.21.2 +idna==3.10 +imagesize==1.4.1 +Jinja2==3.1.6 +MarkupSafe==3.0.2 +packaging==25.0 +Pygments==2.19.2 +requests==2.32.5 +roman-numerals-py==3.1.0 +snowballstemmer==3.0.1 +Sphinx==8.2.3 +sphinxcontrib-applehelp==2.0.0 +sphinxcontrib-devhelp==2.0.0 +sphinxcontrib-htmlhelp==2.1.0 +sphinxcontrib-jsmath==1.0.1 +sphinxcontrib-qthelp==2.0.0 +sphinxcontrib-serializinghtml==2.0.0 +urllib3==2.5.0 From 254b06a12803e0097f129325c20d65fdb2622846 Mon Sep 17 00:00:00 2001 From: Alex Stewart Date: Fri, 5 Sep 2025 16:33:19 -0400 Subject: [PATCH 3/9] Add a top-level Makefile Add a top-level Makefile for convenience. Update the README with new build instructions. Signed-off-by: Alex Stewart --- Makefile | 29 +++++++++++++++++++++++++++++ README.md | 36 +++++++++++++++++++++++------------- 2 files changed, 52 insertions(+), 13 deletions(-) create mode 100644 Makefile diff --git a/Makefile b/Makefile new file mode 100644 index 0000000..a07cbe7 --- /dev/null +++ b/Makefile @@ -0,0 +1,29 @@ + +.DEFAULT_GOAL := all + +# DIRECTORIES +srcdir := src +# /DIRECTORIES + +# BINARIES +export MAKE ?= make +export PYTHON ?= python3 +export SPHINXBUILD = $(PYTHON) -m sphinx +# /BINARIES + + +# REAL TARGETS # +################ + + +# PHONY TARGETS # +################# + +all : + $(MAKE) -C docs html +.PHONY : all + + +clean : + $(MAKE) -C docs clean +.PHONY : clean diff --git a/README.md b/README.md index c04f700..cedac06 100644 --- a/README.md +++ b/README.md @@ -1,24 +1,34 @@ # nilrt-docs -Repository for the https://nilrt-docs.ni.com documentation pages for NI Linux Real-Time. +Official documentation for the NI Linux Real-Time OS. + +The built documentation is hosted at [https://nilrt-docs.ni.com/](https://nilrt-docs.ni.com/). -## Introduction -This project contains community sourced documentation for the NI Linux Real-Time Operating System. This documentation is hosted at https://nilrt-docs.ni.com. ## Building This documentation is built using Sphinx. To build: -1. [Install Sphinx using whichever method you prefer from the official Sphinx documentation.](https://www.sphinx-doc.org/en/master/usage/installation.html). Ensure that the version of Sphinx is greater than or equal to v3.0. -2. Clone this repo. - ``` bash - git clone https://github.com/ni/nilrt-docs - cd nilrt-docs - ``` -3. Run the following commands. +1. Install the host build tools. + * [GNU Make](https://www.gnu.org/software/make/) + * [Python3](https://www.python.org/downloads/) + +1. Install the python requirements specified in [`:requirements.txt`](./requirements.txt). + It is recommended that you use a python virtual environment. + + ```bash + python3 -m venv .venv + source .venv/bin/activate + pip install --upgrade pip + pip install -r requirements.txt + ``` + +1. Build the project using the included Makefile. + ``` bash - cd docs/ - make html + make all ``` -4. Navigate to the built html tree at `docs/build/html` + + The built documentation output will appear under `:docs/build/html/`. + ## About NI Linux Real-Time To learn about NI Linux Real-Time, visit the [NI Linux Real-Time Portal](http://www.ni.com/white-paper/14627/en/). From 8e5bb097acb89f539c1cefe6e79370d0465cf5f7 Mon Sep 17 00:00:00 2001 From: Alex Stewart Date: Fri, 5 Sep 2025 17:18:35 -0400 Subject: [PATCH 4/9] Use sphinx linkcheck to check link validity Add a Makefile target to run the Sphinx linkcheck 'builder', which actually checks the validity of the external links in the documentation. Fixup a couple broken links found in the documentation. Signed-off-by: Alex Stewart --- Makefile | 9 +++++++++ docs/source/conf.py | 16 ++++++++++++++++ docs/source/cross_compile/config_vs_code.rst | 2 +- .../source/opkg-keyrings/opkg-keyrings_index.rst | 2 +- 4 files changed, 27 insertions(+), 2 deletions(-) diff --git a/Makefile b/Makefile index a07cbe7..41f8397 100644 --- a/Makefile +++ b/Makefile @@ -27,3 +27,12 @@ all : clean : $(MAKE) -C docs clean .PHONY : clean + + +linkcheck : + $(MAKE) -C docs linkcheck +.PHONY : linkcheck + + +lint : linkcheck +.PHONY : lint diff --git a/docs/source/conf.py b/docs/source/conf.py index c83797f..b80de3e 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -65,3 +65,19 @@ html_sidebars = { '**': ['localtoc.html', 'relations.html', 'github_link.html', 'searchbox.html'], } + + +# -- Options for linkcheck builder ------------------------------------------- + +from os import cpu_count + +linkcheck_workers = cpu_count() # Use as many workers as there are CPU cores + +linkcheck_ignore = [ + r"https://linux.die.net/.*", # linux.die.next denies robots with 403 +] + +linkcheck_anchors_ignore_for_url = [ + r"https://www.ni.com/en-us/support/downloads/.*", # NI Downloads pages use dynamic anchors + r"https://github.com/ni/linux/blob/.*", # Probably a GH file reference, which use dynamic anchors +] diff --git a/docs/source/cross_compile/config_vs_code.rst b/docs/source/cross_compile/config_vs_code.rst index 2a81620..c7ae7ab 100644 --- a/docs/source/cross_compile/config_vs_code.rst +++ b/docs/source/cross_compile/config_vs_code.rst @@ -213,7 +213,7 @@ includes and other necessary resources. directory: *c_cpp_properties.json*. The file should also be open in the editor. For more information on *c_cpp_properties.json*, refer to the official documentation at `c_cpp_properties.json - reference `__. + reference `__. .. image:: media/config_vscode/image8.png diff --git a/docs/source/opkg-keyrings/opkg-keyrings_index.rst b/docs/source/opkg-keyrings/opkg-keyrings_index.rst index 56b219f..c56771a 100644 --- a/docs/source/opkg-keyrings/opkg-keyrings_index.rst +++ b/docs/source/opkg-keyrings/opkg-keyrings_index.rst @@ -137,7 +137,7 @@ However, if the signing keys used by the feeds are rotated, the target system re to add the new key and remove any obsolete keys no longer in use. The latest version of the `opkg-keyrings` package, available on the distribution feed -(https://download.ni.com/#ni-linux-rt/feeds/dist/), is built with the updated signing keys. +(https://download.ni.com/ni-linux-rt/feeds/dist/), is built with the updated signing keys. Upgrading this package on the target system installs the new signing key to /usr/share/opkg/keyrings, updates the keyring by adding the new key, and removes any deprecated keys no longer used to sign the feeds. From ec4d715339c13e5e9589b5ef81841c8e1909c828 Mon Sep 17 00:00:00 2001 From: Alex Stewart Date: Fri, 5 Sep 2025 17:26:58 -0400 Subject: [PATCH 5/9] .github: add a pr-check workflow The PR check should try to build the project and lint it. If either fails, the PR shouldn't be accepted. Signed-off-by: Alex Stewart --- .github/actions/build/action.yml | 41 ++++++++++++++++++++++++++++++++ .github/workflows/pr-check.yml | 20 ++++++++++++++++ 2 files changed, 61 insertions(+) create mode 100644 .github/actions/build/action.yml create mode 100644 .github/workflows/pr-check.yml diff --git a/.github/actions/build/action.yml b/.github/actions/build/action.yml new file mode 100644 index 0000000..07d6acd --- /dev/null +++ b/.github/actions/build/action.yml @@ -0,0 +1,41 @@ +name: Build Project +description: Install build dependencies, build the project, and upload artifacts. + +inputs: + python-version: + description: Python version to use + required: false + default: '3.13' + +runs: + using: "composite" + steps: + - name: Set up Python + uses: actions/setup-python@v4 + with: + python-version: ${{ inputs.python-version }} + + - name: Install project python dependencies + shell: bash + run: | + python -m pip install --upgrade pip + pip install -r requirements.txt + pip install cyclonedx-bom + + - name: Build project + shell: bash + run: | + make all + + - name: Generate SBOMS + shell: bash + run: | + mkdir -p docs/build/sbom + pip freeze --all | cyclonedx-py requirements - >docs/build/sbom/host-python.sbom.cdx.json + dpkg-query --list >docs/build/sbom/host-packages.sbom.txt + + - name: Upload build artifacts + uses: actions/upload-artifact@v4 + with: + name: build + path: docs/build/ diff --git a/.github/workflows/pr-check.yml b/.github/workflows/pr-check.yml new file mode 100644 index 0000000..351d22e --- /dev/null +++ b/.github/workflows/pr-check.yml @@ -0,0 +1,20 @@ +name: PR Checks + +on: [pull_request] + +jobs: + Build: + runs-on: ubuntu-latest + + env: + SPHINXOPTS: -W + + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Build project + uses: ./.github/actions/build + + - name: Lint docs + run: make lint From 2ebbb3776d156d88a7b214e3ea053d4237e41e35 Mon Sep 17 00:00:00 2001 From: Alex Stewart Date: Fri, 5 Sep 2025 17:38:34 -0400 Subject: [PATCH 6/9] .github:publish-page.yml: use peaceiris' gh-pages action Use peaceiris' gh-pages action to create and publish the gh-pages, because it can do so in an automated fashion (does not require final approval from an admin.) When using this action, it automatically adds a .nojekyll file, so remove the unneeded source file. Signed-off-by: Alex Stewart --- .github/workflows/publish-page.yml | 42 +++++++++++++----------------- .nojekyll | 0 2 files changed, 18 insertions(+), 24 deletions(-) delete mode 100644 .nojekyll diff --git a/.github/workflows/publish-page.yml b/.github/workflows/publish-page.yml index a6999e3..852a985 100644 --- a/.github/workflows/publish-page.yml +++ b/.github/workflows/publish-page.yml @@ -1,32 +1,26 @@ + name: "Publish Documentation" on: push: branches: - - main + - main + jobs: - build: + deploy: runs-on: ubuntu-latest steps: - - uses: actions/setup-python@v2 - - uses: actions/checkout@master - with: - fetch-depth: 0 # otherwise, you will failed to push refs to dest repo - - name: Build and Commit - uses: sphinx-notes/pages@v2 - with: - target_branch: 'gh-pages' - documentation_path: './docs/source' - - name: Preserve Configuration Files - run: | - echo "* @amstewart" > CODEOWNERS - git checkout gh-pages^ -- CNAME - - name: Create Pull Request - uses: peter-evans/create-pull-request@v4 - with: - token: ${{ secrets.GITHUB_TOKEN }} - base: 'gh-pages' - delete-branch: true - title: 'gh-pages updates from ${{ github.sha }}' - branch: 'dev/automated-updates-${{ github.sha }}' - body: 'Automated updates to published pages from ${{ github.sha }}' + - name: Checkout main branch + uses: actions/checkout@v4 + with: + fetch-depth: 0 + + - name: Build project + uses: ./.github/actions/build + + - name: Deploy to GitHub Pages + uses: peaceiris/actions-gh-pages@v4 + with: + github_token: ${{ secrets.GITHUB_TOKEN }} + publish_dir: docs/build/html + publish_branch: gh-pages diff --git a/.nojekyll b/.nojekyll deleted file mode 100644 index e69de29..0000000 From 72dd53252be8778df7de79458b6209307c2987ce Mon Sep 17 00:00:00 2001 From: Alex Stewart Date: Tue, 2 Dec 2025 11:38:28 -0500 Subject: [PATCH 7/9] config_dev_system: fixup too-short header Resolves docutils compile warning. Signed-off-by: Alex Stewart --- docs/source/cross_compile/config_dev_system.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/cross_compile/config_dev_system.rst b/docs/source/cross_compile/config_dev_system.rst index 39adc41..8e0010f 100644 --- a/docs/source/cross_compile/config_dev_system.rst +++ b/docs/source/cross_compile/config_dev_system.rst @@ -111,7 +111,7 @@ Installing the C/C++ Cross Compile Toolchains --------------------------------------------- GNU C & C++ Compile Tools x64 GCC version -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. csv-table:: GCC Versions :file: media/gcc/gcc_versions.csv From a2e9bf60a994d1979580891cc121ccdb2f8d39c2 Mon Sep 17 00:00:00 2001 From: Alex Stewart Date: Tue, 2 Dec 2025 11:45:36 -0500 Subject: [PATCH 8/9] config_dev_system: fixup gcc versions table Previous table file path pointed at an obsolete file. Corrected to new file path. Signed-off-by: Alex Stewart --- docs/source/cross_compile/config_dev_system.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/cross_compile/config_dev_system.rst b/docs/source/cross_compile/config_dev_system.rst index 8e0010f..68274fd 100644 --- a/docs/source/cross_compile/config_dev_system.rst +++ b/docs/source/cross_compile/config_dev_system.rst @@ -114,7 +114,7 @@ GNU C & C++ Compile Tools x64 GCC version ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. csv-table:: GCC Versions - :file: media/gcc/gcc_versions.csv + :file: media/toolchain/gcc_versions.csv :widths: 50 50 :header-rows: 1 From 47122f9170fc9b5ba5110dd2dd25928ee51b5a76 Mon Sep 17 00:00:00 2001 From: Alex Stewart Date: Tue, 2 Dec 2025 11:48:26 -0500 Subject: [PATCH 9/9] clamav: fixup clamav wiki FAQ link Signed-off-by: Alex Stewart --- docs/source/clamav/clamav.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/clamav/clamav.rst b/docs/source/clamav/clamav.rst index 56aa137..5e63272 100644 --- a/docs/source/clamav/clamav.rst +++ b/docs/source/clamav/clamav.rst @@ -233,5 +233,5 @@ Additional Resources - `Scanning Usage Guide `_ - Comprehensive scanning options and examples - `Freshclam Configuration `_ - Signature update configuration - `Signature Management `_ - Managing virus definition databases -- `ClamAV FAQ `_ - Frequently asked questions and troubleshooting tips +- `ClamAV FAQ `_ - Frequently asked questions and troubleshooting tips - `CVDUpdate Utility `_ - Python utility for offline signature updates