From 16777776f160ca9431360d939e4194beb52fb1f6 Mon Sep 17 00:00:00 2001
From: Jillian Vogel <jill@opencraft.com>
Date: Thu, 7 Nov 2024 16:37:03 +1030
Subject: [PATCH] build: add Documentation linting step to CI

using sphinx-lint
---
 .github/workflows/docs-lint.yml  | 41 ++++++++++++++++++++++++++++++++
 Makefile                         |  3 +++
 docs/Makefile                    |  6 ++++-
 requirements/edx/development.txt |  4 ++++
 requirements/edx/doc.in          |  1 +
 requirements/edx/doc.txt         |  4 ++++
 6 files changed, 58 insertions(+), 1 deletion(-)
 create mode 100644 .github/workflows/docs-lint.yml

diff --git a/.github/workflows/docs-lint.yml b/.github/workflows/docs-lint.yml
new file mode 100644
index 000000000000..4ed156db42ff
--- /dev/null
+++ b/.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
diff --git a/Makefile b/Makefile
index 15bab5df67a9..e8348017f24b 100644
--- a/Makefile
+++ b/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)
 
diff --git a/docs/Makefile b/docs/Makefile
index 3c8a65d81cdb..5c9857061e2d 100644
--- a/docs/Makefile
+++ b/docs/Makefile
@@ -4,6 +4,7 @@
 # You can set these variables from the command line.
 SPHINXOPTS    =
 SPHINXBUILD   = sphinx-build
+SPHINXLINT    = sphinx-lint
 SOURCEDIR     = .
 BUILDDIR      = _build
 
@@ -11,7 +12,7 @@ BUILDDIR      = _build
 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)"
diff --git a/requirements/edx/development.txt b/requirements/edx/development.txt
index c5a839650847..dfd57a7f4d06 100644
--- a/requirements/edx/development.txt
+++ b/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
diff --git a/requirements/edx/doc.in b/requirements/edx/doc.in
index 013bafc42ec0..930f6cbf7653 100644
--- a/requirements/edx/doc.in
+++ b/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
diff --git a/requirements/edx/doc.txt b/requirements/edx/doc.txt
index 5c447ee1b695..e5f8845116d0 100644
--- a/requirements/edx/doc.txt
+++ b/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