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 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 diff --git a/Makefile b/Makefile new file mode 100644 index 0000000..41f8397 --- /dev/null +++ b/Makefile @@ -0,0 +1,38 @@ + +.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 + + +linkcheck : + $(MAKE) -C docs linkcheck +.PHONY : linkcheck + + +lint : linkcheck +.PHONY : lint 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/). 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 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 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_dev_system.rst b/docs/source/cross_compile/config_dev_system.rst index 39adc41..68274fd 100644 --- a/docs/source/cross_compile/config_dev_system.rst +++ b/docs/source/cross_compile/config_dev_system.rst @@ -111,10 +111,10 @@ 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 + :file: media/toolchain/gcc_versions.csv :widths: 50 50 :header-rows: 1 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. 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