Enh: align tests section better with our lessons

README.md

@@ -24,7 +24,6 @@ Initiatives.
 
 ## Contributing statement
 
-
 ## How to setup
 
 This repository contains the source files for the [pyOpenSci Python packaging guide](https://pyopensci.org/python-package-guide).
@@ -44,44 +43,49 @@ To build, follow these steps:
 1. Install `nox`
 
    ```console
-   $ python -m pip install nox
+   python -m pip install nox
    ```
+
 2. Build the documentation:
 
    ```console
-   $ nox -s docs
+   nox -s docs
    ```
 
 This should create a local environment in a `.nox` folder, build the documentation (as specified in the `noxfile.py` configuration), and the output will be in `_build/html`.
 
 To build live documentation that updates when you update local files, run the following command:
 
 ```console
-$ nox -s docs-live
+nox -s docs-live
 ```
 
+If you are a uv user, you can also skip installing `nox` and use `uvx` instead:
+
+`uvx nox -s docs-live`
+
 ### Building for release
 
 When building for release, the docs are built multiple times for each translation,
 but translations are only included in the production version of the guide after some completion threshold.
 
 The sphinx build environment is controlled by an environment variable `SPHINX_ENV`
 
-- when `SPHINX_ENV=development` (default), sphinx assumes all languages are built,
+* when `SPHINX_ENV=development` (default), sphinx assumes all languages are built,
   and includes them in the language selector
-- when `SPHINX_ENV=production`, only those languages in `release_languages` (set in `conf.py`)
+* when `SPHINX_ENV=production`, only those languages in `release_languages` (set in `conf.py`)
   are built and included in the language selector.
 
 Most of the time you should not need to set `SPHINX_ENV`,
 as it is forced by the primary nox sessions intended to be used for release or development:
 
 `SPHINX_ENV=development`
-- `docs-live` - autobuild english
-- `docs-live-lang` - autobuild a single language
-- `docs-live-langs` - autobuild all languages
+* `docs-live` - autobuild english
+* `docs-live-lang` - autobuild a single language
+* `docs-live-langs` - autobuild all languages
 
 `SPHINX_ENV=production`
-- `build-test` - build all languages for production
+* `build-test` - build all languages for production
 
 ## Contributing to this guide
 

_static/pyos.css

@@ -340,21 +340,21 @@ See https://github.com/pydata/pydata-sphinx-theme/pull/1784
   src: url("./fonts/poppins-v20-latin-600.woff2") format("woff2"); /* Chrome 36+, Opera 23+, Firefox 39+, Safari 12+, iOS 10+ */
 }
 
-/* nunitosans-regular - latin */
+/* nunitosans-variable - latin */
 @font-face {
   font-display: swap;
   font-family: "NunitoSans";
   font-style: normal;
-  font-weight: 400;
+  font-weight: 200 800;
   src: url("./fonts/NunitoSans-VariableFont.woff2") format("woff2");
 }
 
-/* nunitosans-italic - latin */
+/* nunitosans-italic-variable - latin */
 @font-face {
   font-display: swap;
   font-family: "NunitoSans";
   font-style: italic;
-  font-weight: 400;
+  font-weight: 200 800;
   src: url("./fonts/NunitoSans-Italic-VariableFont.woff2") format("woff2");
 }
 

tests/code-cov.md

@@ -10,31 +10,44 @@ using code coverage effectively.
 A good practice is to ensure that every line of your code runs at least once
 during your test suite. This helps you:
 
-- Identify untested parts of your codebase.
-- Catch bugs that might otherwise go unnoticed.
-- Build confidence in your software's stability.
+- **Identify untested parts:** Parts of your codebase that are not
+  covered by tests.
+- **Catch bugs:** Bugs that might otherwise go unnoticed.
+- **Build confidence:** Confidence in your software's stability.
 
 ## Limitations of code coverage
 
 While high code coverage is valuable, it has its limits:
 
-- **Difficult-to-test code:** Some parts of your code might be challenging to
-  test, either due to complexity or limited resources.
-- **Missed edge cases:** Running all lines of code doesn’t guarantee that edge
-  cases are handled correctly.
+- **Difficult-to-test code:** Some parts of your code might be
+  challenging to test, either due to complexity or limited resources.
+- **Missed edge cases:** Running all lines of code doesn't guarantee
+  that edge cases are handled correctly.
 
 Ultimately, you should focus on how your package will be used and ensure your
 tests cover those scenarios adequately.
 
 ## Tools for analyzing Python package code coverage
 
-Some common services for analyzing code coverage are [codecov.io](https://about.codecov.io/) and [coveralls.io](https://coveralls.io/). These projects are free for open source tools and will provide dashboards that tell you how much of your codebase is covered during your tests. We recommend setting up an account (on either CodeCov or Coveralls) and using it to keep track of your code coverage.
+Some common services for analyzing code coverage are
+[codecov.io](https://about.codecov.io/) and [coveralls.io](https://coveralls.io/).
+These projects are free for open source tools and provide dashboards that
+show how much of your codebase is covered during your tests. We recommend
+setting up an account (on either CodeCov or Coveralls) and using it to
+keep track of your code coverage.
 
 :::{figure} ../images/code-cov-stravalib.png
 :height: 450px
 :alt: Screenshot of the code cov service - showing test coverage for the stravalib package. This image shows a list of package modules and the associated number of lines and % lines covered by tests. At the top of the image, you can see what branch is being evaluated and the path to the repository.
 
-The CodeCov platform is a useful tool if you wish to track code coverage visually. Using it, you can not only get the same summary information that you can get with the **pytest-cov** extension. You can also see what lines are covered by your tests and which are not. Code coverage is useful for evaluating unit tests and/or how much of your package code is "covered". It, however, will not evaluate things like integration tests and end-to-end workflows.
+The CodeCov platform is a useful tool if you wish to track code coverage
+visually. Using it, you can get the same summary information that you can get
+with the **pytest-cov** extension. You can also see what lines are covered by
+your tests and which are not. Code coverage is useful for evaluating
+[unit tests](test-types.md#unit-tests) and/or how much of your package code
+is "covered". It, however, will not evaluate things like
+[integration tests](test-types.md#integration-tests) and
+[end-to-end workflows](test-types.md).
 
 :::
 
@@ -46,21 +59,37 @@ You can also create and upload typing reports to CodeCov.
 
 ## Exporting Local Coverage Reports
 
-In addition to using services like CodeCov or Coveralls, you can generate local coverage reports directly using the **coverage.py** tool. This can be especially useful if you want to create reports in Markdown or HTML format for offline use or documentation.
+In addition to using services like CodeCov or Coveralls, you can generate
+local coverage reports directly using the **coverage.py** tool. This can be
+especially useful if you want to create reports in Markdown or HTML format for
+offline use or documentation.
 
 To generate a coverage report in **Markdown** format, run:
 
 ```bash
-$ python -m coverage report --format=markdown
+python -m coverage report --format=markdown
 ```
-This command will produce a Markdown-formatted coverage summary that you can easily include in project documentation or share with your team.
 
-To generate an HTML report that provides a detailed, interactive view of which lines are covered, use:
+This command will produce a Markdown-formatted coverage summary that you can
+include in project documentation or share with your team.
+
+To generate an HTML report that provides a detailed, interactive view of which
+lines are covered, use:
 
 ```bash
 python -m coverage html
 ```
 
-The generated HTML report will be saved in a directory named htmlcov by default. Open the index.html file in your browser to explore your coverage results.
+The generated HTML report will be saved in a directory named `htmlcov` by
+default. Open the `index.html` file in your browser to explore your coverage
+results.
+
+These local reports are an excellent way to quickly review coverage without
+setting up an external service.
+
+## Next steps
 
-These local reports are an excellent way to quickly review coverage without setting up an external service.
+Writing meaningful tests is the foundation of useful coverage.
+See [Write tests](write-tests.md) and [Test types](test-types.md)
+to learn more about developing better test suites. Learn how to run your tests both
+[locally](run-tests.md) and in [continuous integration](tests-ci.md).

tests/index.md

@@ -9,7 +9,6 @@ In this section, you will learn more about the importance of writing
 tests for your Python package and how you can set up infrastructure
 to run your tests both locally and on GitHub.
 
-
 :::::{grid} 1 1 3 2
 :class-container: text-center
 :gutter: 3
@@ -20,9 +19,8 @@ to run your tests both locally and on GitHub.
 :link-type: doc
 :class-card: left-aligned
 
-Learn more about the art of writing tests for your Python package.
-Learn about why you should write tests and how they can help you and
-potential contributors to your project.
+Learn about the importance of writing tests for your Python
+package and how they help you and potential contributors.
 :::
 ::::
 
@@ -32,8 +30,8 @@ potential contributors to your project.
 :link-type: doc
 :class-card: left-aligned
 
-There are three general types of tests that you can write for your Python
-package: unit tests, integration tests and end-to-end (or functional) tests. Learn about all three.
+Get to know the three test types: unit, integration, and
+end-to-end tests. Learn when and how to use each.
 :::
 ::::
 
@@ -43,8 +41,8 @@ package: unit tests, integration tests and end-to-end (or functional) tests. Lea
 :link-type: doc
 :class-card: left-aligned
 
-If you expect your users to use your package across different versions
-of Python, then using an automation tool such as nox to run your tests is useful. Learn about the various tools that you can use to run your tests across python versions here.
+Learn about testing frameworks like pytest and taskrunners/automation tools like nox, and tox that can be used to run
+tests across different Python versions on your computer.
 :::
 ::::
 
@@ -54,21 +52,23 @@ of Python, then using an automation tool such as nox to run your tests is useful
 :link-type: doc
 :class-card: left-aligned
 
-Continuous integration platforms such as GitHub Actions can be
-useful for running your tests across both different Python versions
-and different operating systems. Learn about setting up tests to run in Continuous Integration here.
+Set up continuous integration with GitHub Actions to run
+tests across Python versions and operating systems.
 :::
 ::::
 
-:::::
-
-
-:::{figure-md} fig-target
-
-<img src="../images/packaging-lifecycle.png" alt="" width="800px">
+::::{grid-item}
+:::{card} ✨ Code coverage ✨
+:link: code-cov
+:link-type: doc
+:class-card: left-aligned
 
-Graphic showing the elements of the packaging process.
+Measure how much of your package code runs during tests.
+Learn to generate local reports and visualize coverage online.
 :::
+::::
+
+:::::
 
 ```{toctree}
 :hidden:
@@ -79,6 +79,7 @@ Intro <self>
 Write tests <write-tests>
 Test types <test-types>
 Run tests locally <run-tests>
+Run tests with Nox <run-tests-nox>
 Run tests online (using CI) <tests-ci>
 Code coverage <code-cov>
 ```