From 089242225e1da3b19429e731194bea6f8b61ade1 Mon Sep 17 00:00:00 2001 From: "Matteo A.C. Rossi" Date: Fri, 10 Jul 2026 17:44:21 +0300 Subject: [PATCH 1/2] =?UTF-8?q?ci(docs):=20=F0=9F=94=97=20add=20source=20a?= =?UTF-8?q?nd=20post-build=20link=20checks?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add lychee-based docs link checking for both source MDX (internal links) and built HTML output (including external links), and wire both checks into the documentation workflow. Update docs commands in README accordingly. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- .github/workflows/docpages.yml | 20 ++++++++++++++++++++ .lychee.postbuild.toml | 11 +++++++++++ .lychee.toml | 8 ++++++++ README.md | 5 +++++ justfile | 8 ++++++++ 5 files changed, 52 insertions(+) create mode 100644 .lychee.postbuild.toml create mode 100644 .lychee.toml diff --git a/.github/workflows/docpages.yml b/.github/workflows/docpages.yml index d400b358..149591bc 100644 --- a/.github/workflows/docpages.yml +++ b/.github/workflows/docpages.yml @@ -91,6 +91,26 @@ jobs: run: | just build-docs + - name: Check docs internal links + uses: lycheeverse/lychee-action@v2 + with: + args: >- + --config .lychee.toml --no-progress + --root-dir ${{ github.workspace }}/docs/content/docs + --fallback-extensions mdx,md --index-files index.mdx,index.md + 'docs/content/docs/**/*.mdx' docs/README.md README.md + fail: true + + - name: Check built docs links (including external) + uses: lycheeverse/lychee-action@v2 + with: + args: >- + --config .lychee.postbuild.toml --no-progress + --root-dir ${{ github.workspace }}/docs/out + --fallback-extensions html --index-files index.html + 'docs/out/**/*.html' + fail: true + - name: Setup Pages if: ${{ github.ref == 'refs/heads/main' }} uses: actions/configure-pages@v6 diff --git a/.lychee.postbuild.toml b/.lychee.postbuild.toml new file mode 100644 index 00000000..f92f48ff --- /dev/null +++ b/.lychee.postbuild.toml @@ -0,0 +1,11 @@ +# Post-build check over exported HTML with external links enabled. + +# Avoid noisy/generated dependency paths if ever passed as inputs. +exclude_path = ["docs/node_modules/**"] + +# Keep retries bounded while reducing transient external failures. +max_retries = 2 +timeout = 20 + +# Treat common external rate limiting as non-fatal for CI stability. +accept = [200, 429] diff --git a/.lychee.toml b/.lychee.toml new file mode 100644 index 00000000..54d8d304 --- /dev/null +++ b/.lychee.toml @@ -0,0 +1,8 @@ +# Restrict checks to local repository links/anchors. +offline = true + +# Avoid traversing generated and dependency directories if they appear in inputs. +exclude_path = ["docs/out/**", "docs/node_modules/**"] + +# API docs are generated by `just gen-api`; skip this route in source-only checks. +exclude = ["^/api(?:$|/)", "file://.*/docs/content/docs/api(?:$|[#/])"] diff --git a/README.md b/README.md index 66836871..50d34ed5 100644 --- a/README.md +++ b/README.md @@ -115,8 +115,13 @@ executed from the notebooks in `docs/notebooks/`. To build it locally: ```bash just build-docs # output: docs/out/ just serve-docs # live-reloading dev server +just check-doc-links # checks internal docs links/anchors from source MDX +just check-doc-links-built # builds docs and checks exported HTML links (including external URLs) ``` +`just check-doc-links` requires [`lychee`](https://github.com/lycheeverse/lychee) +to be installed locally. + ## Citation If you use `monoprop` in your research, please cite: diff --git a/justfile b/justfile index c376d343..ee6fe32b 100644 --- a/justfile +++ b/justfile @@ -110,6 +110,14 @@ doctest-py: build-docs: docs-install gen-api doctest-py gen-notebooks cd {{ site }} && npm run build +# Check docs for broken internal links and anchors. +check-doc-links: + lychee --config .lychee.toml --root-dir "{{ project_source_dir }}/docs/content/docs" --fallback-extensions mdx,md --index-files index.mdx,index.md 'docs/content/docs/**/*.mdx' docs/README.md README.md + +# Build docs, then check exported HTML links (including external URLs). +check-doc-links-built: build-docs + lychee --config .lychee.postbuild.toml --root-dir "{{ project_source_dir }}/docs/out" --fallback-extensions html --index-files index.html 'docs/out/**/*.html' + # Serve the documentation locally with hot reloading. serve-docs: docs-install gen-api gen-notebooks cd {{ site }} && npm run dev From 7988bc39bb2838b2ad795831ddaf60bbe398ffd8 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Wed, 5 Aug 2026 18:39:10 +0000 Subject: [PATCH 2/2] fix(docs): :bug: fix lychee link checker failures for benchmark images and settings.json - Exclude `/benchmarks/*` paths from lychee (public/ assets served at runtime) - Fix `settings.json` relative link to proper GitHub URL Assisted-by: GitHubCopilotCodingAgent:claude-sonnet-5 Co-authored-by: robertodr <3708689+robertodr@users.noreply.github.com> --- .lychee.toml | 8 +++++++- docs/content/docs/benchmarks.mdx | 2 +- 2 files changed, 8 insertions(+), 2 deletions(-) diff --git a/.lychee.toml b/.lychee.toml index 54d8d304..27ab9bfd 100644 --- a/.lychee.toml +++ b/.lychee.toml @@ -5,4 +5,10 @@ offline = true exclude_path = ["docs/out/**", "docs/node_modules/**"] # API docs are generated by `just gen-api`; skip this route in source-only checks. -exclude = ["^/api(?:$|/)", "file://.*/docs/content/docs/api(?:$|[#/])"] +# /benchmarks/* images live in docs/public/ and are served at runtime; they cannot be resolved as +# local file paths by lychee. +exclude = [ + "^/api(?:$|/)", + "file://.*/docs/content/docs/api(?:$|[#/])", + "^/benchmarks/", +] diff --git a/docs/content/docs/benchmarks.mdx b/docs/content/docs/benchmarks.mdx index 86184e5e..c915e5b0 100644 --- a/docs/content/docs/benchmarks.mdx +++ b/docs/content/docs/benchmarks.mdx @@ -177,7 +177,7 @@ The end-to-end workflow is: #### 1. Choose the simulation settings -All simulation parameters live in [`settings.json`](settings.json) and are shared by every engine +All simulation parameters live in [`settings.json`](https://github.com/Algorithmiq/monoprop/blob/main/benches/third_party/pauli_prop/settings.json) and are shared by every engine (Python and Julia alike), so a single edit compares them all on an identical problem instance: | Key | Meaning |