merge main

Author: sneakers-the-rat

.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