Add build clarification to package guide

Author: lwasser

images/python-build-package/pypi-metadata-classifiers.png

@@ -1,7 +1,34 @@
 # Python Package Build Tools
 
+## What is building a Python package and why do we do it?
+
+In Python, if you want to publish your code in a way that can be
+installed by both yourself and others, your code, tests and associated
+metadata need to be organized in a specific way. This specific
+organization and structure is important because it's the structure
+that both `PyPI` and any installer that you use like `pip` can
+understand and parse. This process of organizing and formatting your
+code, documentation, tests and metadata into a format that both pip
+and PyPI can use, is called a build step.
+
+For instance, when you publish to PyPI, you will notice that each package has metadata listed. Let’s have a look at [xclim](https://pypi.org/project/xclim/), one of our [pyOpenSci packages](https://www.pyopensci.org/python-packages.html). Notice that on the PyPI landing page you see some metadata about the package including python, maintainer information and more. PyPI is able to populate this metadata because it was defined using correct syntax and classifiers by Xclim's maintainers, [pyproject.toml file](https://github.com/Ouranosinc/xclim/blob/master/pyproject.toml). This metadata when the xclim package is built, is translated into a distribution file that allows PyPI to read the metadata and print it out on their website.
+
+## How to create the distribution format that PyPI and Pip expects?
+
+You could in theory create your own scripts to organize your code the way PyPI wants it to be. However, just like there are packages that handle known structures such as Pandas for data frames and Numpy for arrays, there are packages and tools that help you create package build distribution files.
+
+```{note}
+
+BREAKOUT: there are a suite of packaging tools that can either help you with the entire packaging process or just one step of the process. For instance setuptools is a commonly used build back end that can be used to create your SDist and wheel. Whereas tools like Hatch, PDM, Poetry and flit help with other parts of the packaging process. While this can cause some confusion and complexity in the packaging ecosystem - for the most part, each tool provides the same distribution output (with minor differences that most users may not care about). Learn more about those tools on this page.
+```
+
+Below, you will learn about the two distribution files that PyPI expects you to publish: SDist and Wheel. You will learn about
+their structure and what files belong in each.
+
 <!-- TODO: add a small discussion on what pinning is?-->
 
+## Tools for building your package
+
 There are a several different build tools that you can use to [create your Python package's _sdist_ and _wheel_ distributions](python-package-distribution-files-sdist-wheel). Below, we discuss the features,
 benefits and limitations of the most commonly used Python packaging tools.
 We focus on pure-python packages in this guide. However, we also

images/python-build-package/pypi-metadata-keywords-license.png

@@ -1,5 +1,68 @@
 # The Python Package Source and Wheel Distributions
 
+```{figure} ../images/python-package-development-process.png
+:align: center
+:alt: Image showing the left side bar of PiPy for the package xclim. The section at the top says Classifier. Below there is a list of items including Development status, intended audience, License, natural language, operating system, programming language and topic. Below each of those sections are various classifier options." width="300px">
+
+Notice the metadata printed on the PyPI page for xclim. When you add the classifier section to your pyproject.toml
+and your package is built, the build tool organizes the metadata into a format that PyPI can understand and
+represent on your pypi landing page. These classifiers also allow users to sort through packages by version of python they support, categories and more.
+```
+
+## What is building a Python package?
+
+In Python, if you want to publish your code in a way that can be
+installed by both yourself and others, your code, tests and associated
+metadata need to be organized in a specific way. This specific
+organization and structure is important because it's the structure
+that both `PyPI` and any installer that you use like `pip` can
+understand and parse. This process of organizing and formatting your
+code, documentation, tests and metadata into a format that both pip
+and PyPI can use, is called a build step.
+
+For instance, when you publish to PyPI, you will notice that each package has metadata listed. Let’s have a look at [xclim](https://pypi.org/project/xclim/), one of our [pyOpenSci packages](https://www.pyopensci.org/python-packages.html). Notice that on the PyPI landing page you see some metadata about the package including python, maintainer information and more. PyPI is able to populate this metadata because it was defined using correct syntax and classifiers by Xclim's maintainers, [pyproject.toml file](https://github.com/Ouranosinc/xclim/blob/master/pyproject.toml). This metadata when the xclim package is built, is translated into a distribution file that allows PyPI to read the metadata and print it out on their website.
+
+```{figure} ../images/python-build-package/pypi-metadata-classifiers.png
+:scale: 50 %
+:align: center
+:alt: Image showing the left side bar of PiPy for the package xclim. The section at the top says Classifier. Below there is a list of items including Development status, intended audience, License, natural language, operating system, programming language and topic. Below each of those sections are various classifier options." width="300px">
+
+When you add the classifier section to your pyproject.toml
+and your package is built, the build tool organizes the metadata into a format that PyPI can understand and
+represent on your pypi landing page. These classifiers also allow users to sort through packages by version of python they support, categories and more.
+```
+
+:::{figure-md} fig-target
+<img src="../images/python-build-package/pypi-metadata-keywords-license.png" alt="t." width="700px">
+
+:::
+
+:::{figure-md} fig-target
+<img src="../images/python-build-package/pypi-metadata-maintainers.png" alt="t." width="700px">
+
+:::
+
+## How to create the distribution format that PyPI and Pip expects?
+
+You could in theory create your own scripts to organize your code the way PyPI wants it to be. However, just like there are packages that handle known structures such as Pandas for data frames and Numpy for arrays, there are packages and tools that help you create package build distribution files.
+
+```{note}
+
+There are a suite of packaging tools that can either help you with
+the entire packaging process or just one step of the process. For instance
+setuptools is a commonly used build back end that can be used to create your
+SDist and wheel. Whereas tools like Hatch, PDM, Poetry and flit help with other
+parts of the packaging process.
+
+While this can cause some confusion and
+complexity in the packaging ecosystem - for the most part, each tool provides
+the same distribution output (with minor differences that most users may not
+care about). Learn more about those tools on this page.
+```
+
+Below, you will learn about the two distribution files that PyPI expects you to publish: SDist and Wheel. You will learn about
+their structure and what files belong in each.
+
 There are two core distribution files
 that you need to create to publish your Python package to
 PyPI source distribution (often called an sdist) and wheel. The sdist contains the raw source