DISCOVER-handbook

The NumFOCUS DISCOVER Handbook (Diverse & Inclusive Spaces and Conferences: Overall Vision and Essential Resources). A guide for organizing more diverse and inclusive events and conferences, produced by the NumFOCUS Diversity & Inclusion in Scientific Computing (DISC) Program, with support from the Moore Foundation.

If you are looking to read the book please visit https://discover-cookbook.numfocus.org/ for a live version of the book. This is the code that powers that website and is intended for maintainers and contributors.

Ways to contribute to this repository

The original body of work took place at a series of unconferences and various spurts of energy, today the DISCOVER-cookbook is a living project with numerous contributors. Because it is code to produce a book rather than code for a software library or application, it has different needs than typical open source software systems. Because of these unique needs, we separate various types of contributions:

Ideas, Questions, and Discussions

Please contribute ideas, questions, and discussions for content or enhancements over in the discussions tab.

Problems or Tracking of Work Items from Ideas, Questions, or Discussions

Please add issues on the GitHub issue tracker.

Content and Design

While content is the heart of the project, the quality of the content needs to remain high. Due to a high volume of generated text being submitted for review, content takes longer to review and approve. We value these contributions but just understand that it will take time to add. Please start an idea in the discussions, then move to making an issue once there is approval for the content to be added to the book. After that issue is made we feel free to open a pull request against the repository to begin the review process.

Bug fixes

For issues with other elements of the book, first make sure an issue is open and tracking can occur on the issue. Then open a a pull request.

Contribution Workflow

To contribute changes:

1. Fork the Repository: Click the "Fork" button at the top-right of this repository's GitHub page to create a copy in your account.

2. Clone Your Fork:

   git clone https://github.com/your-username/DISCOVER-Cookbook.git
   cd DISCOVER-Cookbook

3. Create a New Branch:

   git checkout -b your-branch-name

4. Make Changes:

   • Edit files in your preferred editor
   • Build and verify your changes locally using the build instructions below

5. Test Locally: Build the book and view your changes:

   jupyter-book build DISCOVER
   python -m http.server 8000 --directory DISCOVER/_build/html/

   Visit http://localhost:8000 in your browser to verify changes.

6. Commit and Push:

   git add .
   git commit -m "Description of your changes"
   git push origin your-branch-name

7. Open a Pull Request: Navigate to your fork on GitHub, select your branch, and click "New Pull Request". Provide a clear description of your changes.

For More Information

See the contributing.md for a detailed guide on how to contribute.

How to run the book locally

Create a local python environment and install all the required dependencies using the following commands (either with conda or pip)

If Using Conda

1. Create the Conda Environment

conda env create -f environment.yml

2. Activate the Conda Environment

conda activate DISCOVER-handbook

3. Finally, to build the Jupyter Book

jupyter-book build DISCOVER

If Using pip

1. Create a Virtual Environment (optional)

python -m venv .venv

2. Activate the virtual Environment (optional)

• on Windows:

.venv\Scripts\activate

• on macOS/Linux:

source .venv/bin/activate

3. Install the required dependencies

pip install -r requirements.txt

4. Finally, to build the Jupyter Book

jupyter-book build DISCOVER

View Locally

After building, you can view the book in one of the following ways:

Option 1: Using a Local Server

Run the following command to start a local server:

python -m http.server 8000 --directory DISCOVER/_build/html/

Then, open http://localhost:8000 in your browser.

Option 2: Opening the File Directly

Alternatively, you can open the book directly by navigating to:

DISCOVER/_build/html/index.html

and opening it in your browser.

Note: Make sure you have built the book again before accessing it.

Contributors ✨

Thanks goes to these wonderful people (emoji key):

Akhil-Jasson 📖	Andy R. Terrel 🤔 👀 🚧 💬	Anushka joshi 💻	Ashish Mahajan 💻	Ashley Maguire 📖 🚧 🤔	Ashley Otero 🤔	Bojan Božić 📖
Chris Holdgraf 🤔	Dave Clements 📖 🚧 🤔	Frames White 📖 🤔	Gina 🚧 📖 🤔 👀	Gina 📖	Jeffrin Jojo 📖	Jennifer Klay 🤔
Kafui Alordo 🤔	Kamila Stepniowska 🚧	Kasia Rachuta 🤔	Kat Hoessel 🤔	M.K 📖	Madicken Munk 🤔	Mark Mikofski 🚧 🤔 📖 👀
Melissa Weber Mendonça 🤔	Muhammad Salman 📖	Noa Tamir 👀 🤔 🚧	Oloni 📖	Pratham 💻	Prisha Sharma 🖋	Priya Kholiya 🤔
Raniere Silva 🤔	Reshama Shaikh 📖 🤔	Ritesh Kumar Singh 💻	Sarah Supp 🤔	Tania Allard 🚧 🤔	Tereza Iofciu 📖 🚧 🤔	Tetsuo Koyama 💬 🚧 📖 👀
discover-cookbook 📖	kasiarachuta 📖

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