b2/.github/workflows/doc_lint.yml at develop · ElderStack/b2 · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
name: Documentation lint 📑

# Cheap, fast doc-correctness gate -- two independent jobs, both wheel-free and
# with no compilation, so the whole workflow finishes on every PR in well under a
# minute:
#   * cpp_doc_lint    -- Doxygen doc correctness + undocumented ratchet (C++).
#   * python_doc_lint -- ast-only docstring correctness + undocumented ratchet
#                        (pure-Python package; tools/py_doclint.py).
# This is the growing home of a broader linting initiative; future linters
# (clang-format, clang-tidy, include-what-you-use, ...) can be added as more jobs.
#
# It does NOT belong in build_and_test.yml: that workflow is the expensive
# build/test matrix, and it already `paths-ignore`s Doxyfile/doc_resources/docs, so
# doc-only changes skip it and hit only this lint -- exactly the fast feedback we want.

# Source changes (core/include headers; python/bertini/**) reach this lint through
# build_and_test.yml, which calls the WHOLE workflow as a prerequisite gate (see
# workflow_call below -- both jobs run).  The standalone triggers here cover only the
# doc-config/tooling paths that build_and_test deliberately `paths-ignore`s, so the
# lint still runs for those without double-running on a typical code PR.
on:
  push:
    branches:
      - develop
      - main
    paths:
      - 'Doxyfile'
      - 'doc_resources/**'
      - 'tools/doclint.sh'
      - 'tools/doc_undocumented_baseline.txt'
      - 'tools/py_doclint.py'
      - 'tools/py_doc_undocumented_baseline.txt'
      - '.github/workflows/doc_lint.yml'
  pull_request:
    paths:
      - 'Doxyfile'
      - 'doc_resources/**'
      - 'tools/doclint.sh'
      - 'tools/doc_undocumented_baseline.txt'
      - 'tools/py_doclint.py'
      - 'tools/py_doc_undocumented_baseline.txt'
      - '.github/workflows/doc_lint.yml'
  workflow_dispatch:
  # Called by build_and_test.yml as a prerequisite gate, so no C++ compilation
  # starts until the docs lint is green.
  workflow_call:

# The undocumented-entity ratchet count in tools/doc_undocumented_baseline.txt is
# specific to this Doxygen version; CI must use the same one that seeded the
# baseline, not whatever the runner's apt happens to ship.  Bump both together.
env:
  DOXYGEN_VERSION: "1.13.2"

jobs:
  cpp_doc_lint:
    name: Doxygen doc lint (C++)
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5

      - name: Install pinned Doxygen
        run: |
          url="https://github.com/doxygen/doxygen/releases/download/Release_${DOXYGEN_VERSION//./_}/doxygen-${DOXYGEN_VERSION}.linux.bin.tar.gz"
          curl -sSL "$url" | tar -xz
          echo "$PWD/doxygen-${DOXYGEN_VERSION}/bin" >> "$GITHUB_PATH"

      - name: Show Doxygen version
        run: doxygen --version

      - name: Lint C++ documentation
        run: bash tools/doclint.sh

  # Runs in parallel with cpp_doc_lint.  Pure-stdlib ast, no build, no pip deps.
  python_doc_lint:
    name: Docstring lint (Python)
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.11'

      - name: Lint Python docstrings
        run: python tools/py_doclint.py