From 7ec268764df840303cdbc71bfe7ee790eab71627 Mon Sep 17 00:00:00 2001 From: "Travis F. Collins" Date: Mon, 9 Sep 2024 10:35:34 -0600 Subject: [PATCH] Add CI for sphinx doc builds Signed-off-by: Travis F. Collins --- .github/doc/styles/ADI/Capitalization.yml | 12 +++ .github/doc/styles/ADI/Spelling.yml | 5 ++ .github/doc/styles/ADI/Terms.yml | 14 ++++ .github/doc/styles/Google/Units.yml | 8 ++ .../config/vocabularies/Sphinx/accept.txt | 80 +++++++++++++++++++ .../config/vocabularies/Sphinx/reject.txt | 0 .github/workflows/doc.yml | 54 +++++++++++++ .github/workflows/vale.yml | 12 +++ .vale.ini | 11 +++ 9 files changed, 196 insertions(+) create mode 100644 .github/doc/styles/ADI/Capitalization.yml create mode 100644 .github/doc/styles/ADI/Spelling.yml create mode 100644 .github/doc/styles/ADI/Terms.yml create mode 100644 .github/doc/styles/Google/Units.yml create mode 100644 .github/doc/styles/config/vocabularies/Sphinx/accept.txt create mode 100644 .github/doc/styles/config/vocabularies/Sphinx/reject.txt create mode 100644 .github/workflows/doc.yml create mode 100644 .github/workflows/vale.yml create mode 100644 .vale.ini diff --git a/.github/doc/styles/ADI/Capitalization.yml b/.github/doc/styles/ADI/Capitalization.yml new file mode 100644 index 000000000..e66537e25 --- /dev/null +++ b/.github/doc/styles/ADI/Capitalization.yml @@ -0,0 +1,12 @@ +extends: capitalization +message: "'%s' should be in title case" +level: warning +scope: sentence +# $title, $sentence, $lower, $upper, or a pattern. +#match: $title +#style: AP # AP or Chicago; only applies when match is set to $title. +exceptions: + - ADC + - DAC + - adc + - dac diff --git a/.github/doc/styles/ADI/Spelling.yml b/.github/doc/styles/ADI/Spelling.yml new file mode 100644 index 000000000..f47d5ce75 --- /dev/null +++ b/.github/doc/styles/ADI/Spelling.yml @@ -0,0 +1,5 @@ +extends: spelling +message: "Did you really mean '%s'?" +level: error +ignore: + - Vocab/Sphinx/accept.txt diff --git a/.github/doc/styles/ADI/Terms.yml b/.github/doc/styles/ADI/Terms.yml new file mode 100644 index 000000000..0cd102465 --- /dev/null +++ b/.github/doc/styles/ADI/Terms.yml @@ -0,0 +1,14 @@ +# `extends` specifies the extension point you're using. Here, we're +# using `substitution` to ensure correct usage of some techincal and +# brand-specifc terminology. +extends: substitution +# `message` allows you to customize the output shown to your users. +message: Use '%s' instead of '%s'. +# We're setting this rule's severity to `error`, which will cause +# CI builds to fail. +level: error +# We're using case-insensitive patterns. +ignorecase: true +swap: + libIIO: libiio + linux: Linux diff --git a/.github/doc/styles/Google/Units.yml b/.github/doc/styles/Google/Units.yml new file mode 100644 index 000000000..8c0edb872 --- /dev/null +++ b/.github/doc/styles/Google/Units.yml @@ -0,0 +1,8 @@ +extends: existence +message: "Put a nonbreaking space between the number and the unit in '%s'." +link: 'https://developers.google.com/style/units-of-measure' +nonword: true +level: warning +tokens: + - \d+(?:B|kB|MB|GB|TB) + - \d+(?:ns|ms|s|min|h|d) diff --git a/.github/doc/styles/config/vocabularies/Sphinx/accept.txt b/.github/doc/styles/config/vocabularies/Sphinx/accept.txt new file mode 100644 index 000000000..323d9c6df --- /dev/null +++ b/.github/doc/styles/config/vocabularies/Sphinx/accept.txt @@ -0,0 +1,80 @@ +adijif +204B +204C +JESD204B +JESD204C +libiio +pypi +conda +JESD +ADI +SYSREF +LMFC +AD-FMCDAQ2-EBZ +AD9523-1 +AD9528 +AD9680 +ADRV9009 +HMC7044 +Nox +pyenv +bashrc +zshrc +Makefile +Ultrascale +Ultrascale+ +[aA][dD][cC] +[dD][aA][cC] +PLL +[nN]ox +[mM]ultiblock +codecov +mux +muxes +muxing +Fmax +parameterization +clk +[xX]ilinx +(?i)fpgas +fpga +Scopy +sysfs +iiod +IIOD +usb +Jetson +Mbed +repo +github +iio_context +iio_device +iio_channel +iio_buffer +iio_scan_context +iio_attr +iio_reg +iio_info +iio_readdev +iio_writedev +iio_rwdev +iio_stresstest +iio_genxml +arg +pid +hostname +data_bits +parity_bits +stop_bits +flow_control +Xon +Xoff + +ip +uri +deinterleave +endianness +zeroconf +attr +Doxygen +Nechita diff --git a/.github/doc/styles/config/vocabularies/Sphinx/reject.txt b/.github/doc/styles/config/vocabularies/Sphinx/reject.txt new file mode 100644 index 000000000..e69de29bb diff --git a/.github/workflows/doc.yml b/.github/workflows/doc.yml new file mode 100644 index 000000000..7e8797b71 --- /dev/null +++ b/.github/workflows/doc.yml @@ -0,0 +1,54 @@ +name: Documentation Tests + +on: [push, pull_request] + +jobs: + CheckDocs: + runs-on: ubuntu-latest + + steps: + - uses: actions/checkout@v2 + - name: Set up Python 3.8 + uses: actions/setup-python@v2 + with: + python-version: 3.8 + + - name: Install dependencies + run: | + sudo apt-get -qq update + sudo apt-get install -y git cmake graphviz libavahi-common-dev libavahi-client-dev libaio-dev libusb-1.0-0-dev libxml2-dev rpm tar bzip2 gzip flex bison git libzstd-dev doxygen pandoc + mkdir build + cd build + cmake .. -DWITH_MAN=ON -DHAVE_DNS_SD=OFF + make + sudo make install + cd .. + cd doc + pip install -r requirements_doc.txt + cd .. + + - name: Build man pages + run: | + cd doc + python man_to_rst.py + cd .. + + - name: Check doc build + run: | + cd doc + make html SPHINXOPTS="-W" + cd .. + + # - name: Check doc coverage + # run: | + # cd doc + # make coverage + # cat build/coverage/python.txt + # cat build/coverage/python.txt | wc -l | xargs -I % test % -eq 2 + # cd .. + + - name: Check doc links + run: | + cd doc + make linkcheck + cd .. \ No newline at end of file diff --git a/.github/workflows/vale.yml b/.github/workflows/vale.yml new file mode 100644 index 000000000..20d6d49e7 --- /dev/null +++ b/.github/workflows/vale.yml @@ -0,0 +1,12 @@ +name: reviewdog +on: [pull_request,push] + +jobs: + vale: + name: runner / vale + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + - uses: errata-ai/vale-action@reviewdog + with: + files: doc/source diff --git a/.vale.ini b/.vale.ini new file mode 100644 index 000000000..630d9b6be --- /dev/null +++ b/.vale.ini @@ -0,0 +1,11 @@ +StylesPath = .github/doc/styles +MinAlertLevel = suggestion + + +Vocab = Sphinx + +[*.rst] +BasedOnStyles = ADI, Vale, Google + +[*.md] +BasedOnStyles = ADI, Vale, Google