From 0cca1beeb1f887f38731f3ecc5280af0cfb4140b Mon Sep 17 00:00:00 2001 From: Henry Schreiner Date: Sat, 18 Jul 2026 14:16:35 -0400 Subject: [PATCH] docs: use resolvable root-absolute links for internal pages Internal doc links were written as bare root-relative paths (e.g. `guides/pytest`, `guides/packaging-simple`). MyST could not resolve many of these as cross-references: paths are resolved relative to the source file, and the multi-word ones used hyphens where the source files use underscores (`packaging_simple.md`). Unresolved links fell back to raw `BASE_URL` concatenation, which only produced valid URLs when `BASE_URL` ended in a slash. Rewrite them as root-absolute paths with the `.md` extension (`/guides/packaging_simple.md`) so MyST resolves them as real cross-references and emits correct URLs regardless of the `BASE_URL` trailing slash. Assisted-by: ClaudeCode:claude-opus-4.8 Signed-off-by: Henry Schreiner --- docs/guides/gha_pure.md | 2 +- docs/guides/index.md | 28 ++++++++++++++-------------- docs/guides/mypy.md | 2 +- docs/guides/packaging_classic.md | 2 +- docs/guides/packaging_compiled.md | 4 ++-- docs/guides/style.md | 2 +- docs/index.md | 24 ++++++++++++------------ docs/patterns/index.md | 6 +++--- docs/principles/index.md | 4 ++-- docs/principles/testing.md | 6 +++--- docs/tutorials/docs.md | 4 ++-- docs/tutorials/index.md | 4 ++-- docs/tutorials/module.md | 2 +- docs/tutorials/packaging.md | 2 +- docs/tutorials/test.md | 2 +- 15 files changed, 47 insertions(+), 47 deletions(-) diff --git a/docs/guides/gha_pure.md b/docs/guides/gha_pure.md index 87f0991d..5bca40cb 100644 --- a/docs/guides/gha_pure.md +++ b/docs/guides/gha_pure.md @@ -26,7 +26,7 @@ reasons that a wheel is better than only providing an sdist: is going to go ::: -[on the next page]: guides/gha-wheels +[on the next page]: /guides/gha_wheels.md ## Job setup diff --git a/docs/guides/index.md b/docs/guides/index.md index f49187ec..e3a78dcd 100644 --- a/docs/guides/index.md +++ b/docs/guides/index.md @@ -35,20 +35,20 @@ your repository with the guidelines, runnable [right in the guide][] via WebAssembly! All checks point to a linked badge in the guide. ::: -[tutorials]: tutorials/index -[style]: guides/style -[mypy]: guides/mypy -[docs]: guides/docs -[simple packaging]: guides/packaging-simple -[compiled packaging]: guides/packaging-compiled -[classic packaging]: guides/packaging-classic -[coverage]: guides/coverage -[gha_basic]: guides/gha-basic -[gha_pure]: guides/gha-pure -[gha_wheels]: guides/gha-wheels -[security]: guides/security -[pytest]: guides/pytest -[right in the guide]: guides/repo-review +[tutorials]: /tutorials/index.md +[style]: /guides/style.md +[mypy]: /guides/mypy.md +[docs]: /guides/docs.md +[simple packaging]: /guides/packaging_simple.md +[compiled packaging]: /guides/packaging_compiled.md +[classic packaging]: /guides/packaging_classic.md +[coverage]: /guides/coverage.md +[gha_basic]: /guides/gha_basic.md +[gha_pure]: /guides/gha_pure.md +[gha_wheels]: /guides/gha_wheels.md +[security]: /guides/security.md +[pytest]: /guides/pytest.md +[right in the guide]: /guides/repo_review.md [cookiecutter]: https://cookiecutter.readthedocs.io [copier]: https://copier.readthedocs.io diff --git a/docs/guides/mypy.md b/docs/guides/mypy.md index 2a311874..46bafcd5 100644 --- a/docs/guides/mypy.md +++ b/docs/guides/mypy.md @@ -70,7 +70,7 @@ everything. Try to turn on as much as possible, and increase it until you can run with full `strict` checking. See the [style page][] for configuration suggestions. -[style page]: guides/style +[style page]: /guides/style.md For a library to support typing, it has to a) add types using any of the three methods, and b) add a `py.typed` empty file to indicate that it's okay to look diff --git a/docs/guides/packaging_classic.md b/docs/guides/packaging_classic.md index 79813990..4557c3f0 100644 --- a/docs/guides/packaging_classic.md +++ b/docs/guides/packaging_classic.md @@ -8,7 +8,7 @@ outlined as well. There are several popular packaging systems. This guide covers the old configuration style for [Setuptools][]. Unless you really need it, you should be using the modern style described in [Simple -Packaging](guides/packaging-simple). The modern style is +Packaging](/guides/packaging_simple.md). The modern style is guided by Python Enhancement Proposals (PEPs), and is more stable than the setuptools-specific mechanisms that evolve over the years. This page is kept to help users with legacy code (and hopefully upgrade it). diff --git a/docs/guides/packaging_compiled.md b/docs/guides/packaging_compiled.md index c33deae2..c25a6f65 100644 --- a/docs/guides/packaging_compiled.md +++ b/docs/guides/packaging_compiled.md @@ -40,7 +40,7 @@ The most exciting developments have been new native build backends: :::{note} You should be familiar with [packing a pure Python -project](guides/packaging-simple) - the metadata +project](/guides/packaging_simple.md) - the metadata configuration is the same. ::: There are also classic setuptools plugins: @@ -453,4 +453,4 @@ it is free-threaded. 3.13.5 was rushed out to fix it. [meson-python]: https://meson-python.readthedocs.io [setuptools-rust]: https://setuptools-rust.readthedocs.io/en/latest/ [maturin]: https://www.maturin.rs -[gha_wheels]: guides/gha-wheels +[gha_wheels]: /guides/gha_wheels.md diff --git a/docs/guides/style.md b/docs/guides/style.md index e6ea3381..22483994 100644 --- a/docs/guides/style.md +++ b/docs/guides/style.md @@ -786,7 +786,7 @@ for a specific rule); the standard `# type: ignore` is honored as well. ::: :::: -[mypy page]: guides/mypy +[mypy page]: /guides/mypy.md ## Setuptools specific checks diff --git a/docs/index.md b/docs/index.md index 0e01eb3d..0e159215 100644 --- a/docs/index.md +++ b/docs/index.md @@ -13,10 +13,10 @@ fellow scientists and research software engineers. Jupyter notebooks that are becoming unwieldy? Are changes to some parts of your code accidentally breaking other parts of your code? Do you want to present them in a more maintainable, reusable, and shareable form? Start at the -[tutorial](tutorials/index). +[tutorial](/tutorials/index.md). **Learn recommended tools and best practices.** -[Topical guides](guides/index) provide task-based instruction on topics +[Topical guides](/guides/index.md) provide task-based instruction on topics that scientists and research software engineers may encounter as their projects evolve and grow. This covers modern packaging ([simple][] or [compiled][]), [style checking][], [testing][], [documentation][], [static typing][], [CI][], @@ -35,12 +35,12 @@ WebAssembly! All checks point to a linked badge in the guide. ::: **Learn to write better research code.** A high-level document on -[principles](principles/index) provides advice based on the +[principles](/principles/index.md) provides advice based on the community's collective experience building code that is easier for researchers to use successfully and easier to maintain over time. **Use our solutions for common tasks.** A growing collection of -[patterns](patterns/index) provides tested approaches for +[patterns](/patterns/index.md) provides tested approaches for tasks and can be tricky to get exactly right, such as including data files with Python packages. @@ -75,14 +75,14 @@ with many updates. Improved support for compiled components supported in part by NSF grant [OAC-2209877][]. ::: -[simple]: guides/packaging-simple -[compiled]: guides/packaging-compiled -[style checking]: guides/style -[testing]: guides/pytest -[documentation]: guides/docs -[static typing]: guides/mypy -[ci]: guides/gha-pure -[right in the guide]: guides/repo-review +[simple]: /guides/packaging_simple.md +[compiled]: /guides/packaging_compiled.md +[style checking]: /guides/style.md +[testing]: /guides/pytest.md +[documentation]: /guides/docs.md +[static typing]: /guides/mypy.md +[ci]: /guides/gha_pure.md +[right in the guide]: /guides/repo_review.md [scientific-python/cookie]: https://github.com/scientific-python/cookie [repo-review]: https://repo-review.readthedocs.io diff --git a/docs/patterns/index.md b/docs/patterns/index.md index c6309309..88858dc3 100644 --- a/docs/patterns/index.md +++ b/docs/patterns/index.md @@ -10,9 +10,9 @@ If you would like to use backport packages, see [Backports][]. If you are wondering about public API, see [Exports][]. -[including data files]: patterns/data-files -[backports]: patterns/backports -[exports]: patterns/exports +[including data files]: /patterns/data_files.md +[backports]: /patterns/backports.md +[exports]: /patterns/exports.md ```{tableofcontents} ``` diff --git a/docs/principles/index.md b/docs/principles/index.md index 2406bf6e..d68e419a 100644 --- a/docs/principles/index.md +++ b/docs/principles/index.md @@ -5,8 +5,8 @@ research code. [Process recommendations][] discusses the process of writing software, and [Design recommendations][] covers some tips about writing easy to read and maintain code. -[Process recommendations]: principles/process -[Design recommendations]: principles/design +[Process recommendations]: /principles/process.md +[Design recommendations]: /principles/design.md ```{tableofcontents} diff --git a/docs/principles/testing.md b/docs/principles/testing.md index 946de96f..f44dcd5f 100644 --- a/docs/principles/testing.md +++ b/docs/principles/testing.md @@ -69,8 +69,8 @@ the test-case to make sure it fails when the code is broken. A good place to start writing tests is from the perspective of a user of your module or library, as described in the [Test -Tutorial](tutorials/test), and [Testing with pytest -guide](guides/pytest). These tests follow the "Detroit +Tutorial](/tutorials/test.md), and [Testing with pytest +guide](/guides/pytest.md). These tests follow the "Detroit School", focusing on behavior, avoiding testing of private attributes, minimizing the use of mocks/patches/test-doubles. @@ -393,7 +393,7 @@ run unit tests in your source folder, from your package root, use your source repository), use `pytest --pyargs {package name}`. You can set the default test path in `pyproject.toml`, see: [Configuring -pytest](guides/pytest#configuring-pytest) +pytest](/guides/pytest.md#configuring-pytest) We recommend configuring pytest to run ONLY your fastest, least demanding test suite by default. diff --git a/docs/tutorials/docs.md b/docs/tutorials/docs.md index 99ce1e99..e519e5d0 100644 --- a/docs/tutorials/docs.md +++ b/docs/tutorials/docs.md @@ -195,7 +195,7 @@ Or you can generate a table that links out to documentation for each object. ```` -See the [guide](guides/docs) for more information on how to +See the [guide](/guides/docs.md) for more information on how to integrate this into a package, and setup for nox. [sphinx]: https://www.sphinx-doc.org/ @@ -204,4 +204,4 @@ integrate this into a package, and setup for nox. [sphinx-autodoc2]: https://sphinx-autodoc2.readthedocs.io/ [mkdocs]: https://www.mkdocs.org/ [mkdocs-material]: https://squidfunk.github.io/mkdocs-material/ -[documentation guide]: guides/docs +[documentation guide]: /guides/docs.md diff --git a/docs/tutorials/index.md b/docs/tutorials/index.md index 26fd10c8..77ca2231 100644 --- a/docs/tutorials/index.md +++ b/docs/tutorials/index.md @@ -12,9 +12,9 @@ start off on the right foot. Keeping in mind that too much software infrastructure can be overwhelming to those who haven't yet encountered the need for it, we introduce only the core essentials in this opinionated tutorial. From there, we recommend looking -through the section on [principles](principles/index). As +through the section on [principles](/principles/index.md). As your project grows you may find some good use for the more specific and advanced -topics covered in the [guides](guides/index). +topics covered in the [guides](/guides/index.md). ```{tableofcontents} ``` diff --git a/docs/tutorials/module.md b/docs/tutorials/module.md index ac0d4d26..846b5430 100644 --- a/docs/tutorials/module.md +++ b/docs/tutorials/module.md @@ -79,7 +79,7 @@ automatically generate nice-looking HTML documentation later. Notable features: - (Optional) There is a section of one or more examples. We will revisit docstrings in the section on writing -[documentation](tutorials/docs). +[documentation](/tutorials/docs.md). [snell's law]: https://en.wikipedia.org/wiki/Snell%27s_law [numpydoc standard]: https://numpydoc.readthedocs.io/en/latest/format.html diff --git a/docs/tutorials/packaging.md b/docs/tutorials/packaging.md index 4aeab750..4975be91 100644 --- a/docs/tutorials/packaging.md +++ b/docs/tutorials/packaging.md @@ -125,4 +125,4 @@ In [1]: snell? For more about packaging, also see our [packaging guide][]. [version control with git]: https://swcarpentry.github.io/git-novice/ -[packaging guide]: guides/packaging-simple +[packaging guide]: /guides/packaging_simple.md diff --git a/docs/tutorials/test.md b/docs/tutorials/test.md index 212d636a..8a929db9 100644 --- a/docs/tutorials/test.md +++ b/docs/tutorials/test.md @@ -139,4 +139,4 @@ Consult the [pytest documentation][] for more. For more advanced pytest suggestions, see our [pytest guide][]. [pytest documentation]: https://docs.pytest.org/en/latest/ -[pytest guide]: guides/pytest +[pytest guide]: /guides/pytest.md