feat: new page overviewing CI & code coverage

codespell-ignore.txt

@@ -1 +1,2 @@
 aways
+Soler

conf.py

@@ -54,7 +54,7 @@
     "sphinx_sitemap",
     "sphinxext.opengraph",
     "sphinx_favicon",
-    "sphinxcontrib.bibtex"
+    "sphinxcontrib.bibtex",
 ]
 
 # colon fence for card support in md
@@ -103,7 +103,7 @@
         "image_light": "logo-light-mode.png",
         "alt_text": "pyOpenSci Python Package Guide. The pyOpenSci logo is a purple flower with pyOpenSci under it. The o in open sci is the center of the flower",
     },
-    "header_links_before_dropdown": 4,
+    "header_links_before_dropdown": 5,
     "use_edit_page_button": True,
     "show_nav_level": 2,
     "navigation_depth": 3,
@@ -164,6 +164,6 @@
 }
 
 # Bibliographies
-bibtex_bibfiles = ['bibliography.bib']
+bibtex_bibfiles = ["bibliography.bib"]
 # myst complains about bibtex footnotes because of render order
 suppress_warnings = ["myst.footnote"]

continuous-integration/ci.md

@@ -0,0 +1,84 @@
+(ci-cd)=
+# Continuous Integration and Continuous Deployment (CI/CD) For Python Packages
+
+When you develop, work on, and contribute to software, there is more to consider than
+just writing code. Having tests and checks ensures that your code
+runs reliably and follows a consistent format is also important. You can use
+**Continuous Integration (CI)** and **Continuous
+Deployment (CD)** to run tests and checks on your code every time someone suggests a change online
+in a platform like GitHub or GitLab.
+
+- **Continuous Integration (CI):** Automates the process of running tests,
+  code checks, and other workflows each time code is updated.
+- **Continuous Deployment (CD):** Extends CI by allowing you to automate publishing your package to PyPI, publishing your documentation, and more.
+
+CI and CD streamline software development by automating repetitive
+tasks and ensuring code quality and consistency. Having CI setup also makes it easier for new contributors
+to contribute to your code base without setting up all your test suites and
+other local checks.
+
+## What is continuous integration?
+
+When you’re ready to publish your code online, you can set up Continuous Integration (CI). CI is a platform that allows you to specify and run jobs or workflows you define.
+These workflows include:
+
+- Running your test suite
+- Running code checkers / linters / spellcheck
+- Building your documentation
+
+CI allows you to automate running workflows across a suite of environments, including:
+
+- environments containing different Python versions and
+- different operating systems (Mac, Linux, Windows).
+
+## What is Continuous Deployment (CD)?
+
+Continuous deployment (CD) extends the CI process by automating the deployment of code changes to production or staging environments. In the case of your open source tool, CD can be used to:
+
+- Automate publishing to PyPI
+- Automate publishing your documentation to GitHub Pages or Read the Docs.
+
+It is also used once your conda-forge recipe is set up to keep your package up to date on conda-forge.
+
+### Why use CI
+
+CI can be configured to run a workflow on every commit pushed to GitHub and every pull request opened. This ensures that any changes made to your package are tested across environments before merging into the main branch of your code.
+
+These checks are particularly useful if someone new is contributing to your code. Every contributor's change will be tested when pushed to your code repository.
+
+Together, CI and CD streamline the process of building, testing, and deploying code. They aim to improve software development and publication efficiency, quality, and reliability.
+
+```{note}
+All pyOpenSci packages must use some form of continuous integration. Even if you are not planning to go through peer review, we strongly recommend that you use continuous integration, too!
+```
+
+In the case of GitHub actions (which we will focus on here), CI workflows are running on online servers that support GitHub.
+
+## CI / CD platforms
+
+There are numerous platforms available for CI/CD. Here, we will focus on GitHub Actions (GHA), built into GitHub. GitHub is the most commonly used platform to store scientific open-source software.
+
+:::{note}
+If you use [GitLab](https://about.gitlab.com/) CI/CD, many of the principles described here will apply. However, the workflow files may look different.
+:::
+
+### If you aren't sure, use GitHub Actions
+
+While you are welcome to use the continuous integration platform of your choice,
+we recommend GitHub Actions because it is free-to-use and integrated tightly
+into the GitHub user interface. There is also an entire store of GitHub action
+templates that you can easily use and adapt to your own needs.
+
+:::{admonition} Other platforms that you may run into
+:class: info
+
+- [Appveyor:](https://www.appveyor.com/): Supports running tests on Windows operating systems and predated the release of GitHub Actions. Today, AppVeyor supports operating systems beyond Windows.
+- [Travis CI:](https://www.travis-ci.com/) had been a common CI platform choice in our ecosystem. Usage dropped after Travis CI ended free support for open-source projects.
+- [CircleCI:](https://circleci.com/) CircleCI can be useful for automated builds of websites and documentation since it offers a preview of the PR changes.
+  :::
+
+## Embrace automation
+
+By embracing CI/CD, you can ensure that your code runs as you expect it to across the diverse landscapes of user environments. Further, you can
+automate certain checks (and, in some cases, code fixes), including linting and code style. You can even automate spell-checking your documentation
+and docstrings!

continuous-integration/index.md

@@ -0,0 +1,10 @@
+(ci-cd-intro)=
+# Continuous Integration (CI) and Continuous Deployment (CD) for your Python package
+
+
+:::{toctree}
+:caption: Continuous Integration
+
+
+What is CI?  <ci.md>
+:::

index.md

@@ -286,35 +286,46 @@ to see here clarified in this guide, [we invite you to open an issue on GitHub.]
 
 If you have questions about our peer review process or packaging in general, you are welcome to use our [pyOpenSci Discourse forum](https://pyopensci.discourse.group/).
 
-This is a living guide that is updated as tools and best practices evolve in the Python packaging ecosystem. We will be adding new content over the next year.
+This living Python packaging guide is updated as tools and best practices evolve in the Python packaging ecosystem. We will be adding new content over the next year.
 
 
-```{toctree}
+:::{toctree}
 :hidden:
 :caption: Tutorials
+
 Tutorials  <tutorials/intro>
-```
+:::
 
-```{toctree}
+:::{toctree}
 :hidden:
 :caption: Packaging
 
 Packaging <package-structure-code/intro>
 
-```
+:::
 
-```{toctree}
+:::{toctree}
 :hidden:
 :caption: Documentation
 
 Documentation <documentation/index>
 
-```
+:::
+
 
-```{toctree}
+:::{toctree}
 :hidden:
 :caption: Testing
 
 Tests  <tests/index>
 
-```
+:::
+
+
+:::{toctree}
+:hidden:
+:caption: Continuous Integration
+
+CI/CD  <continuous-integration/index>
+
+:::

package-structure-code/intro.md

@@ -178,7 +178,7 @@ if you are looking for pyOpenSci's Python package review requirements!
 
 :::{toctree}
 :hidden:
-:caption: Package structure & code style
+:caption: Create & Build Your Package
 
 Intro <self>
 
@@ -192,7 +192,7 @@ Complex Builds <complex-python-package-builds>
 
 :::{toctree}
 :hidden:
-:caption: Publishing a package
+:caption: Publish your package
 
 Publish with Conda / PyPI <publish-python-package-pypi-conda>
 Package versions <python-package-versions>

tests/code-cov.md

@@ -0,0 +1,66 @@
+# Code coverage for your Python package test suite
+
+Code coverage measures how much of your package's code runs during testing.
+Achieving high coverage can help ensure the reliability of your codebase, but
+it’s not a guarantee of quality. Below, we outline key considerations for
+using code coverage effectively.
+
+## Why aim for high code coverage?
+
+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.
+
+## 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.
+
+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://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.
+
+:::{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.
+
+:::
+
+
+
+:::{admonition} Typing & MyPy coverage
+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.
+
+To generate a coverage report in **Markdown** format, run:
+
+```bash
+$ 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:
+
+```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.
+
+These local reports are an excellent way to quickly review coverage without setting up an external service.

tests/index.md

@@ -80,4 +80,5 @@ Write tests <write-tests>
 Test types <test-types>
 Run tests locally <run-tests>
 Run tests online (using CI) <tests-ci>
+Code coverage <code-cov>
 ```