Skip to content

Structure the CONTRIBUTING guide to define sprint tasks #311

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Jul 3, 2024
Merged

Structure the CONTRIBUTING guide to define sprint tasks #311

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
733b587
Create a structure for the Contributing guide to help sprint tasks
flpm Jun 30, 2024
847d825
Fix missing xref
flpm Jun 30, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
122 changes: 86 additions & 36 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,65 +1,114 @@
---
orphan: true
---
# Contributing Guide for the Python open source software packaging book
# Contributing to the Python Packaging Guide

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

## TL;DR

We welcome contributions in the form of issues and pull requests:

* 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 are interested in helping translate the guide into other languages, take a look at the [translation guide](./TRANSLATING.md).
* 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
If you are unsure about how to contribute or are not familiar with git and github, this guide will help you through the process.

Most of this repository is structured for **Sphinx**, a documentation engine built in `Python`. We are using the Sphinx Book Theme and the `myST` syntax to create each page in this book.
## How the Python Packaging Guide is structured

If you wish to contribute by working on the guide book locally, you
will first need to
The Python Packaging Guide is written in myST (a variant of MarkDown and rST) and we use **Sphinx**, a documentation engine built in `Python` to build the HTML version you see online.

1. Fork this repository
2. Clone it locally
3. Build the documentation locally
We use a tool called Nox to manage the process of building the guide.

## Instructions for building the documentation locally on your computer
## Two approaches to contributing

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.
You can contribute to the guide using two approaches.

To do so, follow these steps:
The first approach is using a local copy of the guide in your computer. This option requires a more involved setup, but allows you to build the guide locally to verify your contribution did not introduce any bugs before submitting a pull request. It is the recommended approach for larger contribution, like writing a whole new section.

1. Install `nox`
The second approach is making your contribution directly in the GitHub website. This option does not require any setup on your computer and while your contribution will still be tested when you submit a PR (continuous integration), it will take longer for you to get any feedback in case of issue. It is the best way to make small contribution, like fixing typos, or if this is your first contribution to open source and the first approach feels too intimidating.

```
python -m pip install nox
```
2. Build the documentation:
## Forking the repository

```
python -m nox -s docs
```
Independently of the approach you choose, the first step is to fork the Python Packaging Guide repository into your personal GitHub space.

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`.
The site can then be viewed locally by opening the top level `index.html` in your web browser. The exact location of this file will depend on you system, but the output of the following command could be copied into an address bar
*__TODO__: This section should show a beginner user how to fork a repository in GitHub.*
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is great - we can link to this lesson here!. i plan to bring that lesson over to our tutorials at some point!

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

i'll do that in a separate pr!


```
echo "file://$(pwd)/_build/html/index.html"
```
## Contributing via the GitHub website

To build live documentation that updates when you update local files, run the following command:
### How to edit a MarkDown file

```
python -m nox -s docs-live
```
*__TODO__: This section should show how to use the GitHub interface to edit and previewing a Markdown file.*
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

let's make this another help-wanted task for our sprint :)


### How to commit your changes

*__TODO__: This section should show how to commit changes via the GitHub interface.*

## Contributing locally on your computer

### Clone your forked repository

*__TODO__: This section should show how to clone a repository from GitHub into your computer.*

### Create a new branch

*__TODO__: This section should show how to create a new branch.*

### Create a virtual environment

*__TODO__: This section should show how to create a virtual environment using venv.*

### Install the development dependencies

*__TODO__: This section should show how to install the development dependencies defined in pyproject.toml.*

### Commit your changes

*__TODO__: This section should describe how to commit from the command line.*

### How to build the guide locally

*__TODO__: This section should describe the different sessions in nox related to building the docs: docs, docs-test, docs-live. It should also show how to see the guide built locally, by opening the right file in the browser or using the live version from docs-live*

### Before you submit your pull request

*__TODO__: This section should describe what steps a user should follow before submitting the pull request: build the docs, verify your changes look correct, etc.*

## Submitting a pull request with your contribution

### How to make a pull request

*__TODO__: This section should describe how to make a pull request in GitHub.*

### What happens when you submit a pull request (CI/CD)

*__TODO__: This section should describe how to see the results of the CD/CI checks and how to get more information about errors*

### What to expect from the review process

*__TODO__: This section should describe how review happens in GitHub, how see the comments, and how to submit changes (push a new branch)*

## Additional help

### How to get help

*__TODO__: This section should describe the options for finding more help in case beginner contributors need more help (e.g., create an issue, post in a forum, etc).*

### Additional resources

*__TODO__: It should also include links to beginner documentation, like the GitHub docs.*

When build like this, the output will tell you a localhost address where the site can be viewed, generally http://127.0.0.1:8000.
## Annex

## Code examples
### Code examples

This guide uses the [literalinclude Sphinx directive](https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-literalinclude)
whenever possible to keep code and prose separate. Code for use in the documentation is kept in the `examples/` folder.

### Referencing code in documentation
(referencing-code-in-documentation)=
#### Referencing code in documentation

If an example is present elsewhere in the documentation that you want to use, you can copy the `literalinclude`
directive verbatim and the examples will stay in sync.
Expand All @@ -73,9 +122,10 @@ later can protect your example from future modifications to the code.
`:end-at:` options. And if the example code is Python, `:pyobject:` can be an even more future-proof way to keep the
same documentation content even through code refactors.

If you need example code that doesn't yet exist in `examples/` [see creating code for documentation](#creating-code-for-documentation).
If you need example code that doesn't yet exist in `examples/` see creating code for documentation](#creating-code-for-documentation).

### Creating code for documentation
(creating-code-for-documentation)=
#### Creating code for documentation

Whenever you come across a place that could benefit from a code block, instead of writing it in-line with a code fence
(`` ``` `` blocked text) you can write it as a file in its own format. Your example may even already exist; [see referencing code in documentation
Expand Down
Loading