Skip to content

Commit 288a94e

Browse files
lwasserlwasser
authored
enh(event): add Stanford workshop to website (#716)
1 parent c59f46b commit 288a94e

File tree

2 files changed

+329
-0
lines changed

2 files changed

+329
-0
lines changed

‎_posts/events/2025-09-02-stanford-ospo-how-to-create-a-python-package-workshop.md

Lines changed: 199 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,199 @@
1+
---
2+
layout: single
3+
title: "pyOpenSci Workshop: Create a Python package -- Stanford Open Source Program Office"
4+
excerpt: "Python packaging can be tricky to navigate. pyOpenSci will lead a pilot workshop on creating your first Python package. The goal of this workshop is to help scientists learn how to package and make code installable and shareable. Read on to learn more!"
5+
author: "pyopensci"
6+
event:
7+
start_date: "2025-10-02"
8+
location: Online
9+
cost: This workshop is paid through Stanford's membership with pyOpenSci.
10+
permalink: /events/pyopensci-stanford-create-python-package-workshop.html
11+
header:
12+
overlay_image: images/headers/pyopensci-sustainability.png
13+
categories:
14+
- events
15+
classes: wide
16+
type: "event"
17+
last_modified: 2025-09-02
18+
comments: true
19+
---
20+
21+
## Create a Python package: make your Python code easier to share and use
22+
23+
* **When:** Thursday, 2 October @ 10:00 AM Mountain Time // 9:00AM Pacific Time
24+
* **Where:** We will use the Spatial Chat platform to create a classroom-like learning experience.
25+
26+
This event, hosted in partnership with [Stanford’s Open Source Program
27+
Office](https://opensource.stanford.edu/), teaches participants best practices for packaging their Python code. You will learn how to build more reliable research tools and software development skills.
28+
29+
## Setup instructions
30+
31+
You can choose to work on your own machine during the workshop or use the GitHub Codespace we've set up for you. Codespaces include all the tools needed to create your first package—preinstalled and ready to go.
32+
33+
We encourage you to use GitHub Codespaces! If you prefer to install things locally, please do so **before** the workshop.
34+
35+
[Need help? Ask us on Discord.](https://discord.gg/m7RFFxnc)
36+
37+
### 1. Make sure you have a GitHub and Test PyPI account
38+
39+
Before the workshop, please create and log into the following accounts:
40+
41+
1. [Create a free GitHub account](https://www.github.com) if you don’t already have one.
42+
2. [Create a free account on Test PyPI](https://test.pypi.org/account/register) — we’ll use this to practice publishing packages.
43+
44+
45+
> <i class="fa-solid fa-lock"></i> **Important:** To follow along when we publish to Test PyPI, you must enable **two-factor authentication (2FA)** on your Test PyPI account. We strongly recommend doing this **before** the workshop!
46+
{: .notice .notice-important}
47+
48+
## 2a. Setup for working locally on your laptop
49+
50+
We recommend using GitHub Codespaces (see next section) to avoid issues with environment setup. However, if you prefer to work locally, please ensure your environment is set up and ready before the workshop.
51+
52+
If you're comfortable with Python environments, arrive with an environment that has:
53+
54+
- [Hatch installed](https://www.pyopensci.org/python-package-guide/tutorials/get-to-know-hatch.html#install-hatch)
55+
- [Copier installed](https://copier.readthedocs.io/en/stable/#installation)
56+
- You can install both via `pipx`, `uv`, pixi, or any preferred package manager.
57+
- [VS Code](https://code.visualstudio.com/download) (or any IDE you prefer for packaging)
58+
59+
> <i class="fa-solid fa-triangle-exclamation"></i> **Note:**
60+
* We strongly suggest that you visit GitHub.com and [Fork our SciPy 2025 workshop repository](https://github.com/pyOpenSci/pyopensci-scipy25-create-python-package) in case any issues arise with your local installation. This will ensure that you can follow along with us regardless of your environment setup.
61+
> * JupyterLab or Jupyter Notebook is **not ideal** for the packaging work we’ll be doing.
62+
{: .notice }
63+
64+
If you run into issues, please [join our Discord and ask for help](https://discord.gg/m7RFFxnc) before the workshop.
65+
66+
67+
## 2b. If you plan to use GitHub Codespaces (SUGGESTED)
68+
69+
We strongly recommend using our curated [GitHub Codespace](https://codespaces.new/pyOpenSci/pyopensci-workshop-create-python-package?quickstart=1), which can be found in your forked workshop repository. This workspace is already set up with:
70+
71+
* VSCode, copier, Hatch, and everything you need to create your first Python package successfully. Codespaces also allows you to easily commit your work during the workshop to your own forked GitHub repository.
72+
73+
**Before the workshop do the following**
74+
75+
* Go to GitHub.com and [Fork our Python package workshop repository](https://github.com/pyOpenSci/pyopensci-workshop-create-python-package)
76+
77+
<figure>
78+
<picture>
79+
<img src="{{ site.baseurl }}/images/github/codespaces/scipy-fork-repo.gif" alt=".">
80+
</picture>
81+
</figure>
82+
83+
* Launch the codespace before the workshop:
84+
85+
<i class="fa-solid fa-circle-info"></i> The initial spin-up for a codespace can take up to 15 minutes or longer. Once GitHub creates the cloud environment, it will be quicker to relaunch. Please do this before attending the workshop session.
86+
{: .notice }
87+
88+
To open your Codespace,
89+
90+
* Go to your forked SciPy 2025 workshop repository on GitHub,
91+
* Switch to a branch that you want to work on during the workshop,
92+
* Click the code drop-down button (where you'd find a link to clone a repo)
93+
* Click on the Codespaces tab in the drop-down.
94+
95+
Within the Codespaces tab you will see a button: <kbd style="background-color: #2da44e; color: white; padding: 2px 6px; border-radius: 4px;">
96+
Create codespace on main
97+
</kbd>. This button launches a Codespace from the currently active branch. It will default to the
98+
`main` branch if you haven't changed your branch in the repository.
99+
100+
The animated gif below walks you through how this works.
101+
102+
<figure style="width: 55%; margin: 0 auto;">
103+
<picture>
104+
<source srcset="{{ site.baseurl }}/images/github/codespaces/create-github-codespace-main.webp"
105+
type="image/webp">
106+
<img src="{{ site.baseurl }}/images/github/codespaces/create-github-codespace-main.png"
107+
alt="Create codespace on main button">
108+
</picture>
109+
</figure>
110+
111+
> <i class="fa-solid fa-circle-info"></i> To follow GitHub best practices, always create a new branch before making
112+
> changes to a repository, even if you own the repository. Avoid working directly on the `main` branch.
113+
114+
## <i class="fa-solid fa-cloud"></i> About GitHub Codespaces: Working in the cloud
115+
116+
## What is a codespace
117+
118+
GitHub Codespaces are cloud-based development environments that let you
119+
code directly in your browser—no local setup needed. They provide fully
120+
configured, container-based environments connected to your GitHub
121+
repository.
122+
123+
You can customize Codespaces with `.devcontainer` files to match your
124+
development setup. The Codespace for this workshop opens in Visual Studio
125+
Code by default, but you can configure it to use any IDE you prefer.
126+
127+
Learn more in the [GitHub Codespaces docs](https://docs.github.com/en/codespaces/overview).
128+
129+
Codespaces are free for up to 60 hours/month on GitHub’s free plan. Be sure
130+
to shut yours down after the workshop to conserve your allocated time.
131+
{: .notice}
132+
133+
> Codespaces are associated with your **personal GitHub account**, even if
134+
you open one from the pyOpenSci repository. The usage counts toward your
135+
own GitHub credits.
136+
{: .notice }
137+
138+
### View & manage open codespaces
139+
140+
Once you've opened a Codespace, you can return to it later without needing
141+
to start from scratch. GitHub will reuse the environment, making it launch
142+
significantly faster the second time.
143+
144+
If possible, resume the **same Codespace** you started in, rather than
145+
creating a new one in your fork. Read on to learn how to find and reopen a codespace.
146+
147+
<i class="fa-solid fa-link"></i>
148+
[View all active Codespaces associated with your account](https://github.com/codespaces)
149+
150+
{: .notice}
151+
> <i class="fa-solid fa-circle-info"></i> When you delete a Codespace, you're
152+
> ending the session, but the configuration remains available so you can
153+
> launch a new one anytime.
154+
> [Learn more in the GitHub docs](https://docs.github.com/en/codespaces/developing-in-a-codespace/stopping-and-starting-a-codespace)
155+
156+
### How to relaunch a codespace
157+
158+
To relaunch a Codespace:
159+
160+
1. Go to your fork of the workshop repository.
161+
2. Click the **Code** dropdown (same as when you first created the Codespace).
162+
3. Select the **Codespaces** tab to view existing environments.
163+
4. Select the codespace that you want to resume from the list (see image below).
164+
165+
As you can see in the animated gif below, GitHub codespaces always have fun names.
166+
167+
<figure>
168+
<picture>
169+
<img src="{{ site.baseurl }}/images/github/codespaces/reopen-codespace.gif"
170+
alt="GIF showing how to reopen a GitHub Codespace">
171+
</picture>
172+
</figure>
173+
174+
<div class="notice" markdown="1">
175+
176+
<i class="fa-solid fa-users-line"></i> Connect with us!
177+
{: .header }
178+
179+
There are many ways to get involved if you're interested!
180+
181+
* If you read through our lessons and want to suggest changes, open an issue in our [lessons repository here](https://github.com/pyOpenSci/lessons)
182+
* [Volunteer to be a reviewer for pyOpenSci's software review process](https://forms.gle/GHfxvmS47nQFDcBM6)
183+
* [Submit a Python package to pyOpenSci for peer review](https://www.pyopensci.org/software-peer-review/how-to/author-guide.html#submit-your-package-for-peer-review)
184+
* [Donate to pyOpenSci](https://give.communityin.org/pyopensci_2024) to support scholarships for future training events and the development of new learning content.
185+
* Check out our [volunteer page](/volunteer.html) for other ways to get involved.
186+
187+
You can also:
188+
189+
* Keep an eye on our [events page](/events.html) for upcoming training events.
190+
191+
Follow us on social platforms:
192+
193+
* [<i class="fa-brands fa-mastodon" style="color:#81c0aa;"></i> Mastodon](https://fosstodon.org/@pyopensci)
194+
* [<i class="fa-solid fa-cloud" style="color:#81c0aa;"></i> Bluesky](https://bsky.app/profile/pyopensci.bsky.social)
195+
* [<i class="fa-brands fa-linkedin" style="color:#81c0aa;"></i> LinkedIn](https://www.linkedin.com/company/pyopensci)
196+
* [<i class="fa-brands fa-github" style="color:#81c0aa;"></i> GitHub](https://github.com/pyOpenSci)
197+
198+
If you are on LinkedIn, check out and [subscribe to our newsletter, too](https://www.linkedin.com/newsletters/7179551305344933888/?displayConfirmation=true).
199+
</div>

‎_posts/events/2025-10-02-workshop-document-your-package.md

Lines changed: 130 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,130 @@
1+
---
2+
layout: single
3+
title: "Build Documentation That Gets Used: A 2-Hour Interactive Workshop for Python Package Maintainers"
4+
excerpt: "Stop writing documentation that nobody reads. Learn the strategic framework behind great documentation and walk away with templates, checklists, and a clear plan to transform your package's documentation."
5+
author: "pyopensci"
6+
event:
7+
start_date: "2025-11-06"
8+
location: Online
9+
permalink: /events/documentation-workshop.html
10+
header:
11+
overlay_image: images/headers/pyopensci-sustainability.png
12+
categories:
13+
- events
14+
classes: wide
15+
type: "event"
16+
last_modified: 2025-09-02
17+
comments: true
18+
---
19+
20+
## Build Documentation That Gets Used: A 2-Hour Interactive Workshop for Python Package Maintainers
21+
22+
* **When:** Thursday, 6 November 2025
23+
* **Where:** Interactive webinar with live demos
24+
* **Cost:** $149 (Early Bird) | $199 (Regular)
25+
* Student:
26+
27+
Your Python package deserves documentation that works as hard as your code. In this hands-on workshop, you'll learn the strategic framework behind great documentation and walk away with templates, checklists, and a clear plan to transform your package's documentation.
28+
29+
This workshop is part of pyOpenSci's commitment to building better research software through improved documentation practices. Whether you're a seasoned maintainer or new to packaging, you'll gain practical tools to create documentation that actually helps your users succeed.
30+
31+
### Workshop Structure
32+
33+
**Part 1: Documentation Strategy (30 minutes)**
34+
35+
- <i class="fas fa-users"></i> User vs Contributor Framework - Finally understand who needs what
36+
- <i class="fas fa-clipboard-list"></i> Documentation Planning Worksheet - Strategic approach to content planning
37+
- <i class="fas fa-search"></i> Live Package Audit - See how to evaluate existing documentation
38+
39+
**Part 2: Build Your User Documentation (30 minutes)**
40+
41+
- <i class="fas fa-decision"></i> 5-Minute Tool Decision Framework - MkDocs vs Sphinx made simple
42+
- <i class="fas fa-check-square"></i> User Documentation Checklist - Never miss critical content again
43+
- <i class="fas fa-cogs"></i> Sphinx Setup Walkthrough - Using pyOpenSci's proven template
44+
- <i class="fas fa-paint-brush"></i> Customization Demo - Make it yours
45+
46+
**Break (10 minutes)**
47+
48+
**Part 3: Essential Contributor Documentation (30 minutes)**
49+
50+
- <i class="fas fa-user-friends"></i> Contributor Documentation Checklist - What contributors actually need
51+
- <i class="fas fa-eye"></i> Live Audit with Contributor Lens - See the difference in perspective
52+
- <i class="fas fa-handshake"></i> Community Contribution Processes - Set clear expectations
53+
54+
**Part 4: Get Your Docs Online (20 minutes)**
55+
56+
- <i class="fas fa-cloud"></i> Hosting Decision Framework - GitHub Pages vs Read the Docs
57+
- <i class="fas fa-question-circle"></i> Q&A Session - Get your specific questions answered
58+
59+
### Why attend
60+
61+
- <i class="fa-solid fa-lightbulb"></i> Learn the strategic framework behind documentation that gets used
62+
- <i class="fa-solid fa-tools"></i> Get production-ready templates and checklists you can use immediately
63+
- <i class="fa-solid fa-users"></i> Understand the critical difference between user and contributor documentation
64+
- <i class="fa-solid fa-rocket"></i> See live demos of documentation setup and customization
65+
- <i class="fa-solid fa-graduation-cap"></i> Learn from pyOpenSci's experience reviewing hundreds of packages
66+
67+
### Perfect for you if...
68+
69+
- <i class="fas fa-check"></i> You maintain a Python package that people struggle to use
70+
- <i class="fas fa-check"></i> You spend too much time answering the same questions over and over
71+
- <i class="fas fa-check"></i> Your documentation exists but nobody seems to find what they need
72+
- <i class="fas fa-check"></i> You want contributors but they don't know how to get started
73+
- <i class="fas fa-check"></i> You're tired of guessing what documentation to write
74+
75+
### What you'll walk away with
76+
77+
- <i class="fas fa-gift"></i> **Documentation Strategy Template** - Reusable planning framework
78+
- <i class="fas fa-gift"></i> **User & Contributor Checklists** - Never miss important content
79+
- <i class="fas fa-gift"></i> **pyOpenSci Sphinx Template** - Production-ready starter
80+
- <i class="fas fa-gift"></i> **Decision Frameworks** - Tool selection made easy
81+
- <i class="fas fa-gift"></i> **Workshop Recording** - Reference it anytime
82+
83+
### Your instructor
84+
85+
**[Instructor Name]** brings [X years] of experience in scientific Python packaging and has helped [X] packages improve their documentation through pyOpenSci's peer review process. As [title/role], they understand both the technical and community aspects of great documentation.
86+
87+
### Early Bird Pricing
88+
89+
**Early Bird:** $149 (Save $50!)
90+
91+
**Regular Price:** $199
92+
93+
*Early bird pricing ends [date]*
94+
95+
*Limited to 50 participants for maximum interaction*
96+
97+
### Refund Policy
98+
99+
Full refund available up to 24 hours before the workshop. We want you to be completely satisfied with your learning experience.
100+
101+
<div class="notice" markdown="1">
102+
103+
<i class="fa-solid fa-users-line"></i> Connect with us!
104+
{: .header }
105+
106+
Ready to transform your package's documentation?
107+
108+
* **Register:** [REGISTER BUTTON LINK]
109+
* **Questions:** [contact email]
110+
* **Community:** Join our [Discourse forum](https://pyopensci.discourse.group/) for package-related discussions
111+
112+
This workshop is part of pyOpenSci's mission to build a more diverse and inclusive scientific Python community. We support the Python tools that scientists need to create open science workflows.
113+
114+
You can also:
115+
116+
* Check out our [Python Package Guide](https://www.pyopensci.org/python-package-guide/index.html) for comprehensive packaging guidance
117+
* [Submit a Python package to pyOpenSci for peer review](https://www.pyopensci.org/software-peer-review/how-to/author-guide.html#submit-your-package-for-peer-review)
118+
* Keep an eye on our [events page](/events.html) for upcoming training events
119+
120+
Follow us on social platforms:
121+
122+
* [<i class="fa-brands fa-discourse" style="color:#81c0aa;"></i> Discourse](https://pyopensci.discourse.group/)
123+
* [<i class="fa-brands fa-mastodon" style="color:#81c0aa;"></i> Mastodon](https://fosstodon.org/@pyopensci)
124+
* [<i class="fa-solid fa-cloud" style="color:#81c0aa;"></i> Bluesky](https://bsky.app/profile/pyopensci.bsky.social)
125+
* [<i class="fa-brands fa-linkedin" style="color:#81c0aa;"></i> LinkedIn](https://www.linkedin.com/company/pyopensci)
126+
* [<i class="fa-brands fa-github" style="color:#81c0aa;"></i> GitHub](https://github.com/pyOpenSci)
127+
128+
If you are on LinkedIn, check out and [subscribe to our newsletter, too](https://www.linkedin.com/newsletters/7179551305344933888/?displayConfirmation=true).
129+
130+
</div

0 commit comments

Comments
 (0)