Fix: review feedback

Author: lwasser

package-structure-code/intro.md

@@ -14,41 +14,62 @@ best fitted for your workflow.
 :gutter: 3
 
 :::{grid-item-card}
-:link: python-package-build-tools
+:link: python-package-structure
 :link-type: doc
 
-✨ Finding the right packaging tool(s) ✨
+✨ 1. Package file structure ✨
 ^^^
-
-Learn more about the suite of packaging tools out there.
-And learn which tool might be best for you.
+src layout, flat layout and where should tests folders live? No matter what your level of packaging knowledge is, this page will help you decide upon a package structure that follows modern python best practices.
 :::
 
 :::{grid-item-card}
 :link: python-package-structure
 :link-type: doc
 
-✨ Package file structure ✨
+✨ 2. Learn about building your package ✨
 ^^^
-src layout, flat layout and where should tests folders live? No matter what your level of packaging knowledge is, this page will help you decide upon a package structure that follows modern python best practices.
+Building a Python package refers to the process of placing your package code
+metadata (and tests) into a specific format that PyPI can read and that
+your users can install. Learn more about building a Python package here.
 :::
 
 :::{grid-item-card}
 :link: python-package-build-tools
 :link-type: doc
 
-✨ Publish to PyPI and Conda ✨
+✨ 3. What Python package tool should you use? ✨
+^^^
+
+Learn more about the suite of packaging tools out there.
+And learn which tool might be best for you.
+:::
+
+:::{grid-item-card}
+:link: python-package-build-tools
+:link-type: doc
+
+✨ 4. Publish your package to PyPI and Conda ✨
 ^^^
 If you have a pure python package, it's a straight forward
 process to publish to both PyPI and then a Conda channel such as
 conda-forge. Learn more here.
 :::
 
+:::{grid-item-card}
+:link: python-package-versions
+:link-type: doc
+
+✨ 5. Setup package versioning ✨
+^^^
+Semver (numeric versioning) and Calver (versioning using the date) are 2
+common ways to version a package. Which one should you pick? Learn more here.
+:::
+
 :::{grid-item-card}
 :link: code-style-linting-format
 :link-type: doc
 
-✨ Code style & linters ✨
+✨ 6. Code style & linters ✨
 ^^^
 Black, blue, flake8, Ruff - which tools can help you ensure your
 package follows best practices for code format? Learn more about the options and why this is important here.
@@ -134,8 +155,8 @@ if you are looking for pyOpenSci's Python package review requirements!
 Intro <self>
 
 Python package structure <python-package-structure>
-pyproject.toml Package Metadata <pyproject-toml-python-package-metadata>
-What are SDist & Wheel Files? <python-package-distribution-files-sdist-wheel>
+pyproject.toml Package Metadata <pyproject-toml-python-package-metada>
+Build Your Package <python-package-distribution-files-sdist-wheel>
 Package Build Tools <python-package-build-tools>
 Complex Builds <complex-python-package-builds>
 ```

package-structure-code/python-package-distribution-files-sdist-wheel.md

@@ -1,25 +1,30 @@
-# The Python Package Source and Wheel Distributions
+# Learn about Building a Python Package
 
-```{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">
+:::{figure-md} build-workflow
+<img src="/images/python-package-development-process.png" alt="Alt tag to be added when image is final" width="700px">
 
-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.
-```
+You need to build your Python package in order to publish it to PyPI or Conda. For PyPI, the build process essentially organizes your code and metadata into a distribution format that PyPI can read and provide to potential users.
+:::
 
 ## 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
+To [publish your Python package](build-workflow) and make it easy for anyone to install, you first need to build it.
+
+But, what does it mean to build a Python package?
+
+[As shown in the figure above](build-workflow), when you build your Python package, you convert the source files into something called a distribution package. A distribution package contains your source code and metadata about the package, in the format required by the Python Package Index, so that it can be installed by tools like pip.
+
+:::{note}
+The term package used to mean many different things in Python and other languages. On this page, we adapt the convention of the [Python Packaging Authority](https://www.pypa.io/en/latest/) and refer to the product of the
+build step as a **distribution package**.
+:::
+
+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.
 
+### Project metadata and PyPI
+
 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