pyOpenSci · lwasser · Nov 13, 2023 · Nov 22, 2023 · Dec 5, 2023
diff --git a/_static/pyos.css b/_static/pyos.css
@@ -42,6 +42,25 @@ html, body {
     }
 }
 
+/* Make sure the header nav is centered */
+.navbar-header-items .me-auto, .me-auto .navbar-header-items__center {
+    margin-left: auto!important;
+    margin-right: auto!important;
+}
+
+/* custom fonts */
+
+html, body {
+    font-size: 1.02rem;
+}
+
+/* Allow the center content to expand to wide on wide screens */
+@media (min-width: 960px){
+.bd-page-width {
+    max-width: min(100%, 1600px)!important;
+    }
+}
+
 /* Make sure the header nav is centered  - not sure why it's not overriding*/
 .navbar-header-items .me-auto, .me-auto .navbar-header-items__center {
     margin-left: auto!important;
@@ -52,6 +71,7 @@ html, body {
 
 html, body {
     font-size: 1.02rem;
+    font-family: 'Poppins', sans-serif!important;
 }
 
 body p {

diff --git a/_templates/header.html b/_templates/header.html
@@ -0,0 +1,7 @@
+<!-- custom head content-->
+
+<link rel="preconnect" href="https://fonts.googleapis.com">
+<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+<link href="https://fonts.googleapis.com/css2?family=Itim&family=Poppins:wght@300;400;600&display=swap" rel="stylesheet">
+
+<!-- END custom head content -->
diff --git a/_templates/nav.html b/_templates/nav.html
@@ -0,0 +1 @@
+<p>this is a test does it work?</p>
diff --git a/images/packaging-workflow.png b/images/packaging-workflow.png
diff --git a/images/tutorials/code-to-script-diagram.png b/images/tutorials/code-to-script-diagram.png
diff --git a/images/tutorials/github-new-repo.png b/images/tutorials/github-new-repo.png
diff --git a/images/tutorials/github-repo-sidebar.png b/images/tutorials/github-repo-sidebar.png
diff --git a/images/tutorials/packaging-steps.png b/images/tutorials/packaging-steps.png
diff --git a/images/tutorials/publish-package.png b/images/tutorials/publish-package.png
diff --git a/images/tutorials/toolbox.jpg b/images/tutorials/toolbox.jpg
diff --git a/images/tutorials/view-license-github.png b/images/tutorials/view-license-github.png
diff --git a/tutorials/2-add-readme.md b/tutorials/2-add-readme.md
@@ -0,0 +1,171 @@
+# Add a README file to your Python package
+
+<!--
+TODO:
+* add link -
+
+* add a screenshot of the pyospackage readme rendered in GitHub
+* this series would be great if there was a graphic with all of the steps. and each was highlighted at the top of the page.
+*  **TODO:** we didn't ask them to put code into a src dir in the previous lesson? probably good to do that.
+
+ -->
+
+
+
+In the [previous lesson](1-installable-code.md) you:
+
+1. Learned how create the basic structure of a Python package and
+2. How to make your code `pip` installable.
+
+:::{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.
+
+:::
+
+
+::::{grid} 2
+
+:::{grid-item}
+:columns: 4
+:class: sd-m-auto
+
+```{button-link} https://www.pyopensci.org/python-package-guide/documentation/repository-files/readme-file-best-practices.html
+:color: secondary
+:class: sd-rounded-pill float-left
+
+<i class="fa-solid fa-clover"></i> pyOpenSci README file overview guide.
+```
+
+:::
+
+:::{grid-item}
+:columns: 4
+:class: sd-m-auto
+
+```{button-link} https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-readmes
+:color: secondary
+:class: sd-rounded-pill float-left
+
+<i class="fa-brands fa-github"></i> Guide: about `README.md` files
+```
+:::
+
+
+:::{grid-item}
+:columns: 4
+:class: sd-m-auto
+
+empty
+:::
+::::
+
+
+
+## What is a README file?
+
+The `README.md` file is a file located at the root of your GitHub or GitLab repo that helps
+a user understand:
+
+- You package's name and what it does
+- The current development "state" of the package (through badges)
+- How to use your package: this might include a short get started demo that shows someone how to import and quickly use your package. Or it could be a set of links to get started tutorials in your documentation.
+- How to contribute to your package: normally you would link to a `CONTRIBUTING.md` and `CODE_OF_CONDUCT.md` file in this part of the readme
+- 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. So it's good to create this file before you publish to PyPI.
+
+### GitHub highlights your README file as a core file
+
+Every GitHub repository landing page has a right hand side bar that lists and links to elements of your package including:
+
+- A link to your Readme file
+- Your license
+- Number of Stars and
+- Number of Forks
+
+:::{figure-md} github-sidebar
+<img src="../images/tutorials/github-repo-sidebar.png" alt="Add alt " width="500px">
+
+The README.md file is not only the landing page for your package, it also is listed as one of the core elements describing your package repository on GitHub.
+:::
+
+## Create a README.md file for your package
+
+- To get started if it doesn't already exist, create a file called `README.md` in your local GitHub repository.
+
+- At the top of the `README.md` file, add the name of your package (and a logo if you have one). It's fine if you don't have a logo.
+
+- Next add the following sections to your `README.md` file
+
+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](6-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 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.md` once you create those. You can also leave this empty for now. You will add a [`CODE_OF_CONDUCT.md` file in the next lesson](4-add-license-file.md).
+8. **Citation information:** also leave this empty for now. You can learn how to setup your repository with zenodo to make it citable in [this lesson](extras/2-connect-repo-to-zenodo.md).
+
+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
+```
+
+## Wrapping up
+
+It's important to consider the information that a new user or contributor might
+need when creating your `README.md` file. 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.
+
+For instance, as you add get-started tutorials to your documentation, you can
+link directly to those in the README file.
+
+In the [next lesson](4-add-license-file.md), you will add a LICENSE file to
+your Python package repository. 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
diff --git a/tutorials/4-add-license-file.md b/tutorials/4-add-license-file.md
@@ -0,0 +1,110 @@
+# Add a LICENSE & CODE_OF_CONDUCT to your Python package
+
+In the [previous lesson](2-add-readme) you created a basic `README.md` file for your scientific Python package's repository.
+
+:::{admonition} Learning objectives
+:class: tip
+
+In this lesson you will learn:
+
+1. How to select and add a `LICENSE` file to your package repository with a focus on the GitHub interface.
+2. How to add a `CODE_OF_CONDUCT` file to your package repository.
+3. How you can use the Contributors Covenant website to add generic language as a starting place for your `CODE_OF_CONDUCT`.
+:::
+
+<!--
+NOTE: in this case if they add a license on github they will want to pull those changes down.
+
+So in the previous lesson we should have them add the readme, then commit the readme and push to github main branch.
+
+TODO: be sure to ask them to add a link to both their license and their COC in this lesson -->
+
+## Add a LICENSE file to your repository
+
+A license file is a document that contains legal language about how users are allowed to use and reuse your software. Generally, we suggest that you select a permissive license that accommodates the other most commonly used licenses in the scientific Python ecosystem (MIT and BSD-3).
+
+[Click here for an overview of license recommendations for the scientific Python ecosystem](../documentation/repository-files/license-files.html#use-open-permissive-licenses-when-possible)
+
+### Where should the license file live & how do you add it?
+
+Your `LICENSE` file should be placed at the root of your package's repository.
+
+There are two ways to add a license file:
+
+1. When you create a new repository on GitHub, it will ask you if you wish to add a `LICENSE` file at that time.
+2. You can also always go back and add a `LICENSE` file to your repo.
+
+### How to add a LICENSE to your GitHub repository
+
+If you don't already have a `LICENSE` file in your repo, add one now.
+
+* Follow the instructions to select and add a license to your repository on the [<i class="fa-brands fa-github"></i> GitHub LICENSE page]( https://docs.github.com/en/communities/setting-up-your-project-for-healthy-contributions/adding-a-license-to-a-repository) .
+* Once you have added your LICENSE file, be sure to sync your git local repository with the repository on GitHub.com. This means running `git pull` to update your local branch.
+
+:::{admonition} An overview of LICENSES in the scientific Python ecosystem
+:class: note
+
+In the pyOpenSci [packaging guidebook](../documentation/repository-files/license-files.html), we provide an overview of license in the scientific Python ecosystem. We review why license files are important, which ones are most commonly used for scientific software and how to select the correct license.
+
+If you want a broad overview of why licenses are important for protecting open source software, [check out this blog post that overviews the legal side of things.](https://opensource.guide/legal/#just-give-me-the-tldr-on-what-i-need-to-protect-my-project)
+:::
+
+:::{figure-md} github-new-repo
+<img src="../images/tutorials/github-new-repo.png" alt="Add alt " width="500px">
+
+When you initially create a repository on GitHub you can add a license
+through their interface.
+:::
+
+
+:::{figure-md} view-license
+<img src="../images/tutorials/view-license-github.png" alt="Add alt " width="500px">
+
+You can also view an overview of the license on GitHub if you view it in the GitHub interface.
+:::
+
+Next, you will add a `CODE_OF_CONDUCT` file to your repository.
+
+## Add a CODE_OF_CONDUCT file to your repo
+
+A `CODE_OF_CONDUCT` file is critical to supporting your community as
+grows around your project. The `CODE_OF_CONDUCT` is important as it:
+1. Establishes guidelines for how users and contributors interact with each other and you in your software repository.
+2. Identifies negative behaviors that you don't want in your interactions. In extreme situations, you can use this language as a moderation tool that can be references when moderating tense conversations.
+
+If you are unsure of what language to add to your `CODE_OF_CONDUCT`
+file, we suggest that you adopt the [contributor covenant language](https://www.contributor-covenant.org/version/2/1/code_of_conduct/) as a starting place.
+
+[![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-2.1-4baaaa.svg)](#)
+
+* Add a `CODE_OF_CONDUCT.md` file to your repository if it doesn't
+already exist.
+* Visit the contributor covenant website and [add the language here to the file.](https://www.contributor-covenant.org/version/2/1/code_of_conduct/) [A markdown version can be found here.](https://www.contributor-covenant.org/version/2/1/code_of_conduct/code_of_conduct.md)
+
+
+:::{admonition} Additional Code of Conduct resources
+:class: note
+
+* [<i class="fa-brands fa-github"></i> Guide: `CODE_OF_CONDUCT.md` files](https://docs.github.com/en/communities/setting-up-your-project-for-healthy-contributions/adding-a-code-of-conduct-to-your-project)
+* [pyOpenSci package guide `CODE_OF_CONDUCT.md` overview](https://www.pyopensci.org/python-package-guide/documentation/repository-files/code-of-conduct-file.html)
+
+:::
+
+## <i class="fa-solid fa-arrows-rotate"></i> Sync your LICENSE & COC files to GitHub / GitLab
+
+It's time to sync your repository to ensure that all of the files that you have added locally are on GitHUB.com and all of the files that have been added on GitHub are local.
+
+* If you added a `LICENSE` file to GitHub using the GitHub online interface, be sure to pull it down locally using `git pull`.
+* Similarly be sure to pull or push your newly added `CODE_OF_CONDUCT` to your GitHub repository if you created that file locally.
+
+## <i class="fa-solid fa-hands-bubbles"></i> Wrap up
+
+In this lesson and the [last lesson](2-add-readme), you have now added:
+
+* `README` file
+* `LICENSE` file
+* `CODE_OF_CONDUCT` file
+
+These are core files that every scientific Python package should include. In the next lessons, you will:
+* [Flesh out your `pyproject.toml` file](5-pyproject-toml) which will support building and publishing your package on PyPI. and
+* You will learn how to [publish your package to PyPI](6-publish-pypi)!