build: add Documentation linting step to CI

.github/workflows/docs-lint.yml

@@ -0,0 +1,41 @@
+name: Documentation linter
+
+on:
+  pull_request:
+  push:
+    branches:
+      - master
+
+jobs:
+  run_tests:
+    name: Quality Others
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-22.04]
+        python-version:
+          - "3.11"
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 2
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install system requirements
+        run: sudo apt update && sudo apt install -y libxmlsec1-dev
+
+      - name: Install pip
+        run: python -m pip install -r requirements/pip.txt
+
+      - name: Install Required Python Dependencies
+        run: |
+          pip install -r requirements/edx/doc.txt
+
+      - name: Run lint check
+        run: |
+          make docs-lint

Makefile

@@ -30,6 +30,9 @@ SWAGGER = docs/lms-openapi.yaml
 docs: swagger guides technical-docs ## build the documentation for this repository
 	$(MAKE) -C docs html
 
+docs-lint: swagger guides technical-docs ## build the documentation for this repository
+	$(MAKE) -C docs lint
+
 swagger: ## generate the swagger.yaml file
 	DJANGO_SETTINGS_MODULE=docs.docs_settings python manage.py lms generate_swagger --generator-class=edx_api_doc_tools.ApiSchemaGenerator -o $(SWAGGER)
 

docs/Makefile

@@ -4,14 +4,15 @@
 # You can set these variables from the command line.
 SPHINXOPTS    =
 SPHINXBUILD   = sphinx-build
+SPHINXLINT    = sphinx-lint
 SOURCEDIR     = .
 BUILDDIR      = _build
 
 # Put it first so that "make" without argument is like "make help".
 help:
 	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
-.PHONY: help clean Makefile
+.PHONY: help clean lint Makefile
 
 clean:
 	rm -rf _build cms common lms openedx
@@ -21,6 +22,9 @@ clean:
 %: Makefile
 	$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
+lint:
+	$(SPHINXLINT) "$(SOURCEDIR)"
+
 update_redirects:
 	# This updates redirects.txt, creating redirects for any files that have moved (relative to master).
 	sphinx-build -b rediraffewritediff "$(SOURCEDIR)" "$(BUILDDIR)"

requirements/edx/development.txt

@@ -1484,6 +1484,7 @@ polib==1.2.0
     #   -r requirements/edx/doc.txt
     #   -r requirements/edx/testing.txt
     #   edx-i18n-tools
+    #   sphinx-lint
 prompt-toolkit==3.0.48
     # via
     #   -r requirements/edx/doc.txt
@@ -1820,6 +1821,7 @@ regex==2024.9.11
     #   -r requirements/edx/doc.txt
     #   -r requirements/edx/testing.txt
     #   nltk
+    #   sphinx-lint
 requests==2.32.3
     # via
     #   -r requirements/edx/doc.txt
@@ -2005,6 +2007,8 @@ sphinx-book-theme==1.1.3
     # via -r requirements/edx/doc.txt
 sphinx-design==0.6.1
     # via -r requirements/edx/doc.txt
+sphinx-lint==1.0.0
+    # via -r requirements/edx/doc.txt
 sphinx-mdinclude==0.6.2
     # via
     #   -r requirements/edx/doc.txt

requirements/edx/doc.in

@@ -7,6 +7,7 @@ sphinx-book-theme         # Common theme for all Open edX projects
 gitpython                 # fetch git repo information
 Sphinx                    # Documentation builder
 sphinx-design             # provides various responsive web-components
+sphinx-lint               # documentation lint checker
 sphinxcontrib-openapi[markdown] # Be able to render openapi schema in a sphinx project
 sphinxext-rediraffe       # Quickly and easily redirect when we move pages around.
 sphinx-reredirects        # Redirect from a sphinx project out to other places on the web including other sphinx projects

requirements/edx/doc.txt

@@ -1054,6 +1054,7 @@ polib==1.2.0
     # via
     #   -r requirements/edx/base.txt
     #   edx-i18n-tools
+    #   sphinx-lint
 prompt-toolkit==3.0.48
     # via
     #   -r requirements/edx/base.txt
@@ -1262,6 +1263,7 @@ regex==2024.9.11
     # via
     #   -r requirements/edx/base.txt
     #   nltk
+    #   sphinx-lint
 requests==2.32.3
     # via
     #   -r requirements/edx/base.txt
@@ -1412,6 +1414,8 @@ sphinx-book-theme==1.1.3
     # via -r requirements/edx/doc.in
 sphinx-design==0.6.1
     # via -r requirements/edx/doc.in
+sphinx-lint==1.0.0
+    # via -r requirements/edx/doc.in
 sphinx-mdinclude==0.6.2
     # via sphinxcontrib-openapi
 sphinx-reredirects==0.1.5