Fix: many more comments from review 2

Author: lwasser

index.md

@@ -1,13 +1,13 @@
 # pyOpenSci Python Open Source Package Development Guide
 
-
 ```{toctree}
 :hidden:
 :caption: Documentation
 
-Documentation Overview <documentation/index>
+Documentation <documentation/index>
 
 ```
+
 ```{toctree}
 :hidden:
 :caption: Packaging
@@ -45,7 +45,6 @@ community make decisions around how to create scientific Python packages. We are
 :columns: 8
 :class: sd-fs-3
 
-
 ```{button-link} https://www.pyopensci.org/about-peer-review/
 :color: primary
 :class: sd-rounded-pill float-left
@@ -61,7 +60,6 @@ Learn about our open peer review process
 :::
 ::::
 
-
 <!-- I think this is the end of the header - below begins the next grid-->
 
 ::::{grid} 1 1 2 2
@@ -92,7 +90,6 @@ commonly used in the scientific Python community.
 All of the modern tools discussed in this guide will help you build an efficient packaging workflow. This section helps you select the tool that will work best for you.
 :::
 
-
 :::{grid-item-card}
 :link: CONTRIBUTING
 :link-type: doc
@@ -106,6 +103,7 @@ contribute.
 ::::
 
 ## Who this guidebook is for
+
 We assume that you are here because you are:
 
 1. Looking for guidance on creating a Python package.
@@ -118,9 +116,9 @@ Well, friend, you've come to the right place!
 
 This guidebook contains:
 
-* Explanation for "Good enough" minimum requirements associated with being reviewed by pyOpenSci
-* Explanation of better and best practices in case you want to set the bar higher for your package (which we hope you will)!
-* A curated list of resources to help you get your package into documented, usable and tested shape.
+- Explanation for "Good enough" minimum requirements associated with being reviewed by pyOpenSci
+- Explanation of better and best practices in case you want to set the bar higher for your package (which we hope you will)!
+- A curated list of resources to help you get your package into documented, usable and tested shape.
 
 ## Where this guide is headed
 
@@ -131,9 +129,6 @@ Good meets the requirements. Going beyond the minimum can make package maintenan
 This guide is now a work in progress. If you have ideas of things you'd like
 to see here, [we invite you to open an issue on GitHub that details any changes or additions that you'd like to see.](https://github.com/pyOpenSci/python-package-guide/issues).
 
-
-
-
 <!--
 COMMENTED OUT TEXT TO BE MOVED
 

package-structure-code/complex-python-package-builds.md

@@ -9,15 +9,13 @@ In the future, we want to provide resources for packaging workflows that require
 
 You can classify Python package complexity into three general categories. These
 categories can in turn help you select the correct package front-end and
-back end tools.
+back-end tools.
 
 1. **Pure-python packages:** these are packages that only rely on Python to function. Building a pure Python package is simpler. As such, you can chose a tool below that
-has the features that you want and be done with your decision!
+   has the features that you want and be done with your decision!
 2. **Python packages with non-Python extensions:** These packages have additional components called extensions written in other languages (such as C or C++). If you have a package with non-python extensions, then you need to select a build back-end tool that allows you to add additional build steps needed to compile your extension code. Further, if you wish to use a front-end tool to support your workflow, you will need to select a tool that
-supports additional build setps. In this case, you could use setuptools. However, we suggest that you chose build tool that supports custom build steps such as Hatch with Hatchling or PDM. PDM is an excellent choice as it allows you to also select your build back end of choice. We will discuss this at a high level on the complex builds page.
-3.**Python packages that have extensions written in different languages (e.g. fortran and C++) or that have non Python dependencies that are difficult to install (e.g. GDAL)** These packages often have complex build steps (more complex than a package with just a few C extensions for instance). As such, these packages require tools such as [scikit-build](https://scikit-build.readthedocs.io/en/latest/)
-or [meson-python](https://mesonbuild.com/Python-module.html) to build. NOTE: you can use meson-python with PDM.
-
+   supports additional build setps. In this case, you could use setuptools. However, we suggest that you chose build tool that supports custom build steps such as Hatch with Hatchling or PDM. PDM is an excellent choice as it allows you to also select your build back-end of choice. We will discuss this at a high level on the complex builds page. 3.**Python packages that have extensions written in different languages (e.g. fortran and C++) or that have non Python dependencies that are difficult to install (e.g. GDAL)** These packages often have complex build steps (more complex than a package with just a few C extensions for instance). As such, these packages require tools such as [scikit-build](https://scikit-build.readthedocs.io/en/latest/)
+   or [meson-python](https://mesonbuild.com/Python-module.html) to build. NOTE: you can use meson-python with PDM.
 
 <!--
 On this page, we will focus on using front-end tools to package pure python
@@ -45,17 +43,17 @@ ELI: It would be more accurate to say that PDM supports using PDM and setuptools
 Hatch - https://hatch.pypa.io/latest/config/build/#build-hooks uild hooks
 
 Ralf -
-Hatch has the worst take on building compiled code by some distance. Unless its author starts developing an understanding of build systems / needs, and implements support for PEP 517 build backend hooks in pyproject.toml, it's pretty much a dead end.
+Hatch has the worst take on building compiled code by some distance. Unless its author starts developing an understanding of build systems / needs, and implements support for PEP 517 build back-end hooks in pyproject.toml, it's pretty much a dead end.
 ****
 
 
  HEnry: Poetry will move to PEP 621 configuration in version 2.
 
-* pdm, hatch and poetry all have "ways" of supporting c extensions via pdm-backend, hatchling and poetry's build back end.
-* poetry's support for C extensions is not fully developed and documented (yet). * Poetry doesn't offer a way to facilitate "communication" between poetry front end and another back end like meson to build via a build hook. so while some have used it with other back end builds it's not ideal for this application
+* pdm, hatch and poetry all have "ways" of supporting c extensions via pdm-build, hatchling and poetry's build back-end.
+* poetry's support for C extensions is not fully developed and documented (yet). * Poetry doesn't offer a way to facilitate "communication" between poetry front end and another back-end like meson to build via a build hook. so while some have used it with other back-end builds it's not ideal for this application
 * pdm and poetry both rely on setuptools for C extensions. pdm's support claims to be fully developed and documented. poetry claims nothing, and doesn't document it.
 * hatch both offers a plugin type approach to support custom build steps
-PDM (right now) is the only tool that supports other back ends (hatch is working on this - 2 minor releases away)
+PDM (right now) is the only tool that supports other back-ends (hatch is working on this - 2 minor releases away)
 At some point a build becomes so complex that you need to use a tool like scikit or meson to support that complexity.
 
 
@@ -68,42 +66,40 @@ part of your packaging steps. These tools also support some C and C++
 extensions.
 
 
-OFEK - Why use hatchlin vs pdm back end -
+OFEK - Why use hatchlin vs pdm back-end -
 File inclusion is more configurable and easier by default
 There is already a rich ecosystem of plugins and a well-thought-out interface
 Consistency since the official Python packaging tutorial uses Hatchling by default
 
 
 Henry -
-The scikit-hep cookie provides 11 backends including flit-core and hatchling, and I've moved packaging to flit-core, and lots of other things to hatchling, and I can say that hatching's defaults are much nicer than flit-core's. Hatching uses .gitignore to decide what to put in the SDist. Flit-core basically tries to keep its hands off of adding defaults, so you have to configure everything manually. To make it even more confusing, if you use flit instead of a standard tool like build, it will switch to using VCS and those ignored files won't be added - meaning it is really easy to have a project that doesn't support build, including various GitHub Actions. Hatchling wins this by a ton.
+The scikit-hep cookie provides 11 back-ends including flit-core and hatchling, and I've moved packaging to flit-core, and lots of other things to hatchling, and I can say that hatching's defaults are much nicer than flit-core's. Hatching uses .gitignore to decide what to put in the sdist. Flit-core basically tries to keep its hands off of adding defaults, so you have to configure everything manually. To make it even more confusing, if you use flit instead of a standard tool like build, it will switch to using VCS and those ignored files won't be added - meaning it is really easy to have a project that doesn't support build, including various GitHub Actions. Hatchling wins this by a ton.
 
-<!-- TODO: add - compatible with other build back ends eg pdm can work with hatchling
+<!-- TODO: add - compatible with other build back-ends eg pdm can work with hatchling
 
 Eli:
 poetry: supports it, but is undocumented and uses setuptools under the hood, they plan to change how this works and then document it
-pdm-backend: supports it, and documents it -- and also uses setuptools under the hood
+pdm-back-end: supports it, and documents it -- and also uses setuptools under the hood
 hatchling: permits you to define hooks for you to write your own custom build steps, including to build C++ extensions
 
 -->
 
-
-
 <!-- from eli about pdm
 It would be more accurate to say that PDM supports using PDM and setuptools at the same time, so you run setuptools to produce the C extensions and then PDM receives the compiled extension files (.so, .pyd) and packages it up alongside the pure Python files.
 
 Comment about hatch.
 https://github.com/pyOpenSci/python-package-guide/pull/23#discussion_r1081108118
 
-From ralf: There are no silver bullets here yet, no workflow tool is complete. Both Hatch and PDM are single-author tools, which is another concern. @eli-schwartz's assessment is unfortunately correct here I believe (at a high level at least, not sure about details). Hatch has the worst take on building compiled code by some distance. Unless its author starts developing an understanding of build systems / needs, and implements support for PEP 517 build backend hooks in pyproject.toml, it's pretty much a dead end.
+From ralf: There are no silver bullets here yet, no workflow tool is complete. Both Hatch and PDM are single-author tools, which is another concern. @eli-schwartz's assessment is unfortunately correct here I believe (at a high level at least, not sure about details). Hatch has the worst take on building compiled code by some distance. Unless its author starts developing an understanding of build systems / needs, and implements support for PEP 517 build back-end hooks in pyproject.toml, it's pretty much a dead end.
 
 -->
 
 <!--TODO Add examples of builds using each of the tools below?
 
-pdm, hatch and poetry all have "ways" of supporting c extensions via pdm-build, hatchling and poetry's build back end.
-poetry's support for C extensions is not fully developed and documented (yet). Poetry doesn't offer a way to facilitate "communication" between poetry front end and another back end like meson to build via a build hook.
+pdm, hatch and poetry all have "ways" of supporting c extensions via pdm-build, hatchling and poetry's build back-end.
+poetry's support for C extensions is not fully developed and documented (yet). Poetry doesn't offer a way to facilitate "communication" between poetry front end and another back-end like meson to build via a build hook.
 PDM and hatch both offer a plugin type approach to support custom build steps
-PDM (right now) is the only tool that supports other back ends (hatch is working on this - 2 minor releases away)
+PDM (right now) is the only tool that supports other back-ends (hatch is working on this - 2 minor releases away)
 At some point a build becomes so complex that you need to use a tool like scikit or meson to support that complexity.
 
 CORRECTIONS:
@@ -125,10 +121,10 @@ build back-ends such as **meson** and **scikit-build**.
 
 
 me:
-pdm, hatch and poetry all have "ways" of supporting c extensions via pdm-build, hatchling and poetry's build back end.
-poetry's support for C extensions is not fully developed and documented (yet). Poetry doesn't offer a way to facilitate "communication" between poetry front end and another back end like meson to build via a build hook.
+pdm, hatch and poetry all have "ways" of supporting c extensions via pdm-build, hatchling and poetry's build back-end.
+poetry's support for C extensions is not fully developed and documented (yet). Poetry doesn't offer a way to facilitate "communication" between poetry front end and another back-end like meson to build via a build hook.
 PDM and hatch both offer a plugin type approach to support custom build steps
-PDM (right now) is the only tool that supports other back ends (hatch is working on this - 2 minor releases away)
+PDM (right now) is the only tool that supports other back-ends (hatch is working on this - 2 minor releases away)
 At some point a build becomes so complex that you need to use a tool like scikit or meson to support that complexity.
 @eli-schwartz eli-schwartz 3 weeks ago
 PDM and hatch both offer a plugin type approach to support custom build steps
@@ -141,7 +137,6 @@ pdm and poetry both rely on setuptools for C extensions. pdm's support claims to
 https://pdm.fming.dev/latest/pyproject/build/#build-platform-specific-wheels
 -->
 
-
 <!-- https://github.com/pyOpenSci/python-package-guide/pull/23#discussion_r1071541329
 ELI: A complex build could mean running a python script that processes some data file and produces a pure python module file.
 

package-structure-code/pyproject-toml-python-package-metadata.md

@@ -30,15 +30,16 @@ resources working with complex builds in the future.
 ```
 
 ### Example pyproject.toml for building using PDM
+
 Below is an example build configuration for a Python project. This example
 package setup uses:
 
-* **pdm.pep517.api** to build the [package's SDist and wheels](python-package-distribution-files-sdist-wheel)
+- **pdm.pep517.api** to build the [package's sdist and wheels](python-package-distribution-files-sdist-wheel)
 
 ```
 [build-system]
 requires = ["pdm-pep517>=1.0.0"]
-build-backend = "pdm.pep517.api"
+build-back-end = "pdm.pep517.api"
 
 [project]
 name = "examplePy"
@@ -56,6 +57,7 @@ dependencies = [
     "dependency-package-name-2",
 ]
 ```
+
 Notice that dependencies are specified in this file.
 
 ### Example pyproject.toml for building using setuptools
@@ -66,19 +68,19 @@ Notice how simple it is to swap out the tools needed to build this package!
 
 In this example package setup you use:
 
-* **setuptools** to build the [package's SDist and wheels](python-package-distribution-files-sdist-wheel)
-* **setuptools_scm** to manage package version updates using version control tags
+- **setuptools** to build the [package's sdist and wheels](python-package-distribution-files-sdist-wheel)
+- **setuptools_scm** to manage package version updates using version control tags
 
 In the example below `[build-system]` is the first table
-of values. It has two keys that specify the build front end and backend for a package:
+of values. It has two keys that specify the build front end and back-end for a package:
 
 1. `requires =`
-1. `build-backend =`
+1. `build-back-end =`
 
 ```
 [build-system]
 requires = ["setuptools>=45", "setuptools_scm[toml]>=6.2"]
-build-backend = "setuptools.build_meta"
+build-back-end = "setuptools.build_meta"
 
 [project]
 name = "examplePy"
@@ -97,8 +99,6 @@ dependencies = [
 ]
 ```
 
-
-
 ```{note}
 [Click here to read about our packaging build tools including PDM, setuptools, Poetry and Hatch.](/package-structure-code/python-package-build-tools)
 ```