From 611236c9937f2e842b088a24154082159e6e8cdf Mon Sep 17 00:00:00 2001
From: Karel van Klink <karel.vanklink@geant.org>
Date: Thu, 6 Jul 2023 10:46:06 +0200
Subject: [PATCH] lint documentation in source code, instead of generated HTML
 for improved results

---
 README.md           |  2 +-
 build_docs.sh       | 11 +++++++++++
 docs/.gitlab-ci.yml |  2 +-
 docs/build_docs.sh  | 10 ----------
 docs/vale/.vale.ini | 15 +++++++++------
 gso/main.py         |  3 ---
 6 files changed, 22 insertions(+), 21 deletions(-)
 create mode 100755 build_docs.sh
 delete mode 100755 docs/build_docs.sh

diff --git a/README.md b/README.md
index 146c051f..29a7ebdb 100644
--- a/README.md
+++ b/README.md
@@ -2,4 +2,4 @@
 The GÉANT interpretation of [`orchestrator-core`](https://github.com/workfloworchestrator/orchestrator-core).
 
 ## Documentation
-You can build the documentation locally using [build_docs.sh](docs/build_docs.sh).
+You can build the documentation locally using [build_docs.sh](build_docs.sh).
diff --git a/build_docs.sh b/build_docs.sh
new file mode 100755
index 00000000..93a01493
--- /dev/null
+++ b/build_docs.sh
@@ -0,0 +1,11 @@
+#!/bin/bash
+
+docker run -it --rm -v $(pwd)/:/gso sphinxdoc/sphinx:latest /bin/bash -c \
+"pip install sphinx-autodoc2 sphinx_rtd_theme myst-parser;cd /gso/docs/source;make html"
+
+if [ ! -d ./docs/vale/styles/proselint ] || [ ! -d ./docs/vale/styles/Microsoft ]; then
+  docker run -it --rm -v $(pwd)/docs:/docs jdkato/vale:latest --config="/docs/vale/.vale.ini" sync
+fi
+
+docker run -it --rm -v $(pwd):/gso jdkato/vale:latest --glob='!*/_?ipam.py|!*/apidocs/*|!*/migrations/*' \
+--config="/gso/docs/vale/.vale.ini" /gso/docs/source /gso/gso
diff --git a/docs/.gitlab-ci.yml b/docs/.gitlab-ci.yml
index 045ea519..f0c28f63 100644
--- a/docs/.gitlab-ci.yml
+++ b/docs/.gitlab-ci.yml
@@ -34,4 +34,4 @@ lint-documentation:
     - vale sync
 
   script:
-    - vale --glob='!*/gso.services._ipam.html' --config="$CI_PROJECT_DIR/docs/vale/.vale.ini" $CI_PROJECT_DIR/docs/source/index.md $CI_PROJECT_DIR/docs/source/glossary.md $CI_PROJECT_DIR/docs/source/quickstart.md $CI_PROJECT_DIR/docs/build/html/apidocs
+    - vale --glob='!*/_?ipam.py|!*/apidocs/*|!*/migrations/*' $CI_PROJECT_DIR/docs/source $CI_PROJECT_DIR/gso
diff --git a/docs/build_docs.sh b/docs/build_docs.sh
deleted file mode 100755
index ee92182c..00000000
--- a/docs/build_docs.sh
+++ /dev/null
@@ -1,10 +0,0 @@
-#!/bin/bash
-
-docker run -it --rm -v $(pwd)/../:/gso sphinxdoc/sphinx:latest /bin/bash -c \
-"pip install sphinx-autodoc2 sphinx_rtd_theme myst-parser;cd /gso/docs/source;make html"
-
-if [ ! -d ./vale/styles/proselint ] || [ ! -d ./vale/styles/Microsoft ]; then
-  docker run -it --rm -v $(pwd):/docs jdkato/vale:latest --config="/docs/vale/.vale.ini" sync
-fi
-
-docker run -it --rm -v $(pwd):/docs jdkato/vale:latest --glob='!*/gso.services._ipam.html' --config="/docs/vale/.vale.ini" /docs/source/index.md /docs/source/glossary.md /docs/source/quickstart.md /docs/build/html/apidocs
diff --git a/docs/vale/.vale.ini b/docs/vale/.vale.ini
index e7a40f5f..f3ed552d 100644
--- a/docs/vale/.vale.ini
+++ b/docs/vale/.vale.ini
@@ -6,14 +6,17 @@ Vocab = geant-jargon, Sphinx
 
 Packages = proselint, Microsoft
 
-[*]
+[*.{md,py}]
+; We only lint .md and .py files
 BasedOnStyles = Vale, proselint, Microsoft
 Microsoft.Headings = NO
 
-[*.html]
-Microsoft.Dashes = NO
-Microsoft.HeadingAcronyms = NO
+TokenIgnores = ({term}`[^\n]+`)
 
-[/docs/source/glossary.md]
-; Ignore acronyms being undefined in the file that defines all acronyms by definition
+[*/glossary.md]
+; Ignore acronyms being undefined in the file that defines all acronyms by definition.
 Microsoft.Acronyms = NO
+
+[formats]
+; Ignore inline comments in source code, as these do not show up in generated documentation.
+py = rst
diff --git a/gso/main.py b/gso/main.py
index 44b826da..903cb9ec 100644
--- a/gso/main.py
+++ b/gso/main.py
@@ -3,10 +3,7 @@ from orchestrator import OrchestratorCore
 from orchestrator.cli.main import app as core_cli
 from orchestrator.settings import AppSettings
 
-# pylint: disable=unused-import
 import gso.products  # noqa: F401
-
-# pylint: disable=unused-import
 import gso.workflows  # noqa: F401
 
 app = OrchestratorCore(base_settings=AppSettings())
-- 
GitLab