pyOpenSci · lwasser · Nov 30, 2023 · Dec 22, 2023 · Dec 22, 2023 · Dec 22, 2023
diff --git a/images/tutorials/environment-package-install.png b/images/tutorials/environment-package-install.png
diff --git a/images/tutorials/package-components.png b/images/tutorials/package-components.png
diff --git a/images/tutorials/packaging-101-outline.png b/images/tutorials/packaging-101-outline.png
diff --git a/images/tutorials/packaging-lifecycle.png b/images/tutorials/packaging-lifecycle.png
diff --git a/images/tutorials/publish-package-pypi-conda.png b/images/tutorials/publish-package-pypi-conda.png
diff --git a/images/tutorials/toolbox.png b/images/tutorials/toolbox.png
diff --git a/index.md b/index.md
@@ -1,4 +1,93 @@
-# pyOpenSci Python Open Source Package Development Guide
+# pyOpenSci Python Package Guide
+
+Demystifying the Python packaging ecosystem with recommendations for
+scientists to follow.
+
+
+::::{grid} 2
+:reverse:
+
+:::{grid-item}
+:columns: 4
+:class: sd-m-auto
+
+:::
+
+:::{grid-item}
+:columns: 8
+:class: sd-fs-3
+
+```{button-link} https://www.pyopensci.org/about-peer-review/
+:color: primary
+:class: sd-rounded-pill float-left
+Learn about our open peer review process
+```
+
+```{only} html
+![GitHub release (latest by date)](https://img.shields.io/github/v/release/pyopensci/python-package-guide?color=purple&display_name=tag&style=plastic)
+[![](https://img.shields.io/github/stars/pyopensci/python-package-guide?style=social)](https://github.com/pyopensci/contributing-guide)
+[![DOI](https://zenodo.org/badge/556814582.svg)](https://zenodo.org/badge/latestdoi/556814582)
+```
+
+:::
+::::
+
+
+::::{grid} 1 1 2 2
+:class-container: text-center
+:gutter: 3
+
+:::{grid-item-card}
+:link: tutorials/intro
+:link-type: doc
+
+✨ Getting Started ✨
+^^^
+
+If you are new to packaging or just want an opinionated, end-to-end
+way to create a package, check out our tutorials
+:::
+
+:::{grid-item-card}
+:link: package-structure-code/intro
+:link-type: doc
+
+✨ Understand the Python Packaging Ecosystem ✨
+^^^
+If you are looking to better understand the tools and options in the
+diverse Python packaging ecosystem, then this section is for you. Here
+you will learn about the most commonly used tools in the ecosystem as
+well as the tools and processes that our community recommends.
+also tools and processes that our community recommends.
+:::
+
+:::{grid-item-card}
+:link: CONTRIBUTING
+:link-type: doc
+
+✨ Want to contribute? ✨
+^^^
+We welcome contributions to this guide. Learn more about how you can
+contribute.
+:::
+::::
+
+## About
+
+This guide is designed to walk you through a typical Python packaging experience.
+
+It does several things:
+
+1. it provides an overview of the various elements of a Python package
+2. it provides and overview of tools to create Python packages and recommends best practices
+3. it provides end-to-end tutorials to get you on your way creating a package
+
+```{toctree}
+:hidden:
+:caption: Tutorials
+
+Tutorials  <tutorials/intro>
+```
 
 ```{toctree}
 :hidden:
@@ -23,25 +112,17 @@ Packaging <package-structure-code/intro>
 CI & Tests  <ci-and-testing/intro>
 ```
 
-<!-- Github community standards
-https://github.com/pyOpenSci/python-package-guide/community -->
-
-## Welcome, Python open source enthusiast!
-
-Here you will find guidelines for what we look for in your scientific
-Python package when reviewing. You will also find best practice recommendations and curated lists of community resources surrounding packaging and package documentation.
-
 ### pyOpenSci's packaging goals
 
 Our goal is to help the
 community make decisions around how to create scientific Python packages. We are working towards a shared vision of packaging that helps users better understand where to start.
 
 ### How this guide is created
 
-This guide is created by pyOpenSci through an extensive review process. Each page in the guide has been reviewed by experts in the broader Python packaging landscape including people from :
+This guide is created by pyOpenSci through an extensive review process. Each page in the guide has been reviewed by experts in the broader Python packaging landscape, including people from:
 
-- conda & conda-forge
-- the python packaging authority
+- [conda](https://docs.conda.io/en/latest/)& [conda-forge](https://conda-forge.org/)
+- the [Python Packaging Authority](https://www.pypa.io/en/latest/)
 - core Python developers
 - core scientific Python developers
 - and others with expertise in packaging, package documentation, usability and other related knowledge areas
@@ -80,8 +161,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
 :class-container: text-center
 :gutter: 3
@@ -150,37 +229,5 @@ Most of the sections in this guide will ultimately include Good/Better/Best reco
 
 Good meets the requirements. Going beyond the minimum can make package maintenance easier-to-use for new users, easier-to contribute for new contributors and easier-to-maintain for you.
 
-This guide is now a work in progress. If you have ideas of things you'd like
+This guide is 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
-
-
-# TODO LINK TO CI BUILDS FOR Documentation>
-Maybe we can curate a list of CI builds that people can use??? or is that moving too close to a cookie cutter situation
-
-The text below is being moved to the packaging infrastructure section which
-doesn't exist YET... but will soon .
-pyOpenSci packages must:
-
-- Contain full documentation for any user-facing functions.
-- Have a test suite that covers the major functionality of the package.
-- Use continuous integration.
-- Use an OSI approved software license.
-
-
-## Other recommendations
-### Python version support
-You should always be explicit about which versions of Python your package supports.
-Keeping compatibility with old Python versions can be difficult as functionality changes.
-A good rule of thumb is that the package should support, at least,
-the latest three Python versions (e.g., 3.8, 3.7, 3.6).
-
-### Code Style
-pyOpenSci encourages authors to consult [PEP 8](https://www.python.org/dev/peps/pep-0008/) for information on how to style your code.
-
-### Linting
-An automatic linter (e.g. flake8) can help ensure your code is clean and free of syntax errors. These can be integrated with your CI.
-
--->
diff --git a/package-structure-code/python-package-distribution-files-sdist-wheel.md b/package-structure-code/python-package-distribution-files-sdist-wheel.md
@@ -146,6 +146,7 @@ Also note that we are not discussing conda build workflows in this section.
 [You can learn more about conda builds here.](https://conda.io/projects/conda-build/en/latest/user-guide/tutorials/index.html)
 ```
 
+(sdist)=
 ## Source Distribution (sdist)
 
 **Source files** are the unbuilt files needed to build your
@@ -219,6 +220,7 @@ items including a metadata directory and if you use `setuptools_scm` or `hatch_v
 the sdist may also contain a file that stores the version.
 ```
 
+(wheel)=
 ## Wheel (.whl files):
 
 A wheel file is a ZIP-format archive whose filename follows a specific format