Enh: add initial tutorial drafts

conf.py

@@ -74,13 +74,15 @@
         },
     ],
     "logo": {
-        "text": "Python Package Guide",
+        "text": "Python Packaging",
         "image_dark": "logo-dark-mode.png",
         "image_light": "logo-light-mode.png",
         "alt_text": "pyOpenSci Python Package Guide. The pyOpenSci logo is a purple flower with pyOpenSci under it. The o in open sci is the center of the flower",
     },
-    "header_links_before_dropdown": 3,
+    "header_links_before_dropdown": 4,
     "use_edit_page_button": True,
+    "show_nav_level": 2,
+    "navigation_depth": 3,
     "show_toc_level": 1,
     # "navbar_align": "left",  # [left, content, right] For testing that the navbar items align properly
     "github_url": "https://github.com/pyopensci/python-package-guide",

index.md

@@ -1,4 +1,92 @@
-# pyOpenSci Python Open Source Package Development Guide
+# pyOpenSci Python Package Guide
+
+Demystifying the Python packaging ecosystem with recommendations for
+scientists to follow.
+
+::::{grid} 2
+:reverse:
+
+:::{grid-item}
+:columns: 4
+:class: sd-m-auto
+
+:::
+
+:::{grid-item}
+:columns: 8
+:class: sd-fs-3
+
+```{button-link} https://www.pyopensci.org/about-peer-review/
+:color: primary
+:class: sd-rounded-pill float-left
+Learn about our open peer review process
+```
+
+```{only} html
+![GitHub release (latest by date)](https://img.shields.io/github/v/release/pyopensci/python-package-guide?color=purple&display_name=tag&style=plastic)
+[![](https://img.shields.io/github/stars/pyopensci/python-package-guide?style=social)](https://github.com/pyopensci/contributing-guide)
+[![DOI](https://zenodo.org/badge/556814582.svg)](https://zenodo.org/badge/latestdoi/556814582)
+```
+
+:::
+::::
+
+<!-- I think this is the end of the header - below begins the next grid-->
+
+::::{grid} 1 1 2 2
+:class-container: text-center
+:gutter: 3
+
+:::{grid-item-card}
+:link: tutorials/intro
+:link-type: doc
+
+✨ Just getting started? ✨
+^^^
+
+If you are new to packaging or just want an opinionated, end-to-end
+way to create a package, check out our tutorials
+:::
+
+:::{grid-item-card}
+:link: package-structure-code/intro
+:link-type: doc
+
+✨ Want to better understand the ecosystem? ✨
+^^^
+If you are looking to better understand the tools and options in the
+diverse Python packaging ecosystem, then this section is for you. Here
+you will learn about the most commonly used tools in the ecosystem and
+also tools and processes that our community recommends.
+:::
+
+:::{grid-item-card}
+:link: CONTRIBUTING
+:link-type: doc
+
+✨ Want to contribute? ✨
+^^^
+We welcome contributions to this guide. Learn more about how you can
+contribute.
+:::
+::::
+
+## About
+
+This guide is designed to guide you through your Python packaging experience.
+
+It does several things:
+
+1. it provides an overview of the various elements of a python package
+2. it provides and overview of tools to create python packages and recommends best practices
+3. it provides end-to-end tutorials to get you on your way creating a package
+
+```{toctree}
+:hidden:
+:caption: Tutorials
+
+Tutorials  <tutorials/intro>
+```
 
 ```{toctree}
 :hidden:
@@ -23,22 +111,14 @@ Packaging <package-structure-code/intro>
 CI & Tests  <ci-and-testing/intro>
 ```
 
-<!-- Github community standards
-https://github.com/pyOpenSci/python-package-guide/community -->
-
-## Welcome, Python open source enthusiast!
-
-Here you will find guidelines for what we look for in your scientific
-Python package when reviewing. You will also find best practice recommendations and curated lists of community resources surrounding packaging and package documentation.
-
 ### pyOpenSci's packaging goals
 
 Our goal is to help the
 community make decisions around how to create scientific Python packages. We are working towards a shared vision of packaging that helps users better understand where to start.
 
 ### How this guide is created
 
-This guide is created by pyOpenSci through an extensive review process. Each page in the guide has been reviewed by experts in the broader Python packaging landscape including people from :
+This guide is created by pyOpenSci through an extensive review process. Each page in the guide has been reviewed by experts in the broader Python packaging landscape including people from:
 
 - conda & conda-forge
 - the python packaging authority

tutorials/1-create-environment.md

@@ -0,0 +1,125 @@
+# Create a Python development environment
+
+To get started working on your package you will want to create a
+shiny new Python environment. While this is not required, we strongly
+encourage you to create an environment that is dedicated to your Python
+package.
+
+Below you learn how to create an environment using both:
+
+- venv - which is the environment manager that comes with Python
+- conda - an environment manager that is tailored to the scientific ecosystem.
+
+There is no right or wrong environment option. Chose the option that you prefer.
+
+:::{tip}
+If you are a scientist and you work with spatial data or are creating a package that is not pure python, you may prefer conda. But in general pick
+the environment tool that works best for you.
+:::
+
+## Create a package development environment Using venv
+
+venv comes with any Python installation. Thus, you may find it easy to
+use it for your package development needs. Instructions on how to create a
+new development environment using venv are below.
+
+1. **Open Terminal or Command Prompt:**
+
+   - Open your terminal or command prompt.
+
+2. **Navigate to the Project Directory:**
+
+   ```bash
+   cd path/to/your/project-directory
+   ```
+
+3. **Create a Virtual Environment:**
+
+   ```bash
+   python -m venv pyos-dev
+   ```
+
+4. **Activate the Virtual Environment:**
+
+   - **On Windows:**
+
+   ```bash
+   pyos-dev\Scripts\activate
+   ```
+
+   - **On macOS/Linux:**
+
+   ```bash
+   source pyos-dev/bin/activate
+   ```
+
+5. **Install/Manage Dependencies:**
+
+   ```bash
+   pip install package_name
+   ```
+
+6. **Work on Your Project:**
+
+7. **Deactivate the Virtual Environment:**
+   ```bash
+   deactivate
+   ```
+
+### Additional Notes:
+
+- Remember to reactivate the environment each time you want to work on your project.
+- To delete the virtual environment, delete the `pyos-dev` folder.
+
+## Creating a PyOS-Dev Environment Using Conda
+
+Some scientists prefer to use a conda environment for their package development. If that is your preference, follow the steps below.
+
+1. **Create an Environment File (`env.yml`):**
+
+   - Use a text editor to create a file named `env.yml` and specify the required packages in the YAML format. For instance:
+
+   ```yaml
+   name: pyos-dev
+   channels:
+     - defaults
+   dependencies:
+     - python=3.8
+     - package_name1
+     - package_name2
+     # Add other necessary packages
+   ```
+
+2. **Create the Conda Environment from the Environment File:**
+
+   - Open your terminal or command prompt.
+
+   ```bash
+   conda env create -f env.yml
+   ```
+
+   This command will read the `env.yml` file and create a Conda environment named `pyos-dev` with the specified packages.
+
+3. **Activate the Conda Environment:**
+
+   - Once the environment is created, activate it.
+   - **On Windows:**
+
+   ```bash
+   conda activate pyos-dev
+   ```
+
+   - **On macOS/Linux:**
+
+   ```bash
+   source activate pyos-dev
+   ```
+
+4. **Work on Your Project:**
+   - You're now working in the `pyos-dev` Conda environment.
+
+### Additional Notes:
+
+- Remember to activate the environment each time you want to work on your project.
+- To deactivate the environment, use `conda deactivate`.
+- To delete the environment, you can use `conda env remove -n pyos-dev`.