Skip to content

Commit fa62457

Browse files
docs: add local github setup guide
1 parent adb7624 commit fa62457

File tree

5 files changed

+85
-10
lines changed

5 files changed

+85
-10
lines changed

CONTRIBUTING.md

Lines changed: 85 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -44,50 +44,125 @@ You can do this by clicking the "Fork" button in the top right corner of the rep
4444
The Python Packaging Guide is written in myST, a variant of MarkDown. You can edit the files directly in the GitHub website.
4545
To do so, navigate to the file you want to edit and click the pencil icon in the top right corner of the file.
4646

47-
![Edit file in GitHub](../images/edit-file.png)
47+
![Edit file in GitHub](images/contributing/edit-file.png)
4848

4949
To preview your changes, click the "Preview changes" tab.
5050

51-
![Preview changes in GitHub](../images/preview-changes.png)
51+
![Preview changes in GitHub](images/contributing/preview-changes.png)
5252

5353
### How to commit your changes
5454

5555
When you are done editing the file, scroll down to the bottom of the page. You will see a section called "Commit changes".
5656
Here you can write a title and a description for your changes. Make sure to write a clear and concise title that describes the changes you made.
5757

58-
![Commit changes in GitHub](../images/commit-changes.png)
58+
![Commit changes in GitHub](images/contributing/commit-changes.png)
5959

6060
click on the "propose changes" button to submit your changes and open a pull request. See (How to make a pull request)[#how-to-make-a-pull-request] for more information.
6161

6262
## Contributing locally on your computer
6363

6464
### Clone your forked repository
6565

66-
*__TODO__: This section should show how to clone a repository from GitHub into your computer.*
66+
To clone your forked repository to your computer, you need to copy the URL of your forked repository and run the following command in your terminal:
67+
68+
```bash
69+
git clone <URL>
70+
```
71+
Replace `<URL>` with the URL of your forked repository. You can find the URL by clicking the green "Code" button on your forked repository page.
72+
73+
![Clone repository](images/contributing/clone-repository.png)
6774

6875
### Create a new branch
6976

70-
*__TODO__: This section should show how to create a new branch.*
77+
Before making any changes, you should create a new branch to work on. This will help keep your changes separate from the main branch and make it easier to submit a pull request.
78+
79+
To create a new branch, run the following command in your terminal:
80+
81+
```bash
82+
git checkout -b <branch-name>
83+
```
7184

7285
### Create a virtual environment
7386

74-
*__TODO__: This section should show how to create a virtual environment using venv.*
87+
To build the guide locally, you need to create a virtual environment and install the dependencies. You can do this by running the following commands in your terminal:
88+
89+
- **On Windows**:
90+
```bash
91+
python -m venv .venv
92+
.venv\Scripts\activate
93+
```
94+
95+
- **On MacOS and Linux**:
96+
```bash
97+
python -m venv .venv
98+
source .venv/bin/activate
99+
```
75100

76101
### Install the development dependencies
77102

78-
*__TODO__: This section should show how to install the development dependencies defined in pyproject.toml.*
103+
To install the development dependencies, run the following command in your terminal:
104+
105+
```bash
106+
python -m pip install -e .[dev]
107+
```
79108

80109
### Commit your changes
81110

82-
*__TODO__: This section should describe how to commit from the command line.*
111+
After making your changes, you need to commit them to your local repository. To do this, run the following commands in your terminal:
112+
113+
- To see the changes you made:
114+
```bash
115+
git status
116+
```
117+
- To add the changes to the staging area:
118+
```bash
119+
git add .
120+
```
121+
- To commit the changes:
122+
```bash
123+
git commit -m "Your commit message here"
124+
```
125+
Replace `"Your commit message here"` with a clear and concise message that describes the changes you made.
83126

84127
### How to build the guide locally
85128

86-
*__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*
129+
To build the guide locally, you can use the `nox` command. This will run the default `nox` session, which builds the guide and opens it in your browser.
130+
131+
To see the different sessions available, you can run the following command in your terminal:
132+
133+
```bash
134+
nox --list-sessions
135+
```
136+
There are different sessions in nox related to building the docs: `docs`, `docs-test`, `docs-live`. You can run them by specifying the session name after the `nox` command.
137+
138+
- `docs`: this session builds the guide and opens it in your browser.
139+
```bash
140+
nox -e docs
141+
```
142+
To see the guide built locally, open the file `_build/html/index.html` in your browser.
143+
144+
- `docs-test`: this session runs the tests for the guide.
145+
```bash
146+
nox -e docs-test
147+
```
148+
If the tests fail, you will see an error message in your terminal. You need to fix the errors before submitting your pull request.
149+
150+
- `docs-live`: this session builds the guide and opens it in your browser with live reloading.
151+
```bash
152+
nox -e docs-live
153+
```
154+
open the local version of the guide in your browser at ``localhost`` shown in the terminal.
87155

88156
### Before you submit your pull request
89157

90-
*__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.*
158+
Before submitting your pull request, make sure to run the tests and check the formatting of your code.
159+
160+
```bash
161+
nox -e docs-test
162+
```
163+
If the tests fail, you will see an error message in your terminal. You need to fix the errors before submitting your pull request.
164+
Also make sure to check the formatting of your documentation by building the docs locally and checking that your changes look correct.
165+
91166

92167
## Submitting a pull request with your contribution
93168

13.2 KB
Loading
File renamed without changes.
File renamed without changes.
File renamed without changes.

0 commit comments

Comments
 (0)