merge main

.all-contributorsrc

@@ -472,6 +472,16 @@
         "review",
         "tutorial"
       ]
+    },
+    {
+      "login": "ctb",
+      "name": "C. Titus Brown",
+      "avatar_url": "https://avatars.githubusercontent.com/u/51016?v=4",
+      "profile": "http://ivory.idyll.org/blog/",
+      "contributions": [
+        "code",
+        "review"
+      ]
     }
   ],
   "contributorsPerLine": 7,

.github/workflows/build-book.yml

@@ -42,7 +42,7 @@ jobs:
       run: python3 -m pip install nox
 
     - name: Build book
-      run: nox -s docs
+      run: nox -s docs-test
 
     # Save html as artifact
     - name: Save book html as artifact for viewing

CONTRIBUTING.md

@@ -1,3 +1,6 @@
+---
+orphan: true
+---
 # Contributing Guide for the Python open source software packaging book
 
 This is a community resource. We welcome contributions in the form of issues and/or pull requests to this guide.

README.md

@@ -1,6 +1,6 @@
 # <img src="https://www.pyopensci.org/images/logo.png" width=100 /> pyOpenSci scientific Python Packaging Guide
 <!-- ALL-CONTRIBUTORS-BADGE:START - Do not remove or modify this section -->
-[![All Contributors](https://img.shields.io/badge/all_contributors-45-orange.svg?style=flat-square)](#contributors-)
+[![All Contributors](https://img.shields.io/badge/all_contributors-46-orange.svg?style=flat-square)](#contributors-)
 <!-- ALL-CONTRIBUTORS-BADGE:END -->
 
 ![GitHub release (latest by date)](https://img.shields.io/github/v/release/pyopensci/python-package-guide?color=purple&display_name=tag&style=plastic)
@@ -132,6 +132,7 @@ Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/d
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/h-vetinari"><img src="https://avatars.githubusercontent.com/u/33685575?v=4?s=100" width="100px;" alt="h-vetinari"/><br /><sub><b>h-vetinari</b></sub></a><br /><a href="https://github.com/pyOpenSci/python-package-guide/commits?author=h-vetinari" title="Code">💻</a> <a href="https://github.com/pyOpenSci/python-package-guide/pulls?q=is%3Apr+reviewed-by%3Ah-vetinari" title="Reviewed Pull Requests">👀</a> <a href="#tutorial-h-vetinari" title="Tutorials">✅</a></td>
       <td align="center" valign="top" width="14.28%"><a href="https://xmnlab.github.io"><img src="https://avatars.githubusercontent.com/u/5209757?v=4?s=100" width="100px;" alt="Ivan Ogasawara"/><br /><sub><b>Ivan Ogasawara</b></sub></a><br /><a href="https://github.com/pyOpenSci/python-package-guide/commits?author=xmnlab" title="Code">💻</a> <a href="https://github.com/pyOpenSci/python-package-guide/pulls?q=is%3Apr+reviewed-by%3Axmnlab" title="Reviewed Pull Requests">👀</a> <a href="#tutorial-xmnlab" title="Tutorials">✅</a></td>
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/tomalrussell"><img src="https://avatars.githubusercontent.com/u/2762769?v=4?s=100" width="100px;" alt="Tom Russell"/><br /><sub><b>Tom Russell</b></sub></a><br /><a href="https://github.com/pyOpenSci/python-package-guide/commits?author=tomalrussell" title="Code">💻</a> <a href="https://github.com/pyOpenSci/python-package-guide/pulls?q=is%3Apr+reviewed-by%3Atomalrussell" title="Reviewed Pull Requests">👀</a> <a href="#tutorial-tomalrussell" title="Tutorials">✅</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="http://ivory.idyll.org/blog/"><img src="https://avatars.githubusercontent.com/u/51016?v=4?s=100" width="100px;" alt="C. Titus Brown"/><br /><sub><b>C. Titus Brown</b></sub></a><br /><a href="https://github.com/pyOpenSci/python-package-guide/commits?author=ctb" title="Code">💻</a> <a href="https://github.com/pyOpenSci/python-package-guide/pulls?q=is%3Apr+reviewed-by%3Actb" title="Reviewed Pull Requests">👀</a></td>
     </tr>
   </tbody>
 </table>

_static/pyos.css

@@ -69,7 +69,7 @@ h1 {
     color: var(--pyos-h1-color);
 }
 h2 {
-    margin-top: 80px;
+    margin-top: 1em;
 }
 
 h3 {

conf.py

@@ -62,6 +62,7 @@
     "attrs_block",
 ]
 myst_heading_anchors = 3
+myst_footnote_transition = False
 
 # Sphinx_favicon is used now in favor of built in support
 # https://pypi.org/project/sphinx-favicon/

index.md

@@ -56,10 +56,9 @@ Community docs
 
 Publish your docs
 ```
-## _new_ Tutorial Series: How to Create a Python Package
+## _new_ Tutorial Series: Create a Python Package
 
-The how to create a Python package tutorial series is being developed
-by the community now! Join our community review process or watch development of these tutorials in our [Github repo here](https://github.com/pyOpenSci/python-package-guide).
+The first round of our community-developed, how to create a Python package tutorial series for scientists is complete! Join our community review process or watch development of future tutorials in our [Github repo here](https://github.com/pyOpenSci/python-package-guide).
 
 
 :::::{grid} 1 1 2 2
@@ -100,7 +99,7 @@ by the community now! Join our community review process or watch development of
 :::::
 
 
-## Python packaging ecosystem overview & best practices
+## Python Packaging for Scientists
 
 Learn about Python packaging best practices. You will also get to know the
 the vibrant ecosystem of packaging tools that are available to help you with your Python packaging needs.
@@ -135,31 +134,90 @@ Learn about best practices for:
 
 :::
 ::::
+:::::
 
+## Documentation
+
+:::::{grid} 1 1 2 2
+:class-container: text-center
+:gutter: 3
 
 ::::{grid-item}
-:::{card} ✨ Write & Publish Docs ✨
+:::{card} ✨ Write The Docs ✨
 :class-card: left-aligned
 
 * [Create documentation for your users](/documentation/write-user-documentation/intro)
 * [Core files to include in your package repository](/documentation/repository-files/intro)
+* [Write tutorials to show how your package is used](/documentation/write-user-documentation/create-package-tutorials)
+:::
+::::
+
+::::{grid-item}
+:::{card} ✨ Developer Docs ✨
+:class-card: left-aligned
+
+* [Create documentation for collaborating developers](/documentation/repository-files/contributing-file)
+* [Write a development guide](/documentation/repository-files/development-guide)
+:::
+::::
+
+::::{grid-item}
+:::{card} ✨ Document For A Community ✨
+:class-card: left-aligned
+
+* [Writing a README file](/documentation/repository-files/readme-file-best-practices)
+* [Set norms with a Code of Conduct](/documentation/repository-files/code-of-conduct-file)
+* [License your package](/documentation/repository-files/license-files)
+:::
+::::
+
+::::{grid-item}
+:::{card} ✨ Publish Your Docs ✨
+:class-card: left-aligned
+
 * [How to publish your docs](/documentation/hosting-tools/intro)
+* [Using Sphinx](/documentation/hosting-tools/intro)
+* [Markdown, MyST, and ReST](/documentation/hosting-tools/myst-markdown-rst-doc-syntax)
+* [Host your docs on Read The Docs or Github Pages](/documentation/hosting-tools/publish-documentation-online)
 :::
 ::::
 
+:::::
+
+## Tests
+
+*We are actively working on this section. [Follow development here.](https://github.com/pyOpenSci/python-package-guide)*
+
+:::::{grid} 1 1 2 2
+:class-container: text-center
+:gutter: 3
+
 ::::{grid-item}
 :::{card} ✨ Tests for your Python package ✨
 :class-card: left-aligned
 
 * [Intro to testing](tests/index.md)
 * [Write tests](tests/write-tests)
 * [Types of tests](tests/test-types)
+:::
+::::
+
+::::{grid-item}
+:::{card} ✨ Run your tests ✨
+:class-card: left-aligned
+
 * [Run tests locally](tests/run-tests)
 * [Run tests in CI](tests/tests-ci)
-
-*We are actively working on this section. [Follow development here.](https://github.com/pyOpenSci/python-package-guide)*
 :::
 ::::
+:::::
+
+## Contributing
+
+:::::{grid} 1 1 2 2
+:class-container: text-center
+:gutter: 3
+
 
 ::::{grid-item}
 :::{card} ✨ Code style & Format ✨
@@ -228,20 +286,19 @@ This is a living guide that is updated as tools and best practices evolve in the
 Tutorials  <tutorials/intro>
 ```
 
-
 ```{toctree}
 :hidden:
-:caption: Documentation
+:caption: Packaging
 
-Documentation <documentation/index>
+Packaging <package-structure-code/intro>
 
 ```
 
 ```{toctree}
 :hidden:
-:caption: Packaging
+:caption: Documentation
 
-Packaging <package-structure-code/intro>
+Documentation <documentation/index>
 
 ```
 

noxfile.py

@@ -11,15 +11,26 @@
 
 @nox.session
 def docs(session):
-    session.install("-r", "requirements.txt")
+    session.install("-e", ".")
     cmd = ["sphinx-build"]
     cmd.extend(build_command + session.posargs)
     session.run(*cmd)
 
+@nox.session(name="docs-test")
+def docs_test(session):
+    """
+    Same as `docs`, but rebuild everything and fail on warnings for testing
+    """
+    session.install("-e", ".")
+    cmd = ["sphinx-build"]
+    cmd.extend(['-W', '--keep-going', '-E', '-a'])
+    cmd.extend(build_command + session.posargs)
+    session.run(*cmd)
+
 
 @nox.session(name="docs-live")
 def docs_live(session):
-    session.install("-r", "requirements.txt")
+    session.install("-e", ".")
 
     AUTOBUILD_IGNORE = [
         "_build",

pyproject.toml

@@ -1,8 +1,13 @@
+[build-system]
+requires = ["hatchling", "hatch-vcs"]
+build-backend = "hatchling.build"
+
 [project]
 name = "python-package-guide"
-
-[project.optional.dependencies]
-dev = [
+dynamic = [
+    "version"
+]
+dependencies = [
     "pydata-sphinx-theme==0.15.1",
     "myst-nb",
     "sphinx",
@@ -17,8 +22,14 @@ dev = [
     "sphinx-inline-tabs",
     # for project cards
     "matplotlib",
-    "sphinxcontrib-bibtex"
-    ]
+    "sphinxcontrib-bibtex",
+]
+
+[tool.hatch.build.targets.wheel]
+bypass-selection = true
+
+[tool.hatch]
+version.source = "vcs"
 
 
 # https://github.com/codespell-project/codespell#usage

tutorials/add-license-coc.md

@@ -174,7 +174,6 @@ That's it - you've now added a code of conduct to your package directory.
 
 - [<i class="fa-brands fa-github"></i> Guide: `CODE_OF_CONDUCT.md` files](https://docs.github.com/en/communities/setting-up-your-project-for-healthy-contributions/adding-a-code-of-conduct-to-your-project)
 - [pyOpenSci package guide `CODE_OF_CONDUCT.md` overview](https://www.pyopensci.org/python-package-guide/documentation/repository-files/code-of-conduct-file.html)
-
 :::
 
 ## <i class="fa-solid fa-hands-bubbles"></i> Wrap up

tutorials/publish-conda-forge.md

@@ -44,7 +44,7 @@ Anyone can submit a package to these channels however they must pass a technical
 
 [Learn more about conda channels here.](#about-conda)
 
-:::{figure-md} pypi-conda-channels
+:::{figure-md} pypi-conda-channels-2
 
 <img src="../images/python-pypi-conda-channels.png" alt="Graphic with the title Python package repositories. Below it says anything hosted on PyPI can be installed using pip install. Packaging hosted on a conda channel can be installed using conda install. Below that there are two rows. The top row says conda channels. Next to it are three boxes one with conda-forge, community maintained; bioconda and then default - managed by the Anaconda team. Below that there is a row that says PyPI servers. PyPI - anyone can publish to PyPI and test PyPI (a testbed server for you to practice)." width="700px">
 
@@ -228,7 +228,7 @@ where it saved the recipe file.
 
 Open the meta.yaml file. The finished `meta.yaml` file that grayskull creates should look like the example below:
 
-```yaml
+```yaml+jinja
 {% set name = "pyospackage" %}
 {% set version = "0.1.8" %}
 
@@ -421,7 +421,7 @@ This is also why we don't suggest you publish to conda-forge as a practice run.
 
 Once you create your pull request, a suite of CI actions will run that build and test the build of your package. A conda-forge maintainer will work with you to get your recipe in good shape and merged.
 
-:::{figure-md} pypi-conda-channels
+:::{figure-md} conda-forge-pr-build
 
 <img src="../images/conda-forge-staged-recipes-ci.png" alt="Image showing the 5 CI tasks that will run against your package in the GitHub interface after you'ce created a pull request. " width="700px">