pyOpenSci is devoted to building diverse, supportive community around the Python open source tools that drive open science. We do this through:

• open peer review
• mentorship
• training

pyOpenSci is an independent organization, fiscally sponsored by Community Initiatives.

This repository contains the source files for the pyOpenSci Python packaging guide.

Our guidebook is built with Sphinx which is a documentation tool and uses the pydata-sphinx-theme.

The easiest way to build our documentation is to use the nox automation tool, a tool for quickly building environments and running commands within them.

Using nox ensures that your environment has all the dependencies needed to build the documentation.

To build, follow these steps:

1. Install nox

   $ python -m pip install nox

2. Build the documentation:

   $ nox -s docs

This should create a local environment in a .nox folder, build the documentation (as specified in the noxfile.py configuration), and the output will be in _build/html.

To build live documentation that updates when you update local files, run the following command:

$ nox -s docs-live

When building for release, the docs are built multiple times for each translation, but translations are only included in the production version of the guide after some completion threshold.

The sphinx build environment is controlled by an environment variable SPHINX_ENV

• when SPHINX_ENV=development (default), sphinx assumes all languages are built, and includes them in the language selector
• when SPHINX_ENV=production, only those languages in release_languages (set in conf.py) are built and included in the language selector.

Most of the time you should not need to set SPHINX_ENV, as it is forced by the primary nox sessions intended to be used for release or development:

SPHINX_ENV=development

• docs-live - autobuild english
• docs-live-lang - autobuild a single language
• docs-live-langs - autobuild all languages

SPHINX_ENV=production

• build-test - build all languages for production

We welcome and issues and pull requests to improve the content of this guide. If you'd like to see an improvement, please open an issue.

Thanks goes to these wonderful people (emoji key):

Akhil Krishna R 🤔👀	Alexandre Batisse 📖🎨	Ana 🌍	Ananthu C V 👀	Anderson Bravalheri 💻🎨	Ariane Sasso 📖🎨💻👀	Brianne Wilhelmi 💻👀
C. Titus Brown 💻👀	Cale Kochenour 💻👀	Carol Willing 👀🤔	Cheng H. Lee 💻👀	Chiara Marmo 💻🎨👀	Chris Holdgraf 💻👀	Daniel Chen 🤔👀
Daniel Possenriede 💻👀	Dave Hirschfeld 👀	David Nicholson 📖🎨✅	Eli Schwartz 💻🎨👀	Erik Welch 📖🎨	Felipe Moreno 👀💻🌍📖💬	Filipe 💻🎨
Frost Ming 💻👀	Han 💻👀	Henry Cuzco 💻👀🎨	Henry Schreiner 💻🎨👀	Hugo van Kemenade 💻👀	Inessa Pawson 💻👀✅	Isabel Zimmerman 💻👀
Ivan Ogasawara 💻👀✅	J. Steven Dodge 💻	Jackson Burns 💻👀✅	James Lamb 💻📖🌍	James Tocknell 💻👀	Jannis Leidel 💻👀	Jeremy Paige 💻👀✅🚧📖
Jesse Mostipak ✅	John Drake 💻👀	Jonny Saunders 💻🎨🤔💬️️️️♿️🚇	Joseph H Kennedy 💻👀	Juan Luis Cano Rodríguez 💻🎨👀	Karen Cranston 💻👀	Ken Seehart 💻👀
Kozo Nishida 👀🌍	Kyohei Sahara 💻👀	Lauren Moore 📖	Leah Wasser 📖🎨🤔💬	Malvika Sharan 🤔👀	Maria Knorps 💻👀	Marie Roald 💻🐛
Matt Hall 💻👀	Matthew Feickert 📖👀	Megan Sosey 💻👀	Melissa Weber Mendonça 💬	Michael Pilosov, PhD 👀	Mihai Maruseac 📖💻👀✅	Moritz E. Beber 💻✅
Naty Clementi 💻👀🌍📖	Neil Chue Hong 👀	Nick Murphy 💻👀	Ofek Lev 💻🎨👀✅	Olek 💻👀	Oriol Abril-Pla 💬	Pamphile Roy 📖🎨
Pat Tressel 💻👀	Patrick Byers 💻👀	Philipp A. 💻👀	Pradyun Gedam 💻🎨👀	Ralf Gommers 💻🎨👀	Randy Döring 💻👀	Revathy Venugopal 💻👀📖
Roberto Pastor Muela 💻👀🌍🤔	Ryan 💻👀	Sanket Kumar Kar 💻	Santiago Soler 💻👀	Simon 📖🎨	Sneha Yadav 💻👀	Stefan van der Walt 💻🎨👀
Stefanie Molin 💻👀	Stefano Rivera 👀	Tetsuo Koyama 💻👀📖🌍🤔️️️️♿️🚇📝	Tom Russell 💻👀✅📖	Trevor James Smith 💻👀	Tyler Bonnell 💻👀	Vaunty 💻👀
William F. Broderick ✅	Yngve Mardal Moe 💻👀	Zac Warham 🤔👀	Zack Weinberg 👀	h-vetinari 💻👀✅	hpodzorski-USGS 💻👀	jaimergp 💻👀✅
miguelalizo 💻👀📖	mrgah 💻👀	nyeshlur 💻👀	ruoxi 💻👀	Éric 💻👀	🇺🇦 Sviatoslav Sydorenko (Святослав Сидоренко) 👀

This project follows the all-contributors specification. Contributions of any kind welcome!