Refine doc handling

* remove CI scripts and use Makefile targets instead
* ensure doc8 runs quiet
* add new docs-check make target to run documentation and links checks
* update oudated doc for docs contribution

Signed-off-by: Philippe Ombredanne <pombredanne@nexb.com>

Author: pombredanne

.github/workflows/docs-ci.yml

@@ -21,14 +21,12 @@ jobs:
           python-version: ${{ matrix.python-version }}
 
       - name: Install Dependencies
-        run:  pip install -e .[docs]
+        run:  ./configure --dev
 
-      - name: Check Sphinx Documentation build minimally
-        working-directory: ./docs
-        run: sphinx-build -E -W source build
+      - name: Check documentation and HTML for errors and dead links
+        run: make docs-check
 
-      - name: Check for documentation style errors
-        working-directory: ./docs
-        run: ./scripts/doc8_style_check.sh
+      - name: Check documentation for style errors
+        run: make doc8
 
 

Makefile

@@ -19,7 +19,7 @@ dev:
 
 doc8:
 	@echo "-> Run doc8 validation"
-	@${ACTIVATE} doc8 docs/ *.rst
+	@${ACTIVATE} doc8 --quiet docs/ *.rst
 
 valid:
 	@echo "-> Run Ruff format"
@@ -46,6 +46,10 @@ test:
 
 docs:
 	rm -rf docs/_build/
-	@${ACTIVATE} sphinx-build docs/ docs/_build/
+	@${ACTIVATE} sphinx-build docs/source docs/_build/
 
-.PHONY: conf dev check valid clean test docs
+docs-check:
+	@${ACTIVATE} sphinx-build -E -W -b html docs/source docs/_build/
+	@${ACTIVATE} sphinx-build -E -W -b linkcheck docs/source docs/_build/
+
+.PHONY: conf dev check valid clean test docs docs-check

docs/scripts/doc8_style_check.sh

@@ -18,7 +18,7 @@
 # -- Project information -----------------------------------------------------
 
 project = "nexb-skeleton"
-copyright = "nexB Inc. and others."
+copyright = "nexB Inc., AboutCode and others."
 author = "AboutCode.org authors and contributors"
 
 

docs/scripts/sphinx_build_link_check.sh

@@ -147,7 +147,7 @@ What is Checked?
 ^^^^^^^^^^^^^^^^
 
 PyCQA is an Organization for code quality tools (and plugins) for the Python programming language.
-Doc8 is a sub-project of the same Organization. Refer this `README <https://github.com/PyCQA/doc8/blob/master/README.rst>`_ for more details.
+Doc8 is a sub-project of the same Organization. Refer this `README <https://github.com/PyCQA/doc8/blob/main/README.rst>`_ for more details.
 
 What is checked:
 
@@ -169,11 +169,11 @@ What is checked:
 Interspinx
 ----------
 
-ScanCode toolkit documentation uses `Intersphinx <http://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html>`_
+ScanCode toolkit documentation uses `Intersphinx <https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html>`_
 to link to other Sphinx Documentations, to maintain links to other Aboutcode Projects.
 
 To link sections in the same documentation, standart reST labels are used. Refer
-`Cross-Referencing <http://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#ref-role>`_ for more information.
+`Cross-Referencing <https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html>`_ for more information.
 
 For example::
 
@@ -230,7 +230,7 @@ Style Conventions for the Documentaion
 
 1. Headings
 
-    (`Refer <http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#sections>`_)
+    (`Refer <https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#sections>`_)
     Normally, there are no heading levels assigned to certain characters as the structure is
     determined from the succession of headings. However, this convention is used in Python’s Style
     Guide for documenting which you may follow:

docs/source/conf.py

@@ -122,7 +122,5 @@ max-complexity = 10
 
 
 [tool.doc8]
-
 ignore-path = ["docs/build", "doc/build", "docs/_build", "doc/_build"]
 max-line-length=100
-verbose=0