feat: cross-link checks with guide

Signed-off-by: Henry Schreiner <henryschreineriii@gmail.com>

Author: henryiii

.pre-commit-config.yaml

@@ -32,6 +32,7 @@ repos:
       - id: check-yaml
       - id: debug-statements
       - id: end-of-file-fixer
+        exclude: ^docs/_includes/rr.html$
       - id: mixed-line-ending
       - id: name-tests-test
         args: ["--pytest-test-first"]
@@ -66,7 +67,7 @@ repos:
       - id: prettier
         types_or: [yaml, markdown, html, css, scss, javascript, json]
         args: [--prose-wrap=always]
-        exclude: ^.readthedocs.yml
+        exclude: ^docs/_includes/rr.html$
 
   - repo: https://github.com/codespell-project/codespell
     rev: "v2.2.4"

docs/_includes/rr.html

@@ -0,0 +1 @@
+<span class="rr-btn" id="{{ include.id }}">{{ include.id }}</span>

docs/_sass/custom/custom.scss

@@ -131,3 +131,21 @@ blockquote > h2 {
   font-weight: 300;
   letter-spacing: 2px;
 }
+
+.rr-btn {
+  border-radius: 4px;
+  background-color: #808080;
+  color: white;
+  padding: 1px 4px;
+  font-size: 9pt;
+  font-family: sans-serif;
+  display: inline-block;
+  text-align: center;
+  line-height: 1;
+}
+.rr-btn::before {
+  content: "sp-repo-review";
+  font-size: 5pt;
+  display: block;
+  text-align: center;
+}

docs/pages/guides/gha_basic.md

@@ -9,12 +9,12 @@ custom_title: GitHub Actions introduction
 
 {% include toc.html %}
 
-The recommended CI for scientific Python projects is GitHub Actions (GHA),
-although its predecessor Azure is also in heavy usage, and other popular
-services (Travis, Appveyor, and Circle CI) may be found in a few packages. GHA
-is preferred due to the flexible, extensible design and the tight integration
-with the GitHub permissions model (and UI). Here is a guide in setting up a new
-package with GHA.
+{% include rr.html id="GH100" %} The recommended CI for scientific Python
+projects is GitHub Actions (GHA), although its predecessor Azure is also in
+heavy usage, and other popular services (Travis, Appveyor, and Circle CI) may be
+found in a few packages. GHA is preferred due to the flexible, extensible design
+and the tight integration with the GitHub permissions model (and UI). Here is a
+guide in setting up a new package with GHA.
 
 GHA is made up of workflows which consist of actions. Here are some of the
 workflows you will probably want in your package. These should be in a file
@@ -36,11 +36,11 @@ on:
 jobs:
 ```
 
-This gives the workflow a nice name, and defines the conditions under which it
-runs. This will run on all pull requests, or pushes to main. If you use a
-develop branch, you probably will want to include that. You can also specify
-specific branches for pull requests instead of running on all PRs (will run on
-PRs targeting those branches only).
+This gives the workflow a nice name {% include rr.html id="GH101" %}, and
+defines the conditions under which it runs. This will run on all pull requests,
+or pushes to main. If you use a develop branch, you probably will want to
+include that. You can also specify specific branches for pull requests instead
+of running on all PRs (will run on PRs targeting those branches only).
 
 ## Pre-commit
 
@@ -124,9 +124,10 @@ you were building a final package.
 
 ## Updating
 
-If you use non-default actions in your repository (you will see some in the
-following pages), then it's a good idea to keep them up to date. GitHub provided
-a way to do this with dependabot. Just add the following file as
+{% include rr.html id="GH200" %} {% include rr.html id="GH210" %} If you use
+non-default actions in your repository (you will see some in the following
+pages), then it's a good idea to keep them up to date. GitHub provided a way to
+do this with dependabot. Just add the following file as
 `.github/dependabot.yml`:
 
 ```yaml
@@ -143,7 +144,8 @@ This will check to see if there are updates to the action weekly, and will make
 a PR if there are updates, including the changelog and commit summary in the PR.
 If you select a name like `v1`, this should only look for updates of the same
 form (since April 2022) - there is no need to restrict updates for "moving tag"
-updates anymore. You can also use SHA's and dependabot will respect that too.
+updates anymore {% include rr.html id="PY006" %}. You can also use SHA's and
+dependabot will respect that too.
 
 You can use this for other ecosystems too, including Python.
 
@@ -253,7 +255,8 @@ permissions:
   id-token: write
 ```
 
-You probably only want one deployment at a time, so you can use:
+{% include rr.html id="GH103" %} You probably only want one deployment at a
+time, so you can use:
 
 ```yaml
 concurrency:
@@ -325,8 +328,9 @@ These are some things you might need.
 
 ### Cancel existing runs
 
-If you add the following, you can ensure only one run per PR/branch happens at a
-time, cancelling the old run when a new one starts:
+{% include rr.html id="GH102" %} If you add the following, you can ensure only
+one run per PR/branch happens at a time, cancelling the old run when a new one
+starts:
 
 {% raw %}
 

docs/pages/guides/nox.md

@@ -32,10 +32,10 @@ is _much_ faster than explaining how to get setup or manually messing with
 virtual environments. It is also highly reproducible, creating and destroying
 the temporary environment each time.
 
-You _should_ use nox to make it easy and simple for new contributors to run
-things. You _should_ use nox to make specialized developer tasks easy. You
-_should_ use nox to avoid making single-use virtual environments for docs and
-other rarely run tasks.
+{% include rr.html id="PY007" %} You _should_ use nox to make it easy and simple
+for new contributors to run things. You _should_ use nox to make specialized
+developer tasks easy. You _should_ use nox to avoid making single-use virtual
+environments for docs and other rarely run tasks.
 
 Nox doesn't handle binary builds very well, so for compiled projects, it might
 be best left to just specialized tasks.

docs/pages/guides/packaging_classic.md

@@ -87,6 +87,9 @@ generally not found in scientific Python packages, but not discouraged; all
 tools build the same wheels (and they often build setuptools compliant SDists,
 as well).
 
+{% include rr.html id="PP003" %} Note that `"wheel"` is never required; it is
+injected automatically by setuptools only when needed.
+
 ### Special additions: NumPy
 
 You may want to build against NumPy (mostly for Cython packages, pybind11 does

docs/pages/guides/packaging_simple.md

@@ -38,7 +38,8 @@ is coming.
 
 ## pyproject.toml: build-system
 
-Packages must have a `pyproject.toml` file that selects the backend:
+{% include rr.html id="PY001" %} Packages must have a `pyproject.toml` file
+{% include rr.html id="PP001" %} that selects the backend:
 
 <div class="skhep-bar d-flex m-2" style="justify-content:center;">
   <button class="skhep-bar-item hatch-btn btn m-2 btn-purple" onclick="openTab('hatch')">Hatchling</button>
@@ -141,6 +142,11 @@ detection, while Trampolim and whey do not, requiring a `tool` setting.
 If you don't match your package name and import name (which you should except
 for very special cases), you will likely need extra configuration here.
 
+You should have a `README` {% include rr.html id="PY002" %} and a `LICENSE` {%
+include rr.html id="PY003" %} file. You should have a `docs/` folder {% include
+rr.html id="PY003" %}. You should have a `/tests` folder (recommended) and/or a
+`src/<package>/tests` folder.
+
 ## Versioning
 
 You can specify the version manually (as shown in the example), but the backends

docs/pages/guides/pytest.md

@@ -62,9 +62,9 @@ This looks simple, but it is doing several things:
 ### Configuring pytest
 
 pytest supports configuration in `pytest.ini`, `setup.cfg`, or, since version 6,
-`pyproject.toml`. If you can require pytest 6 (in other words, if Python 3.6+ is
-fine - pytest is a developer requirement, not a user one, so limiting it is
-fine), then use `pyproject.toml`. This is an example configuration:
+`pyproject.toml` {% include rr.html id="PP301" %}. Remember, pytest is a
+developer requirement, not a user one, so always require 6+ (or 7+) and use
+`pyproject.toml`. This is an example configuration:
 
 ```toml
 [tool.pytest.ini_options]
@@ -79,21 +79,25 @@ testpaths = [
 ]
 ```
 
-The `minversion` will print a nicer error if your `pytest` is too old (though,
-ironically, it won't read this is the version is too old, so setting "6" or less
-in `pyproject.toml` is rather pointless). The `addopts` setting will add
-whatever you put there to the command line when you run; `-ra` will print a
-summary "r"eport of "a"ll results, which gives you a quick way to review what
-tests failed and were skipped, and why. `--showlocals` will print locals in
-tracebacks. `--strict-markers` will make sure you don't try to use an
-unspecified fixture. And `--strict-config` will error if you make a mistake in
-your config. `xfail_strict` will change the default for `xfail` to fail the
-tests if it doesn't fail - you can still override locally in a specific xfail
-for a flaky failure. `filter_warnings` will cause all warnings to be errors (you
-can add allowed warnings here too, see below). `log_cli_level` will report
-`INFO` and above log messages on a failure. Finally, `testpaths` will limit
-`pytest` to just looking in the folders given - useful if it tries to pick up
-things that are not tests from other directories.
+{% include rr.html id="PP302" %} The `minversion` will print a nicer error if
+your `pytest` is too old (though, ironically, it won't read this is the version
+is too old, so setting "6" or less in `pyproject.toml` is rather pointless). The
+`addopts` setting will add whatever you put there to the command line when you
+run; {% include rr.html id="PP308" %} `-ra` will print a summary "r"eport of
+"a"ll results, which gives you a quick way to review what tests failed and were
+skipped, and why. `--showlocals` will print locals in tracebacks.
+{% include rr.html id="PP307" %} `--strict-markers` will make sure you don't try
+to use an unspecified fixture. {% include rr.html id="PP306" %} And
+`--strict-config` will error if you make a mistake in your config.
+{% include rr.html id="PP305" %} `xfail_strict` will change the default for
+`xfail` to fail the tests if it doesn't fail - you can still override locally in
+a specific xfail for a flaky failure. {% include rr.html id="PP309" %}
+`filter_warnings` will cause all warnings to be errors (you can add allowed
+warnings here too, see below). {% include rr.html id="PP304" %} `log_cli_level`
+will report `INFO` and above log messages on a failure.
+{% include rr.html id="PP303" %} Finally, `testpaths` will limit `pytest` to
+just looking in the folders given - useful if it tries to pick up things that
+are not tests from other directories.
 [See the docs](https://docs.pytest.org/en/stable/customize.html) for more
 options.
 

docs/pages/guides/repo_review.md

@@ -5,7 +5,6 @@ permalink: /guides/repo-review/
 nav_order: 110
 parent: Topical Guides
 interactive_repo_review: true
-custom_title: Scikit-HEP Repo Review (beta)
 ---
 
 You can check the style of a GitHub repository below. Enter any repository, such
@@ -16,14 +15,15 @@ check was skipped because a previous required check failed. Some checks will
 fail, that's okay - the goal is bring all possible issues to your attention, not
 to force compliance with arbitrary checks.
 
-You can also run [this tool](https://github.com/scikit-hep/repo-review) locally:
+You can also run [this tool](https://github.com/scientific-python/repo-review)
+locally:
 
 ```bash
-pipx run 'scikit-hep-repo-review[cli]' <path to repo>
+pipx run 'sp-repo-review[cli]' <path to repo>
 ```
 
 ---
 
 {% include interactive_repo_review.html %}
 
-[Open in new page](https://scikit-hep.github.io/repo-review/).
+[Open in new page](https://scientific-python.github.io/repo-review/).