Fix: address comments on intro page and update with python as a flex language

lwasser · lwasser · commit b98fe5684504 · 2023-01-25T13:42:09.000-07:00
diff --git a/conf.py b/conf.py
@@ -93,7 +93,7 @@
 html_theme = 'furo'
 html_static_path = ["_static"]
 html_css_files = ["pyos.css"]
-html_title = "pyOpenSci Package Guide"
+html_title = "pyOpenSci Python Packaging Guide"
 html_logo = "images/logo/logo.png"
 
 # Add any paths that contain custom static files (such as style sheets) here,
diff --git a/index.md b/index.md
@@ -111,42 +111,39 @@ to see here, [we invite you to open an issue on GitHub that details any changes
 
 ```{toctree}
 :hidden:
-:caption: Documentation
 
-Documentation Overview <documentation/index>
-Write User Documentation <documentation/write-user-documentation/intro>
-Core GitHub Repository Files <documentation/repository-files/intro>
-Documentation Tools & Hosting  <documentation/hosting-tools/intro>
+🏠 Home <self>
 ```
 
-
 ```{toctree}
 :hidden:
-:caption: Package structure & code style
+:caption: Package structure
 
-<<<<<<< HEAD
-Intro <python-packaging/intro>
+Intro <package-structure-code/intro>
+Python package structure <package-structure-code/python-package-structure>
+What are SDIst & Wheel Files? <package-structure-code/python-package-distribution-files-sdist-wheel.md>
+Package Build Tools <package-structure-code/python-package-build-tools>
 
 ```
 
 
+```{toctree}
+:hidden:
+:caption: Documentation
+
+Documentation Overview <documentation/index>
+Write User Documentation <documentation/write-user-documentation/intro>
+Core GitHub Repository Files <documentation/repository-files/intro>
+Documentation Tools & Hosting  <documentation/hosting-tools/intro>
+```
+
 
 ```{toctree}
 :hidden:
 :caption: CI and Testing
 
-Intro <ci-and-testing/intro>
-=======
-Intro <package-structure-code/intro>
-
-Python package structure <package-structure-code/python-package-structure>
-What are SDIst & Wheel Files? <package-structure-code/python-package-distribution-files-sdist-wheel.md>
-Package Build Tools <package-structure-code/python-package-build-tools>
 Package Versions <package-structure-code/python-package-versions>
-package-structure-code/overview
-package-structure-code/collaboration
 Code Style & Format <package-structure-code/code-structure-style>
->>>>>>> e8b229d (Add: package structure and build tools)
 ```
 
 
diff --git a/package-structure-code/intro.md b/package-structure-code/intro.md
@@ -1,29 +1,10 @@
 # Python package structure information 
 
 If you plan to submit a package for review to pyOpenSci and are looking for 
-some guidance on package structure, code formats and style, then this section is for you. 
+some guidance on package structure, code formats and style, then this section 
+is for you. 
 
-## Guidelines for pyOpenSci's packaging recommendations 
-
-<!-- Might belong on the LANDING page for this entire guide?-->
-
-There are some differing opinions on what Python package structure should 
-look like and what tools to use across the Python ecosystem. 
-
-In this guide, we have made decisions around suggested standards and required 
-standards, based upon the commonly used approaches in the scientific Python 
-community.  Our goal is to help standardize packaging across this ecosystem.
-
-In some cases the suggestions here may diverge from those in the non-scientific parts of the Python ecosystem. 
-
-```{note}
-The suggestions for package layout in this section are made with the 
-intent of being helpful; they are not specific requirements for your 
-package to be reviewed and accepted into our ecosystem.
-```
-
-In all cases, we try to align our suggestions with the most current, accepted
-[PEP's (Python Enhancement Protocols)](https://peps.python.org/pep-0000/) and the [scientific-python community specs](https://scientific-python.org/specs/). 
+<!-- TODO: move this either to the top of this section or the landing page?-->
 
 ```{note}
 Have a look at the 
@@ -35,6 +16,39 @@ anyone who is just getting started with creating a Python package.
 In general these are basic items that should be in any open software repository. 
 ```
 
+## Guidelines for pyOpenSci's packaging recommendations 
+
+<!-- Might belong on the LANDING page for this entire guide?-->
+
+Python is a flexible programming language that is used across numerous 
+disciplines and domains. Python is so flexible that it is one of the few 
+languages that can be used to wrap around other languages.
+
+If you are building a pure Python package, then your packaging setup can be 
+simple. However, some scientific packages have complex requirements as they may 
+need to support extensions or tools written in other languages such as C or C++.
+
+To support the many different uses of Python, there are many ways to create a 
+Python package. 
+
+The ecosystem is dynamic, and constantly evolving to support
+the numerous needs that developers (and scientists) have using Python. 
+
+This dynamic yet flexible environment is what many love about Python. 
+
+## What you will learn here 
+
+In this section of our Python packaging guide, we try to:
+
+* Provide an overview of the options available to you when packaging your tool 
+* Suggest tools and approaches that both meet your needs and also support existing standards. 
+* Suggest tools and approaches that will allow you to expand upon a workflow that may begin as a pure Python tool and evolve into a tool that requires addition layers of complexity in the packaging build. 
+* Align our suggestions with the most current, accepted
+[PEPs (Python Enhancement Protocols)](https://peps.python.org/pep-0000/) and the [scientific-python community SPECs](https://scientific-python.org/specs/). 
+* In an effort to maintain consistency withint our community , we also align with existing best practices being implemented by developers of core Scientific Python packages such as numpy, scipy and others. 
+
+
+
 
 <!-- 
 
diff --git a/package-structure-code/python-package-build-tools.md b/package-structure-code/python-package-build-tools.md
@@ -1,39 +1,50 @@
 # Python Package Build Tools 
 
+<!--TODO Add examples of builds using each of the tools below? -->
+
 Below, we discuss some of the tools that are commonly used 
 to build Python packages. This page is intended to help 
 maintainers select a build tool to use. 
 
 ## Tools to build python packages 
 
-There are a suite of build tools that you can use to create your Python 
-package's **SDist** and *Wheel* distributions. 
+There are several different build tools that you can use to create your Python 
+package's **SDist** and **Wheel** distributions. 
 To better understand your options, it's important to first understand the 
 difference between a 
 build tool front-end and build backend. 
 
 ## Build front-end vs. build backend tools for Python packaging
 
 ### Build back-ends 
-Every tool has a back-end 
-build tool that actually builds the package and creates associated 
-(SDist and wheel) distribution files. Some of the tools below such as **Flit** 
-and **PDM** only support pure Python package builds that do not have a 
-compilation or other additional build step. These types of tools are ideal if 
-you have a pure Python project. 
+Most packaging tools have a back-end 
+build tool that builds the package and creates associated 
+(SDist and wheel) distribution files. Some tools, such as **Flit**
+and **Hatch**, only support pure-Python package builds. A pure-Python build refers 
+to a package build that does not have extensions that are written in another 
+programming language (such as `C` or `C++`). These non-pure Python builds often 
+have additional code compilation steps. 
+
+```{note}
+**PDM** does have some support for `C`/[`Cython`](https://cython.org/) extensions. [Click here to 
+learn more.](https://pdm.fming.dev/latest/pyproject/build/#build-platform-specific-wheels
+)
+```
 
-Other tools such as **Hatch** and **setuptools** support more complex builds 
-with custom steps. 
+There are, however back-ends such as and **setuptools.build**, **meson.build** 
+and **scikit-build** that support complex builds with custom steps. If your 
+build is particularly complex (ie you have more than a few `C`/`C++` 
+extensions), we suggest you consider using **meson.build** or **scikit-build**. 
 
 ### Build front-ends
 Each tool discussed below has a front-end interface that you can use to perform 
 different types of Python packaging tasks.
+
 For instance, you can use **Flit**, **Hatch** and **PDM** to both build your 
 package and to publish your package to PyPI (or test PyPI). Setuptools, 
 on the other hand requires you to use **twine** to push to PyPI. 
 
-Using a tool like **Flit**, **Hatch** or **PDM** can makes your workflow 
-commands (and package requirements) consistent and simple. 
+Using a tool like **Flit**, **Hatch** or **PDM** will simplify your workflow.
 
 Example to build your package with **Flit**: 
 
@@ -53,21 +64,16 @@ twine check dist/*
 twine upload -r testpypi dist/*
 ```
 
-<!-- In the Python package build space **setuptools** is the original tool (i.e. 
-the OG) of build tools. With a tool like `setuptools` you have the flexibility 
-to publish python pure python packages and packages with custom build steps. 
-However, you will also need to use other tools such as **twine** -->
+However each tool has different features and limits on the types of packaging 
+steps that it supports. 
+Below we describe the broader ecosystem of Python package build tools. 
+We also highlight the benefits and potential limitations presented by each tool. 
 
 ## An ecosystem of Python build tools
 
 Below we introduce several of the most commonly used Python packaging build 
 tools (see chart below).
 
-Each tool has different features. There is no right or wrong tool to use as far 
-as pyOpenSci is concerned. We are just trying to help you find the tool that 
-works best for your workflow. 
-
-
 :::{figure-md} fig-target
 
 <img src="../images/python-package-tools-2022-survey-pypa.png" alt="Graph showing the results of the 2022 PyPA survey of Python packaging tools. On the x axis is percent response and on the y axis are the tools." width="700px">
