diff --git a/CHANGES.md b/CHANGES.md index 452949e..38ffd6c 100644 --- a/CHANGES.md +++ b/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) diff --git a/README.md b/README.md index c83dc46..8472319 100644 --- a/README.md +++ b/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 diff --git a/docs/source/conf.py b/docs/source/conf.py index 02aa035..459eab9 100644 --- a/docs/source/conf.py +++ b/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 diff --git a/docs/source/contributing.md b/docs/source/contributing.md index 1624f9f..c0b125c 100644 --- a/docs/source/contributing.md +++ b/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 diff --git a/pyproject.toml b/pyproject.toml index 964897c..7bbdaa3 100644 --- a/pyproject.toml +++ b/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" } diff --git a/src/mxmake/topics/docs/sphinx.mk b/src/mxmake/topics/docs/sphinx.mk index c36d08e..046931f 100644 --- a/src/mxmake/topics/docs/sphinx.mk +++ b/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)