Fix: continued edits to tutorials

documentation/repository-files/license-files.md

@@ -1,4 +1,4 @@
-# Your repository should have a LICENSE.md file
+# License files for scientific Python open source software
 
 :::{button-link} https://www.pyopensci.org/about-peer-review/
 :color: primary
@@ -7,7 +7,7 @@
 Want to learn how to add a license file to your GitHub repository? Check out this lesson.
 :::
 
-A license file is important for any open source project to have. The license file helps your users and the community understand
+A license file is important for any open source project to have. The license file helps your users and the community understand:
 
 1. how they can use your software
 2. whether the software can be reused or adapted for other purposes
@@ -17,16 +17,40 @@ and more.
 
 ## Where to store your license.
 
-The root of your GitHub / GitLab repository should have a `LICENSE.txt` file that contains descriptive text that identifies the type of license that you have selected for your software.
+The root of your GitHub / GitLab repository should have a `LICENSE` file that
+contains descriptive text that identifies the type of license that you have
+selected for your software.
 
-### What type of license to use
+### Use open permissive licenses when possible
 
-If you are [submitting your project to pyOpenSci for peer review](https://www.pyopensci.org/about-peer-review/index.html), then your project should use an [Open Software Initiative (OSI) approved license ](https://opensource.org/licenses).
+We generally suggest that you use a permissive, license that is [Open Software Initiative (OSI) approved](https://opensource.org/licenses). If you are
+[submitting your package to pyOpenSci for peer review](https://www.pyopensci.org/about-peer-review/index.html), then we require an OSI approved
+license.
+
+### How to chose a license
 
 To select your license, we suggest that you use GitHub's
 [Choose a License tool ](https://choosealicense.com/).
 
-If you choose your license through GitHub, you can also automatically get a copy of the license file to add to your repository.
+If you choose your license when creating a new GitHub repository, you can also
+automatically get a text copy of the license file to add to your repo. However
+in some cases the license that you want is not available through that online
+process.
+
+:::{admonition} License recommendations from the SciPy package
+[The SciPy documentation has an excellent overview of licenses.](https://docs.scipy.org/doc/scipy/dev/core-dev/index.html#licensing). Once of the key elements
+that these docs recommend is ensuring that the license that you select is
+complementary to license used in the core scientific Python ecosystem.
+Below is a highlight of this text which outlines license that are compatible
+with the modified BSD license that SciPy uses.
+
+> Other licenses that are compatible with the modified BSD license that SciPy uses are 2-clause BSD, MIT and PSF. Incompatible licenses are GPL, Apache and custom licenses that require attribution/citation or prohibit use for commercial purposes.
+
+Too coordinate with other packages in our scientific ecosystem, we also recommend
+that you consider using either BSD or MIT as your
+license. If you are unsure, the MIT license tends to be a simpler easier-to-understand option.
+:::
+
 
 ## Important: make sure that you closely follow the guidelines outlines by the License that you chose
 
@@ -49,7 +73,7 @@ This means that technically, if you copy code from the Stack Overflow website, a
 🚨 Proceed with caution! 🚨
 :::
 
-[The SciPy documentation has an excellent license discussion that is worth reading and considering for your project's development guide.](https://docs.scipy.org/doc/scipy/dev/core-dev/index.html#licensing)
+
 
 <!-- TODO: Add discussion of GitHub citation.cff files ??
 i think we need to better understand how this works before adding it...

tutorials/1-installable-code.md

@@ -1,22 +1,16 @@
 # Make your Python code pip installable
 
-<!--
-
-TODO: don't forget a .gitignore ...
 
 
-FROM CAROL: Probably more accurate to say that the _init_.py  allows Python to recognize that the directory is a module that may be imported and used. A package can have multiple modules.
+:::{figure-md} code-to-script
 
+<img src="../images/tutorials/code-to-script-diagram.png" alt="Diagram showing .. more here if this stays." width="700px">
 
-TODO list
-
-- https://docs.python.org/3/tutorial/modules.html#packages -< link to this docs...>
-- make the pyproj toml explanation much shorter and link to the next lesson
-- consolidate the pyproj description as it's in there twice now.
-- i think it would be cool to have a package spectrum graphic. on the left is you just have code that you want to use, then the code can be installed, then you can build a package... etc etc so each tutorial would highlight a step across that spectrum
-- the packaging guide pyproject.toml page is really poor right now as is. -->
+This is just a concept - if we use change the icons to match the steps
+:::
 
 :::{admonition} Learning Objectives
+:class: tip
 
 In this lesson you will learn:
 
@@ -26,12 +20,23 @@ In this lesson you will learn:
 - How to install your package in editable mode for interactive development
 
 To complete this lesson you will need a local Python (development)
-environment. You are welcome to use any environment manager that you chose. [Review this lesson,](1-create-environment) which walks you through creating an environment using both `venv` and `conda`. If you aren't sure which environment manager to use and
+environment. You are welcome to use any environment manager that you chose.
+
+* [If you need guidance creating a Python environment, review this lesson](extras/1-create-environment.md) which walks you through creating an environment using both `venv` and `conda`.
+* If you aren't sure which environment manager to use and
 you are a scientist, we suggest that you use `conda`.
 :::
 
 ## Make your package installable
 
+
+:::{figure-md} packages-environment
+
+<img src="../images/environment-package-install.png" alt="Diagram showing .. more here if this stays." width="500px">
+
+This is an ugly a concept. The graphic should show that you can turn your script into something that can be installed into a contained Python environment. Or you can turn your code into a full package installable from PyPI (or github but we can leave that out to reduce complexity).
+:::
+
 It’s time to create the most basic version of a Python package.
 While this code can't be yet published to PyPI or conda and
 is not documented, it will be installable on your computer or
@@ -48,8 +53,7 @@ To make your code installable you need:
 
 The directory structure you’ll create in this first section looks like this:
 
-```toml
-
+```bash
 pyospackage/
      └─ pyproject.toml
      └─ src/  # the src directory ensures your tests always run on the installed
@@ -87,7 +91,7 @@ The `__init__.py` file also:
 :::{admonition} The **init**.py file
 :class: tip
 
-You can technically install a package without an `__init__.py` file since Python 3.3, we suggest that you include it in your package structure as it allows you to make some important customizations to your package’s user experience.
+Since Python 3.3 came out, you can install a package without an `__init__.py` file. However, we suggest that you include it in your package structure as it allows you to customize your package’s user experience.
 :::
 
 ### What is a pyproject.toml file?
@@ -96,14 +100,12 @@ The **pyproject.toml** file is:
 
 - Where you store your project’s metadata (including its name, authors, license, etc)
 - Where you store dependencies (the packages that it depends on)
-- Used to specify and configure what build back end you want to use to create your package.
-
-A **pyproject.toml**: This file is critical for both installing your package and publishing to pyPi. This is where you will declare your project build system tools, dependencies and metadata. More on that later
+- Used to specify and configure what build back end you want to use to build your package distributions that are used for PyPI publication.
 
-After the `__init__.py` and `pyproject.toml` files have been added, your package can be built and distributed as an installable Python package using tools like pip. Note that the `pyproject.toml` file needs to have the a few basic items defined for this to work including:
+After the `__init__.py` and `pyproject.toml` files have been added, your package can be built and distributed as an installable Python package using tools such as pip. Note that the `pyproject.toml` file needs to have the a few basic items defined for it to be installable including:
 
-- The build backend that you want to use,
-- The project name, and a few other metadata elements.
+- The build-backend that you want to use,
+- The project name and version.
 
 :::{admonition} pro tip
 :class: tip
@@ -122,11 +124,13 @@ Neither 'setup.py' nor 'pyproject.toml' found.
 
 ## Try it yourself - Create your package!
 
-Now that you understand the basics, it's time to create a Python package! Create a directory structure similar to the structure below. If you don’t wish to create each of the files and directories below, you can always [fork and clone and customize the pyOpenSci example package, here](https://github.com/pyOpenSci/pyosPackage)
+Now that you understand the basics, it's time to create a Python package! Below you will create a directory structure similar to the structure described above.
+
+If you don’t wish to create each of the files and directories below, you can always [fork and clone and customize the pyOpenSci example package, here.](https://github.com/pyOpenSci/pyosPackage)
 
 ### Step 1: Set Up the Package Directory Structure
 
-Create a new directory for your package. Choose a name for your package, preferably in lowercase and without spaces (e.g., "pyospackage").
+Create a new directory for your package. Choose a name for your package, preferably in lowercase and without spaces (e.g., "pyospackage_yourname").
 
 Inside the package directory,
 
@@ -145,7 +149,7 @@ Your final package directory structure should look like this:
 pyospackage/
      └─ pyproject.toml
      └─ src/
-             └── pyospackage/
+             └── pyospackage_yourname/
               	     ├── __init__.py
 ```
 
@@ -236,8 +240,8 @@ instance, a `build-system` table most often holds 2 variables:
 2. `build-backend` is used to define specific build-backend name, (in this example we are using `hatchling.build`).
 
 TOML organizes data structures, defining relationships within a configuration
-file. You will learn more about the pyproject.toml format in the
-[next lesson when you add additional metadata / information to this file.](/python-package-tutorial/pyproject-toml.html)
+file. You will learn more about the `pyproject.toml` format in the
+[next lesson when you add additional metadata / information to this file.](3-pyproject-toml.md)
 
 ```toml
 # An example of the build-system table which contains two variables - requires and build-backend
@@ -268,7 +272,9 @@ version using git tags in the version and release your package lesson. <ADD LINK
 :::{admonition} The bare minimum needed in a pyproject.toml file
 :class: tip
 
-The core basic information that you need in a `pyproject.toml` file in order to publish on PyPI is the name of your package and the version. However, we suggest that you flesh out your metadata early on in the `pyproject.toml` file. Once you have your project metadata in the pyproject.toml file, you will
+The core basic information that you need in a `pyproject.toml` file in order to publish on PyPI is your **package's name**  and the **version**. However, we suggest that you flesh out your metadata early on in the `pyproject.toml` file.
+
+Once you have your project metadata in the pyproject.toml file, you will
 rarely update it. In the next lesson you’ll add more metadata and structure to this file.
 :::
 
@@ -288,7 +294,7 @@ Let’s try it out.
 NOTE: just in case we may want to include the bash lessons here?? -->
 
 - First open bash and `cd` into your package directory
-- Activate the Python environment that you wish to use. If you need help with working with virtual environments [check out this lesson](1-create-environment).
+- Activate the Python environment that you wish to use. If you need help with working with virtual environments [check out this lesson](extras/1-create-environment.md).
 - Finally run `python -m pip install -e .`
 
 ```bash
@@ -312,12 +318,15 @@ Obtaining file:///Users/leahawasser/Documents/GitHub/pyos/pyosPackage
 # use pip list instead of conda list here if you are working in an venv environment rather than a conda envt
 ```
 
-Before we go any further, let's break down this command:
+:::{admonition}  What does `pip install -e .` do?
+:class: tip
+
+Let's break down `pip install -e .`
+
 
-`python -m pip install -e .` (e for editable)
 
 `pip install -e .` installs your package into the current active
-Python environment in **editable mode**. Installing your package in
+Python environment in **editable mode** (`-e`). Installing your package in
 editable mode, allows you to work on your code and then test the updates
 interactively in your favorite Python interface. One important caveat of editable mode is that every time you update your code, you may need to restart your Python kernel.
 
@@ -326,11 +335,47 @@ mode) you can use:
 
 - `python -m pip install . `
 
-:::{admonition}
+:::{admonition} Using `python -m` when calling `pip`
 :class: tip
+
 Above, you use`python -m` to call the version of pip installed into your current active environment.
 :::
 
+#### Look for pyospackage in your environment
+
+Once you have installed your package, you can view it in your current
+environment. If you are using `venv` or `conda`, `pip` list will allow you
+to see your current package installations.
+
+Note that because pyospackage is installed in editable mode (`-e`) pip will show you the past to where you package installation's code
+is.
+
+```bash
+$ pip list
+
+➜ pip list
+Package                       Version        Editable project location
+----------------------------- -------------- --------------------------------------------------------------
+...
+arrow                         1.2.3
+...
+...
+mamba                         1.1.0
+markdown-it-py                2.2.0
+MarkupSafe                    2.1.2
+matplotlib                    3.7.1
+msgpack                       1.0.5
+mypy                          1.4.1
+nox                           2021.10.1
+numpy                         1.24.2
+packaging                     23.0
+pandas                        1.5.3
+pyosPackage                   0.1.0          /Users/yourusername/path/here/pyosPackage
+...
+...
+...
+```
+
 ### 6. Test out your new package
 
 After installing your package, type “python” at the command prompt to start
@@ -402,19 +447,30 @@ level vs. what makes the most sense to keep in individual modules.
 
 You did it! You have now created a Python package that you can install into any Python environment. While there is still more to do, you have completed the first major step.
 
-In the next lesson you will:
+In the upcoming lessons you will:
 
-1. Flesh out metadata for your package within your `pyproject.toml` file.
-2. Learn how to build your learn how to build your package distribution files (**sdist** and **wheel**) and
-3. Learn how to publish your package on **test PyPI**.
+* add a [README file](2-add-readme.md) and [LICENSE ](3-add-license-file.md) to your package
+* [Add more metadata to your `pyproject.toml`](3-pyproject-toml.md) file to support PyPI publication.
+* [Learn how to build your your package distribution](4-publish-pypi.md) files (**sdist** and **wheel**) and
+publish to **test PyPI**.
+* Finally you will learn how to publish to conda-forge from PyPI.
 
 If you have a package that is ready for the mainstream user then
 you can also publish your package on PyPI.
 
 <!--
-### NOTES on this lesson
+### Lesson TODOs ###
+
+- Make sure they are using the clean dev envt  (i think that is mentioned)
+- Then define **all** = [“”] to avoid issues with pylance / mypy - still unclear regarding best practices for surfacing functions / methods. it seems like doing it here could lend them to bad practices of surfacing EVERYTHING. At the same time knowing how to surface say a specific class in a package can be useful especially if it's a big package and there is one core structure that a user will use a lot. Then again calling for a module isn't that hard>
+
+TODO: don't forget to have them add /dist to their .gitignore ...
 
-- Have something on pip and conda list to see the package in the envt…
-- Could create a clean envt using venv first and then conda
-- Then look at the list of installed things…
-- Then define **all** = [“”] to avoid issues with pylance / mypy -->
+https://hatch.pypa.io/latest/intro/#existing-project <- hatch will migrate from setup.py for you >
+
+FROM CAROL: Probably more accurate to say that the _init_.py  allows Python to recognize that the directory is a module that may be imported and used. A package can have multiple modules.
+
+- https://docs.python.org/3/tutorial/modules.html#packages -< link to this docs...>
+
+- i think it would be cool to have a package spectrum graphic. on the left is you just have code that you want to use, then the code can be installed, then you can build a package... etc etc so each tutorial would highlight a step across that spectrum
+-->

tutorials/2-add-readme.md

@@ -1,10 +1,13 @@
-# What goes into your Python package README.md file?
+# Add a README.md file to your Python package
+
+<!--
+TODO: add a screenshow of the pyospackage readme rendered in GitHub -->
 
 ```{button-link} https://www.pyopensci.org/python-package-guide/documentation/repository-files/readme-file-best-practices.html
 :color: primary
 :class: sd-rounded-pill float-left
 
-If you want to learn more about readme files, you can check out our guidebook reference: the art of readme files.
+Click here to learn more about best practices for creating README.md files.
 ```
 
 :::{admonition} TODOS
@@ -69,7 +72,7 @@ The README.md file is not only the landing page for your package, it also is lis
 1. **Badges:** Add any badges below the name of your file. if you don't have badges yet, that is ok. you'll have at least one once you [publish your package to PyPI](4-publish-pypi) in lesson 4.
 2. **Package overview:** Below the badges, add a section that provides an easy-to-understand overview of what your package does. Keep this section short and if you can avoid jargon or define technical words to make the description accessible to more people.
 3. **Installation Instructions:** Below the description add installation instructions. this might tell people how to install your package `pip install packagename` or `conda install`... You can come back and add this information after you publish to PyPI in lesson 4.
-4. **Additional Setup Information** In this section also briefly document (or link to documentation for) any additional setup that is required to use your package. This might include tokens or authentication information if it is applicable to your package. Or additional installations of tools such as GDAL, etc. Note: many packages wont need any additional information here!
+4. **Additional Setup Information** In this section also briefly document (or link to documentation for) any additional setup that is required to use your package. This might include tokens or authentication information if it is applicable to your package. Or additional installations of tools such as GDAL, etc. Note: many packages won't need any additional information here!
 5. **How to use your package:** Next add a brief demo of how to use your package. this might include a small code chunk that demonstrates importing and a quick call to functionality in your package.
 6. **Descriptive links to docs:** Unless you already have your documentation online, you can leave this section empty for now. this section would include links to tutorials or documentation get-started pages that will help your users understand how to use your package.
 7. **Community section:** this is where you'll add links to your contributing guide and code_of_conduct once you create those. You can also leave this empty for now.