lint documentation in source code, instead of generated HTML for improved results

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).

build_docs.sh

+#!/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

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

docs/build_docs.sh

-#!/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

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

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())