Merge pull request #52 from mxstack/feature/docs-linkcheck

feat: docs-linkcheck added for sphinx.mk

Author: rnixx

CHANGES.md

@@ -2,9 +2,10 @@
 
 ## 1.3.1 (unreleased)
 
-- Fix theme for newer Sphinx 7.x.
-- Add support for Python 3.14.
-- Fix interactive uv venv, use --allow-existing instead.
+- Fix: theme for newer Sphinx 7.x.
+- Fix: interactive uv venv, use --allow-existing instead.
+- Feature: Add support for Python 3.14.
+- Feature: Add `docs-linkcheck` to check for broken links in the sphinx documentation.
 
 ## 1.3.0 (2025-09-03)
 

README.md

@@ -18,7 +18,7 @@ The detailed `mxmake` documentation is available [mxstack.github.io/mxmake](http
 
 # Copyright
 
-- Copyright (c) 2022-2024 mxstack Contributors
+- Copyright (c) 2022-2025 mxstack Contributors
 - BSD 2-clause license (see below)
 
 Contributors

docs/source/conf.py

@@ -77,3 +77,16 @@
 
 # Logo configuration
 html_logo = "_static/mxmake-logo.svg"
+
+# -- Options for linkcheck builder -------------------------------------------
+
+# Ignore localhost URLs (they're examples, not real links to check)
+# Also ignore links that linkcheck has issues with but are actually valid
+linkcheck_ignore = [
+    r"http://localhost:\d+",
+    r"https://gist\.github\.com/.*#.*",  # GitHub gist anchors cause false positives
+    r"https://www\.gnu\.org/.*",  # gnu.org frequently times out but links are valid
+]
+
+# Increase timeout for slow sites
+linkcheck_timeout = 60

docs/source/contributing.md

@@ -2,7 +2,7 @@
 
 ## Source Code
 
-The sources are in a GIT DVCS with its main branches at [Github](http://github.com/mxstack/mxmake).
+The sources are in a GIT DVCS with its main branches at [Github](https://github.com/mxstack/mxmake).
 
 ## Copyright & Licence
 

pyproject.toml

@@ -1,7 +1,7 @@
 [project]
 name = "mxmake"
 description = "Generates a Python project-specific Makefile by using an extensible library of configurable Makefile snippets."
-version = "1.3.0"
+version = "1.4.0"
 keywords = ["development", "deployment", "make"]
 authors = [
   {name = "MX Stack Developers", email = "dev@bluedynamics.com" }

src/mxmake/topics/docs/sphinx.mk

@@ -11,6 +11,9 @@
 #:description = Rebuild Sphinx documentation on changes, with live-reload in
 #:  the browser using `sphinx-autobuild`.
 #:
+#:[target.docs-linkcheck]
+#:description = Run Sphinx linkcheck to verify external links in documentation.
+#:
 #:[target.docs-clean]
 #:description = Removes generated docs.
 #:
@@ -22,6 +25,10 @@
 #:description = Documentation generation target folder.
 #:default = docs/html
 #:
+#:[setting.DOCS_LINKCHECK_FOLDER]
+#:description = Documentation linkcheck output folder.
+#:default = docs/linkcheck
+#:
 #:[setting.DOCS_REQUIREMENTS]
 #:description = Documentation Python requirements to be installed (via pip).
 #:default =
@@ -52,6 +59,11 @@ docs-live: $(DOCS_TARGET) $(DOCS_TARGETS)
 	@echo "Rebuild Sphinx documentation on changes, with live-reload in the browser"
 	@$(SPHINX_AUTOBUILD_BIN) $(DOCS_SOURCE_FOLDER) $(DOCS_TARGET_FOLDER)
 
+.PHONY: docs-linkcheck
+docs-linkcheck: $(DOCS_TARGET) $(DOCS_TARGETS)
+	@echo "Run Sphinx linkcheck"
+	@$(SPHINX_BIN) -b linkcheck $(DOCS_SOURCE_FOLDER) $(DOCS_LINKCHECK_FOLDER)
+
 .PHONY: docs-dirty
 docs-dirty:
 	@rm -f $(DOCS_TARGET)