# Contributing Guide for the Python open source software packaging book

Important! Before contributing to this repository, please be sure to review
our [organization-wide contributing guide](https://www.pyopensci.org/handbook/CONTRIBUTING.html) which contains guidelines for
contributions.

This is a community resource. We welcome contributions in the form of issues and/or pull requests to this guide.

- If you have an idea for something that should be included in the guide, [please open an issue here](https://github.com/pyOpenSci/python-package-guide/issues).
- If you find a typo, feel free to [submit a pull request](https://github.com/pyOpenSci/python-package-guide/pulls) to modify the text directly. Or, if you are less comfortable with pull requests, feel free to open an issue.
- If you want to see a larger change to the content of the guide book, please submit an issue first!

## How this guide is structured

This guide is built using **Sphinx**, a documentation engine built in `Python` and the pydata_sphinx_theme. We use `myST` syntax to create each page in this book.

If you wish to contribute by working on the guide book locally, you
will first need to

1. Fork this repository
2. Clone it locally
3. Build the documentation locally

## Instructions for building the documentation locally on your computer

The easiest way to build the documentation in this repository is to use `nox`,
a tool for quickly building environments and running commands within them.
Nox ensures that your environment has all the dependencies needed to build the documentation.

To do so, follow these steps:

1. Install `nox`

   ```
   pip install nox
   ```

2. Build the documentation:

   ```
   nox -s docs_build
   ```

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
```