Add: readme file tutorial

Author: lwasser

tutorials/add-readme.md

@@ -0,0 +1,211 @@
+# Add a README file to your Python package
+
+In the previous lessons you learned:
+
+1. What a Python package is
+2. How to make your code installable and
+3. How to publish your package to (test) PyPI
+
+:::{admonition} Learning objectives
+
+In this lesson you will learn:
+
+1. How to add a **README.md** file to your package.
+2. What the core elements of a **README.md** file are.
+:::
+
+## What is a README file?
+
+The `README.md` file is a markdown file located at the root of your project directory that helps
+a user understand:
+
+- You package's name and what it does
+- The current development "state" of the package (through badges)
+- How to get started with using your package.
+- How to contribute to your package
+- How to cite your package
+
+Your **README.md** file is important as it is often the first thing that someone sees before they install your package. The README file also will be used to populate your PyPI landing page.
+
+Note that there is no required format for README files. This page simply outlines sections that we suggest you have in your README file.
+
+## Create a README.md file for your package
+
+It's time to add a `README.md` file to your project directory.
+
+### Step 0. Create a README file
+To get started, if you don't already have a README.md file in your project directory, create one.
+
+:::{tip}
+If you created your project directory from
+
+* a GitHub repository online
+* using `hatch init`
+
+Then you may already have a README.MD file in your project directory.
+:::
+
+<!-- If they use hatch init in the very first lesson -
+the readme will already be there-->
+
+### Step 1. Add package badges
+
+At the top of the `README.md` file, add the name of your package.
+
+### Step 2 - add badges to the top of your README file
+
+It's common for maintainers to add badges to the top of their README files. Badges allow you and your package users to track things like
+
+* Broken documentation and test builds
+* Versions of your package that are on PyPI and Conda.
+* Whether your package has been reviewed and vetted by an organization such as pyOpenSci and/or JOSS.
+
+If you have already published your package to pypi.org you can use [shields.io to create a package version badge](https://shields.io/badges/py-pi-version). This badge will dynamically update as you release new versions of your package to PyPI.
+
+If not you can leave the top empty for now and add badges to your README at a later point as they make sense for your package.
+
+### Step 3 - Add a description of what your package does
+
+Below the badges (if you have them), add a section of text
+that provides an easy-to-understand overview of what your
+package does.
+
+* Keep this section short.
+* Try to avoid jargon.
+* Define technical terms that you use to make the description accessible to more people.
+
+Remember that the more people understand what your package does, the more people will use it.
+
+### Step 4 - Add package installation instructions
+
+Next, add instructions that tell users how to install your package.
+
+For example, can they use pip to install your package?
+`pip install packagename`
+
+or conda?
+
+`conda install -c conda-forge packagename`.
+
+If you haven't yet published your package to pypi.org then
+you can skip this section and come back and add these
+instructions later.
+
+### Step 5 - Any additional setup
+
+In some cases, your package users may need to manually
+install other tools in order to use your package. If that
+is the case, be sure to add a section on additional setup
+to your README file.
+
+Here, briefly document (or link to documentation for) any
+additional setup that is required to use your package.
+This might include:
+
+* authentication information if it is applicable to your package.
+* additional tool installations such as GDAL.
+
+:::{note}
+Many packages won't need this section in their README. In that case you can always skip this section!
+:::
+
+
+### Step 6 - Add a get started section
+
+Next add a getting started section that shows how to use your package. This
+section should include a small code chunk that demonstrates importing and using
+some of the functionality in your package.
+
+For the pyosPackage, a short get started demo might look like this:
+
+```python
+>>> from pyospackage.add_numbers import add_num
+>>> add_num(1, 2)
+3
+``````
+
+Or it could simply be a link to a get started tutorial that you have created. If
+you don't have this yet, you can leave it empty for the time being.
+
+This would
+also be a great place to add links to any tutorials that you have created that
+help users understand how to use your package for common workflows.
+
+
+### Step 7 - Community section
+
+The community section of your README file is a place to include information for users who may want to engage with your project. This engagement will likely happen either on a platform like GitHub or GitLab.
+
+In the community section, you will add links to your contributing guide
+and `CODE_OF_CONDUCT.md`. You will add a [`CODE_OF_CONDUCT.md` file in the next lesson](add-license-coc).
+
+As your package grows you may also have a link to a development guide that contributors and your maintainer team will follow.
+
+
+
+### Step 8 - Citation & License information
+
+Finally it is important to let users know
+
+1. how to cite your package and
+2. what the license is.
+
+You will create a license file for your package in this lesson.
+
+Your finished `README.md` file should look something like this:
+
+````markdown
+# pyOpenSci-package
+
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.8365068.svg)](https://doi.org/10.5281/zenodo.8365068)
+[![pyOpenSci](https://tinyurl.com/y22nb8up)](https://github.com/pyOpenSci/software-review/issues/115)
+
+## What packagename does
+
+Short description here using non technical language that describes what your package does.
+
+## How to install
+
+<todo - when i add more to the pyos package this can use that readme>
+To install this package... use:
+
+`pip install packagename`
+
+## OPTIONAL - if you have additional setup instructions add them here. if not, skip this section.
+
+## Get started using packagename
+
+Here add a quick code demo showing a user how to use the package after it is installed.
+
+```
+from packagename.module import xmethod
+
+a = xmethod.dosomething(var1, var2)
+
+```
+
+You can also add any links to this section to tutorials in your documentation.
+
+## Community
+
+Add information here about contributing to your package. Be sure to add links to your `CODE_OF_CONDUCT` file and your development guide. For now this section might be empty. You can go back and fill it in later.
+
+## How to cite packagename
+
+citation information here
+````
+
+## <i class="fa-solid fa-hands-bubbles"></i> Wrap up
+
+It's important to consider the information that a new user or contributor might
+need when creating your `README.md` file. While there is no perfect template,
+above is a set of recommendations as you are just getting started. You may find
+the need for other elements to be added to this file as you further develop your
+package and as a community begins to use your package.
+
+In the [next lesson](add-license-coc), you will add a LICENSE file to
+your Python package. A license file is critical as it tells users
+how they legally can (and can't use your package). It also:
+
+* Builds trust with your users
+* Discourages misuse of your package and associated code

tutorials/intro.md

@@ -33,13 +33,21 @@ Get to know Hatch <get-to-know-hatch>
 
 :::{toctree}
 :hidden:
-:caption: Python Packaging 101
+:caption: Create a Python package
 
 What is a Python package? <self>
 Make your code installable <1-installable-code>
 Publish to PyPI <publish-pypi>
 :::
 
+
+:::{toctree}
+:hidden:
+:caption: Project Metadata
+
+Add README file <add-readme>
+:::
+
 :::{admonition} Learning Objectives
 
 This lesson introduces you to the basic components of a Python package.
@@ -301,7 +309,7 @@ publish it in a repository such as **PyPI** or **conda-forge**.
 :::{todo}
 The links below won't work until those lessons (which are written) are published.
 
-Learn [how to publish your package to PyPI in this tutorial.](6-publish-pypi.md)
+Learn [how to publish your package to PyPI in this tutorial.](publish-pypi)
 :::