Fix: a few fixes from Jeremiah

Author: lwasser

package-structure-code/declare-dependencies.md

@@ -1,17 +1,52 @@
-# Python package dependency declaration
+# Declaring Development Dependencies - Python Packaging
 
 ## How to declare documentation, test and other deps
 
-It is currently recommended that you store all dependency information in a **pyproject.toml** file.
+In the [pyproject.toml overview page](pyproject-toml-python-package-metadata) we discussed how to setup a pyproject.toml file with basic metadata information.
+On this page, you will learn about storing and accessing dependency information within the pyproject.toml file.
+
+It is recommended that you store all dependency information in a **pyproject.toml** file (with a few caveats).
+
 This ensures that all of the metadata associated with your package is declared in a single place, making it simpler for users and contributors to understand your package infrastructure.
 
-Dependencies for building your documentation, running your tests and building your package's distribution files can be stored in a `[optional.dependencies]` table within the **pyproject.toml** file.
+## Direct project dependencies
+
+Your core project dependencies - representing the packages that
+a user requires to install your package, can be stored in a
+dependencies array located within the `[project]` table of your
+pyproject.toml file. This looks something like this:
+
+````toml
+[project]
+name = "examplePy"
+authors = [
+    {name = "Some Maintainer", email = "[email protected]"},
+]
+# more metadata here...
+dependencies = [
+    "rioxarray",
+    "geopandas",
+]
+```
+
+## Development dependencies
+
+Dependencies for building your documentation, running your tests and building your package's distribution files are often referred to as development dependencies. These are the dependnecies that a user needs to run core development elements of your package such as:
+
+* running your test suite
+* building your documentation
+* linting and other code cleanup tools
+
+These dependencies can be stored in an
+`[optional.dependencies]` table within the **pyproject.toml** file.
 
 ```{admonition} What happened to the requirements.txt file for dependencies?
 :class: note
 
-The requirements.txt file used to be the default way to store dependencies. However in recent years, the ecosystem has moved to storing all of this information in a single **pyproject.toml** file.
-```
+The requirements.txt file used to be the default way to store dependencies. However in recent years, the ecosystem has moved to storing all of this information in a single **pyproject.toml** file. You may find that some projects do still maintain a requirements.txt file either for specific local development needs OR to support users who may want to create a pip-based virtual environment.
+````
+
+## How to declare development dependencies
 
 To declare dependencies in your **pyproject.toml** file:
 
@@ -48,17 +83,22 @@ lint = [
 
 ## How to install dependencies from your pyproject.toml
 
-You can then install the dependencies via individual groups using:
+You can install development dependencies using the
+groups that you defined above using the syntax:
 
-`pip install yourPackage.[docs]`
+`pip install .[docs]`
 
-or you could install just the dependencies for your tests using:
+Above you install the dependencies needed for your documentation and also your package using pip. Below you
+install just the dependencies needed to run your tests:
 
-`pip install yourPackage.[tests]`
+`pip install .[tests]`
 
 You can install all dependencies in the `[optional.dependencies]` table using:
 
-`yourPackage.[all]`
+`pip install .[docs, tests, lint]`
+
+Each time you call `pip install .[groups-here]`, you are also installing your package locally and also any dependencies
+that your package needs / has declared in your pyproject.toml file.
 
 ```{admonition} For zsh shell users
 :class: tip
@@ -85,9 +125,10 @@ dev = [
 ]
 ```
 
-You can also install subsets of dependencies like this:
+The above allows you to install both the tests and docs dependency lists
+using the command:
 
-`pip install .[tests, docs]`
+`pip install .[dev]`
 
 ```{tip}
 When you install dependencies using the above syntax:
@@ -101,11 +142,9 @@ pip will also install both your package and its core dependencies.
 
 The above workflow assumes that you want to publish your package on PyPI. And then you plan to publish to conda-forge (optionally), [by submitting a recipe using greyskull](https://www.pyopensci.org/python-package-guide/package-structure-code/publish-python-package-pypi-conda.html).
 
-If you want to support conda users, you may want to also maintain a conda environment that they can use to install your package. Maintaning a conda environment will also help you test that your package installs as you expect into a conda environment.
-
-## Read the Docs & Python Environments
+If you want to support conda users, you may want to also maintain a conda environment that they can use to install your package. Maintaining a conda environment will also help you test that your package installs as you expect into a conda environment.
 
-TODO: we will link to this config section from the RTD page as well...
+## Read the Docs & project dependencies
 
 If you are using readthedocs to build your documentation, then you may need to install your dependencies using a **readthedocs.yaml** file.
 
@@ -129,7 +168,7 @@ python:
 
 The above should work if you are using a vanilla packaging approach with a tool such as the [PyPA build tool](https://pypa-build.readthedocs.io/en/stable/) and any back-end that works with `build`.
 
-If you are using another front-end build tool such as PDM, Hatch or Poetry to manage dependencies, then your approach to installing dependencies may be different. Each tool has its own, slightly different way of declaring dependencies in the **pyproject.toml** file. You can learn more about [configuing RTD for tools such as Poetry and PDM here.](https://docs.readthedocs.io/en/stable/build-customization.html#install-dependencies-with-poetry)
+If you are using another front-end build tool such as PDM, Hatch or Poetry to manage dependencies, then your approach to installing dependencies may be different. Each tool has its own, slightly different way of declaring dependencies in the **pyproject.toml** file. You can learn more about [configuring RTD for tools such as Poetry and PDM here.](https://docs.readthedocs.io/en/stable/build-customization.html#install-dependencies-with-poetry)
 
 ```{admonition} A note for conda users
 :class: tip
@@ -138,5 +177,5 @@ If you use a conda environment for developing your tool, keep in mind that when
 
 Thus, if you are running a conda environment, installing your package in editable mode risks dependency conflicts. This is particularly important if you have a spatial package that required GDAL or has a GDAL supported dependency.
 
-Alternatively, you can install your package using `pip install -e . --no-deps` to only install the package. And install the rest of your depenedncies using a conda environment file.
+Alternatively, you can install your package using `pip install -e . --no-deps` to only install the package. And install the rest of your dependencies using a conda environment file.
 ```

package-structure-code/intro.md

@@ -156,6 +156,7 @@ Intro <self>
 Python package structure <python-package-structure>
 pyproject.toml Package Metadata <pyproject-toml-python-package-metadata>
 Build Your Package <python-package-distribution-files-sdist-wheel>
+Declare dependencies <declare-dependencies>
 Package Build Tools <python-package-build-tools>
 Complex Builds <complex-python-package-builds>
 ```