Skip to content

Commit 2326d5d

Browse files
datapythonistadatapythonista
committed
working on the pandas sprint documentation
1 parent 93805dc commit 2326d5d

File tree

3 files changed

+111
-0
lines changed

3 files changed

+111
-0
lines changed

‎pandas/guide/source/contents.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -29,3 +29,4 @@ pandas documentation sprint.
2929

3030
pandas_setup
3131
pandas_docstring
32+
pandas_pr

‎pandas/guide/source/pandas_pr.rst

Lines changed: 105 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,105 @@
1+
=======================
2+
Submitting your changes
3+
=======================
4+
5+
Once you finished the changes to your assigned docstring, you can follow the
6+
instructions in this document in order to get your changes merged into pandas,
7+
and released in the next version.
8+
9+
1. Validate that your docstring does not have technical errors
10+
--------------------------------------------------------------
11+
12+
There is a script in pandas that validates whether a docstring follows the
13+
technical parts of the pandas docstring convention. To run the script,
14+
execute in your terminal:
15+
16+
| ``cd <pandas-dir>``
17+
| ``scripts/validate_docstring.py <your-function-or-method>``
18+
19+
where `<your-function-or-method>` is for example `pandas.DataFrame.head`,
20+
`pandas.Series.tail` or `pandas.to_datetime`.
21+
22+
2. Visual validation of the docstring
23+
-------------------------------------
24+
25+
The previous sprint validates things like the names of the sections, or
26+
that there are dots, spaces, or blank lines in the right side. But does
27+
not validate for typos, unclear sentences, or other mistakes. To validate
28+
them, as well as the visualization of your docstring in the pandas website
29+
you need to generate the html version of the page you worked on.
30+
31+
To build the documentation run:
32+
33+
| ``cd <pandas-dir>/doc``
34+
| ``python make.py html --single <your-function-or-method>``
35+
36+
where `<your-function-or-method>` follows the format described in the previous
37+
section.
38+
39+
This will generate a file `<pandas-dir>/doc/build/html/generated/<your-function-or-method>.html`
40+
that can be opened with your web browser.
41+
42+
3. Validate code in the examples
43+
--------------------------------
44+
45+
Code in the `Examples` section of the docstring must be valid Python code, and
46+
return the exact output as presented. Besides illustrating the functionality
47+
in the documentation, this code is also part of the unit tests.
48+
49+
To run the examples as unit tests, and validate that the code is correct and
50+
returns the expected output, execute the next in your terminal:
51+
52+
| ``cd <pandas-dir>``
53+
| ``pytest --doctest-modules <file-of-your-docstring> -k <function-or-method-name>``
54+
55+
where `<file-of-your-docstring>` is the path to the file where you edited your docstring
56+
(e.g. `pandas/core/frame.py`) and `<function-or-method-name>` is the name of the function
57+
or method you edited (e.g. `head`).
58+
59+
4. Validate that the docstring is clear to others
60+
-------------------------------------------------
61+
62+
As the last validation, please show the html version of your docstring to a
63+
person in the sprint not involved in the changes to the docstring, and make
64+
sure they are able to fully understand it.
65+
66+
5. Commit your changes
67+
----------------------
68+
69+
Once all the validations are successful, you can proceed to commit the changes
70+
into git.
71+
72+
Before committing your changes, make sure you are in the branch of the feature
73+
you are going to commit with:
74+
75+
| ``git branch``
76+
77+
Then, follow the next steps:
78+
79+
| ``git fetch upstream``
80+
| ``git merge upstram/master``
81+
| ``git add <modified-file(s)>``
82+
| ``git commit -m "<commit-message>"``
83+
84+
where `<modified-file(s)>` is the file where you made your changes (in rare
85+
cases it could be more than one file). And `<commit-message>` is a short
86+
description of your changes, starting by "DOC:" (e.g. "DOC: Improved the
87+
docsting of DataFrame.head()").
88+
89+
6. Push your changes to the sprint repository
90+
---------------------------------------------
91+
92+
Before sending the pull request to the pandas core developers, you will send
93+
it to the sprint repository. Where more experienced contributors will review
94+
it, and suggest changes if needed.
95+
96+
First, push your changes to your GitHub fork:
97+
98+
| ``git push -u origin <your-branch-name>``
99+
100+
Then, visit https://github.com/python-sprints/pandas in your browser, and click
101+
on the "Compare & pull request" button in the yellow box above the repository
102+
files.
103+
104+
Once your changes are reviewed and approved, you will receive an email on how
105+
to send the final pull request to pandas.

‎pandas/guide/source/pandas_setup.rst

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -46,6 +46,11 @@ This will create a directory named `pandas`, containing the latest version of
4646
the source code. We will name this directory `<pandas-dir>` in the rest of
4747
this document.
4848

49+
Then, set the upstream remote, so you can fetch the updates from the pandas
50+
repository:
51+
52+
| ``git remote add upstream https://github.com/pandas-dev/pandas``
53+
4954
3. Set up a Python environment
5055
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
5156

0 commit comments

Comments
 (0)