-
-
Notifications
You must be signed in to change notification settings - Fork 17.9k
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.
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
DOC/CI: run doctests on travis #19952
Changes from 22 commits
f17747f
d24bbd2
47f7034
67f4ae8
5caf04b
2d4c6ac
10cf824
32f6d1c
5833f86
1d8e592
3add36c
a65ee48
9317d31
7845ea3
6cc5a96
9837682
5d468d2
6826dcf
834c750
c03c895
d3d5a50
4884f03
caa43f1
25bc158
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,60 @@ | ||
#!/bin/bash | ||
|
||
echo "inside $0" | ||
|
||
|
||
source activate pandas | ||
cd "$TRAVIS_BUILD_DIR" | ||
|
||
RET=0 | ||
|
||
if [ "$DOCTEST" ]; then | ||
|
||
echo "Running doctests" | ||
|
||
# running all doctests is not yet working | ||
# pytest --doctest-modules --ignore=pandas/tests -v pandas | ||
|
||
# if [ $? -ne "0" ]; then | ||
# RET=1 | ||
# fi | ||
|
||
# DataFrame / Series docstrings | ||
pytest --doctest-modules -v pandas/core/frame.py \ | ||
-k"-assign -axes -combine -isin -itertuples -join -nlargest -nsmallest -nunique -pivot_table -quantile -query -reindex -reindex_axis -replace -round -set_index -stack -to_dict -to_records -to_stata -transform" | ||
|
||
if [ $? -ne "0" ]; then | ||
RET=1 | ||
fi | ||
|
||
pytest --doctest-modules -v pandas/core/series.py \ | ||
-k"-agg -map -nlargest -nonzero -nsmallest -reindex -searchsorted -to_dict" | ||
|
||
if [ $? -ne "0" ]; then | ||
RET=1 | ||
fi | ||
|
||
pytest --doctest-modules -v pandas/core/generic.py \ | ||
-k"-_set_axis_name -_xs -droplevel -groupby -interpolate -pct_change -pipe -reindex -reindex_axis -resample -sample -to_json -to_xarray -transform -transpose -values -xs" | ||
|
||
if [ $? -ne "0" ]; then | ||
RET=1 | ||
fi | ||
|
||
# top-level reshaping functions | ||
pytest --doctest-modules -v \ | ||
pandas/core/reshape/concat.py \ | ||
pandas/core/reshape/pivot.py \ | ||
pandas/core/reshape/reshape.py \ | ||
pandas/core/reshape/tile.py \ | ||
-k"-crosstab -pivot_table -cut" | ||
|
||
if [ $? -ne "0" ]; then | ||
RET=1 | ||
fi | ||
|
||
else | ||
echo "NOT running doctests" | ||
fi | ||
|
||
exit $RET |
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -365,6 +365,31 @@ This will identify methods documented in ``doc/source/api.rst`` that are not act | |
class methods, and existing methods that are not documented in ``doc/source/api.rst``. | ||
|
||
|
||
Updating a *pandas* docstring | ||
----------------------------- | ||
|
||
When improving a single function or method's docstring, it is not necessarily | ||
needed to build to full documentation (see next section). | ||
However, there is a script that checks a docstring (for example for the ``DataFrame.mean`` method):: | ||
|
||
python scripts/validate_docstrings.py pandas.DataFrame.mean | ||
|
||
This script will indicate some formatting errors if present, and will also | ||
run and test the examples included in the docstring. | ||
Check the :ref:`pandas docstring guide <docstring>` for a detailed guide | ||
on how to format the docstring. | ||
|
||
The examples in the docstring ('doctests') must be valid Python code, | ||
that in a deterministic way returns the presented output, and that can be | ||
copied and run by users. This can be checked with the script above, and is | ||
also tested on Travis. A failing doctest will be a blocker for merging a PR. | ||
Check the :ref:`examples <docstring.examples>` section in the docstring guide | ||
for some tips and tricks to get the doctests passing. | ||
|
||
When doing a PR with a docstring update, it is good to post the | ||
output of the validation script in a comment on github. | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. @datapythonista eventually we should rework the documentation guidelines to include more of sprint content like https://python-sprints.github.io/pandas/guide/pandas_pr.html, but for now added short section more clearly mentioning the validation script and that the doctests need to pass |
||
|
||
|
||
How to build the *pandas* documentation | ||
--------------------------------------- | ||
|
||
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
s/to/the