Skip to content

Commit 7716ab4

Browse files
datapythonistadatapythonista
committed
Adding initial part of the pandas documentation sprint guide
1 parent 01d87df commit 7716ab4

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

41 files changed

+14936
-0
lines changed

‎docs/.buildinfo

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
# Sphinx build info version 1
2+
# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
3+
config: ffdea613ae45443996055a26b0f5b0f3
4+
tags: 645f666f9bcd5a90fca523b33c5a78b7

‎docs/.doctrees/contents.doctree

1.91 KB
Binary file not shown.

‎docs/.doctrees/environment.pickle

2.96 KB
Binary file not shown.

‎docs/.doctrees/pandas-doc.doctree

13.3 KB
Binary file not shown.

‎docs/_static

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
pandas-doc/build/_static

‎docs/pandas-doc.html

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
pandas-doc/build/contents.html

‎docs/pandas-doc/build/.buildinfo

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
# Sphinx build info version 1
2+
# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
3+
config: f892973023b47dc74293562181b9d8ee
4+
tags: 645f666f9bcd5a90fca523b33c5a78b7

‎docs/pandas-doc/build/.doctrees/contents.doctree

11.2 KB
Binary file not shown.

‎docs/pandas-doc/build/.doctrees/environment.pickle

2.87 KB
Binary file not shown.

‎docs/pandas-doc/build/_sources/contents.rst.txt

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
====================================
2+
How to write a good pandas docstring
3+
====================================
4+
5+
About docstrings and standards
6+
------------------------------
7+
8+
A Python docstring is a string used to document a Python function or method,
9+
so programmers can understand what it does without having to read the details
10+
of the implementation.
11+
12+
Also, it is a commonn practice to generate online (html) documentation
13+
automatically from docstrings. `Sphinx <http://www.sphinx-doc.org>`_ serves
14+
this purpose.
15+
16+
Next example gives an idea on how a docstring looks like:
17+
18+
.. code-block:: python
19+
20+
def add(num1, num2):
21+
"""Add up to integer numbers.
22+
23+
This function simply wraps the `+` operator, and does not
24+
do anything interesting, except for illustrating what is
25+
the docstring of a very simple function.
26+
27+
Parameters
28+
----------
29+
num1 : int
30+
First number to add
31+
num2 : int
32+
Second number to add
33+
34+
Returns
35+
-------
36+
int
37+
The sum of `num1` and `num2`
38+
39+
Examples
40+
--------
41+
>>> add(2, 2)
42+
4
43+
>>> add(25, 0)
44+
25
45+
>>> add(10, -10)
46+
0
47+
"""
48+
return num1 + num2
49+
50+
To make it easier to understand docstrings, and to make it possible to export
51+
them to html, some standards exist.
52+
53+
The first conventions every Python docstring should follow are defined in
54+
`PEP-257 <https://www.python.org/dev/peps/pep-0257/>`_.
55+
56+
As PEP-257 is quite open, some other standards exist. In the case of pandas,
57+
the numpy docstring convention is followed. There are two main documents
58+
that explain this convention:
59+
60+
- `Guide to NumPy/SciPy documentation <https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt>`_
61+
- `numpydoc docstring guide <http://numpydoc.readthedocs.io/en/latest/format.html>`_
62+
63+
numpydoc is a Sphinx extension to support the numpy docstring convention.
64+
65+
The standard uses reStructuredText (reST). reStructuredText is a markup
66+
language that allows encoding styles in plain text files. Documentation
67+
about reStructuredText can be found in:
68+
69+
- `Sphinx reStructuredText primer <http://www.sphinx-doc.org/en/stable/rest.html>`_
70+
- `Quick reStructuredText reference <http://docutils.sourceforge.net/docs/user/rst/quickref.html>`_
71+
- `Full reStructuredText specification <http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html>`_
72+
73+
The rest of this document will summarize all the above guides, and will
74+
provide additional convention specific to the pandas project.

‎docs/pandas-doc/build/_static/ajax-loader.gif

673 Bytes
Loading

0 commit comments

Comments
 (0)