diff --git a/tutorials/intro.md b/tutorials/intro.md index 78225e5d..140bc756 100644 --- a/tutorials/intro.md +++ b/tutorials/intro.md @@ -1,60 +1,15 @@ # Python packaging 101 *A start to finish beginner-friendly tutorial* - - - - - - -Welcome to the pyOpenSci Python packaging tutorial series. The lessons on the upcoming pages walk you through the core steps needed to +Welcome to the pyOpenSci Python packaging tutorial series. The lessons +on the upcoming pages walk you through the core steps needed to create a Python package. - :::{figure-md} packaging-outline -Diagram showing .. more here if this stays. +Diagram showing the lessons in our packaging tutorial. -TODO: This will be replaced with a interactive CSS element that walks users through lessons +Packaging tutorial overview graphic ::: ## Who are these tutorials for? @@ -64,9 +19,6 @@ that you have not created a Python package before. However, the content will still be valuable if you are interested in better understanding the steps involved in creating a Python package. - In this series you will learn about the core elements that you need to publish your package to the [Python Package Index (PyPI)](https://pypi.org/). @@ -106,7 +58,7 @@ to manage and reuse code across different projects. A package is installable, which means that you can add the functionality within the package code to any Python environment and import that functionality like -you would import numpy or matplotlib. +you would import NumPy or matplotlib. At a high level, you can think about each package as a toolbox filled with different tools that perform specific actions in your code when imported and @@ -114,26 +66,14 @@ called. :::{figure-md} python-toolbox -Diagram showing ADD ALT. +Diagram showing a sketch of a toolbox filled with different tools including a hammer and a saw. -You can think about a package as a toolbox filled with coding tools. A tool may be a function or a -class. Each tool does a specific thing well. +You can think about a package as a toolbox filled with coding tools. +A tool may be a function or a class. Each tool does a specific thing +well. ::: - - - ## The elements of a Python package :::{figure-md} package-components @@ -204,12 +144,6 @@ Integrated CI/CD will help you maintain your software ensuing that changes to t The lifecycle of a scientific Python package. ::: - - - ```{toctree} :hidden: :caption: Pre game @@ -223,16 +157,16 @@ extras/* Ideally the code in your Python package is general. This means it can be used on different data or for different scientific applications. An example -of a package that is written in a generalized way is `matplotlib`. +of a package that is written in a generalized way is matplotlib. -`matplotlib` does +matplotlib does one (big important) thing really well: *It creates visual plots of data.* -`Matplotlib` is used by thousands of users for different plotting applications +Matplotlib is used by thousands of users for different plotting applications using different types of data. While few scientific packages will have the same -broad application as tools like `matplotlib` or `numpy`, the +broad application as tools like matplotlib or NumPy, the idea of code being used for something more than a single workflow still applies to package development if you want other people to use your package. @@ -272,12 +206,12 @@ which supports a specific project. ### Python packages and environments A Python package can be installed into a Python environment in the same way -you might install `numpy` or `pandas`. Installing your package into an environment +you might install NumPy or pandas. Installing your package into an environment allows you to access it from any code run with that specific Python environment activated. :::{figure-md} packages-environment -Diagram showing the steps associated with creating a package and then installing it. The first arrow says your package and the second says pip install package. The second arrow leads to a box that represents a python environment that already has some packages installed such as pandas and numpy. Your package will also get installed into that same environment when you pip install it. +Diagram showing the steps associated with creating a package and then installing it. The first arrow says your package and the second says pip install package. The second arrow leads to a box that represents a python environment that already has some packages installed such as pandas and NumPy. Your package will also get installed into that same environment when you pip install it. You don't have to publish to PyPI in order to make your code installable. WIth the correct file structure and project metadata you can make your code