Update guide (#73)

* add doctest tips

* small correctins

* add note on possibly needing to recompile pandas

* rebuild

Author: jorisvandenbossche

pandas/guide/_sources/pandas_docstring.rst.txt

@@ -20,7 +20,8 @@ Next example gives an idea on how a docstring looks like:
 .. code-block:: python
 
     def add(num1, num2):
-    """Add up two integer numbers.
+    """
+    Add up two integer numbers.
 
     This function simply wraps the `+` operator, and does not
     do anything interesting, except for illustrating what is
@@ -265,7 +266,7 @@ argument means, which can be added after a comma "int, default -1, meaning all
 cpus".
 
 In cases where the default value is `None`, meaning that the value will not be
-used. Instead of "str, default None" is preferred "str, optional".
+used. Instead of "str, default None", it is preferred to write "str, optional".
 When `None` is a value being used, we will keep the form "str, default None".
 For example, in `df.to_csv(compression=None)`, `None` is not a value being used,
 but means that compression is optional, and no compression is being used if not
@@ -535,7 +536,8 @@ For example:
 
     class Series:
         def head(self):
-            """Return the first 5 elements of the Series.
+            """
+            Return the first 5 elements of the Series.
 
             This function is mainly useful to preview the values of the
             Series without displaying the whole of it.
@@ -603,7 +605,8 @@ A simple example could be:
 
     class Series:
         def head(self, n=5):
-            """Return the first elements of the Series.
+            """
+            Return the first elements of the Series.
 
             This function is mainly useful to preview the values of the
             Series without displaying the whole of it.
@@ -815,6 +818,52 @@ positional arguments `head(3)`.
         pass
 
 
+.. _docstring.doctest_tips:
+
+Tips for getting your examples pass the doctests
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Getting the examples pass the doctests in the validation script can sometimes
+be tricky. Here are some attention points:
+
+* Import all needed libraries (except for pandas and numpy, those are already
+  imported as `import pandas as pd` and `import numpy as np`) and define all
+  variables you use in the example.
+
+* Try to avoid using random data.
+
+* If you have a code snippet that wraps multiple lines, you need to use '...'
+  on the continued lines:
+
+  ::
+
+    >>> df = pd.DataFrame([[1, 2, 3], [4, 5, 6]], index=['a', 'b', 'c'],
+    ...                   columns=['A', 'B'])
+
+* If you want to show a case where an exception is raised, you can do::
+
+    >>> pd.to_datetime(["712-01-01"])
+    Traceback (most recent call last):
+    OutOfBoundsDatetime: Out of bounds nanosecond timestamp: 712-01-01 00:00:00
+
+  It is essential to include the "Traceback (most recent call last):", but for
+  the actual error only the error name is sufficient.
+
+* If there is a small part of the result that can vary (e.g. a hash in an object
+  represenation), you can use ``...`` to represent this part.
+
+  If you want to show that ``s.plot()`` returns a matplotlib AxesSubplot object,
+  this will fail the doctest::
+
+    >>> s.plot()
+    <matplotlib.axes._subplots.AxesSubplot at 0x7efd0c0b0690>
+
+  However, you can do (notice the comment that needs to be added)::
+
+    >>> s.plot()  # doctest: +ELLIPSIS
+    <matplotlib.axes._subplots.AxesSubplot at ...>
+
+
 .. _docstring.example_plots:
 
 Plots in examples
@@ -839,7 +888,7 @@ plot will be generated automatically when building the documentation.
             .. plot::
                 :context: close-figs
 
-            >>> s = pd.Series([1, 2, 3])
-            >>> s.plot()
+                >>> s = pd.Series([1, 2, 3])
+                >>> s.plot()
             """
             pass

pandas/guide/_sources/pandas_pr.rst.txt

@@ -16,7 +16,7 @@ technical parts of the pandas docstring convention. To run the script,
 execute in your terminal:
 
     | ``cd <pandas-dir>``
-    | ``scripts/validate_docstrings.py <your-function-or-method>``
+    | ``python scripts/validate_docstrings.py <your-function-or-method>``
 
 where `<your-function-or-method>` is for example `pandas.DataFrame.head`,
 `pandas.Series.tail` or `pandas.to_datetime`.
@@ -34,6 +34,15 @@ Finally, the output will also contain errors from running the examples.
 
 With few exceptions, you should fix all the errors before continuing.
 
+If you are changing a docstring in a cython file (with ``.pyx`` extension),
+you need to rebuild the pandas C extensions to be able to see the resulting
+changes in the docstring and to validate the docstring with the command
+above. 
+To recompile pandas, run:
+
+    | ``cd <pandas-dir>``
+    | ``python setup.py build_ext --inplace``
+
 2. Visual validation of the docstring
 -------------------------------------
 
@@ -114,6 +123,9 @@ style by running the command:
 
     | ``git diff upstream/master -u -- "*.py" | flake8 --diff``
 
+If you don't already have flake8 installed, you can install it in the Anaconda Prompt it via
+    | ``conda install flake8``
+
 If the command does not return any warning, mark that checkbox with an X (do
 not leave spaces inside the brackets, use `[X]`). If it returns a warning,
 fix it, commit your changes, and push to your remote branch before opening

pandas/guide/_static/alabaster.css

@@ -15,49 +15,14 @@
 
 
 
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
 @import url("basic.css");
 
 /* -- page layout ----------------------------------------------------------- */
 
 body {
     font-family: 'goudy old style', 'minion pro', 'bell mt', Georgia, 'Hiragino Mincho Pro', serif;
     font-size: 17px;
-    background-color: #fff;
+    background-color: white;
     color: #000;
     margin: 0;
     padding: 0;
@@ -89,7 +54,7 @@ hr {
 }
 
 div.body {
-    background-color: #fff;
+    background-color: #ffffff;
     color: #3E4349;
     padding: 0 30px 0 30px;
 }
@@ -111,7 +76,7 @@ div.footer a {
 }
 
 p.caption {
-    font-family: inherit;
+    font-family: ;
     font-size: inherit;
 }
 
@@ -267,15 +232,19 @@ div.body p, div.body dd, div.body li {
 div.admonition {
     margin: 20px 0px;
     padding: 10px 30px;
-    background-color: #EEE;
-    border: 1px solid #CCC;
+    background-color: #FCC;
+    border: 1px solid #FAA;
 }
 
-div.admonition tt.xref, div.admonition code.xref, div.admonition a tt {
-    background-color: #FBFBFB;
+div.admonition tt.xref, div.admonition a tt {
     border-bottom: 1px solid #fafafa;
 }
 
+dd div.admonition {
+    margin-left: -60px;
+    padding-left: 60px;
+}
+
 div.admonition p.admonition-title {
     font-family: 'Garamond', 'Georgia', serif;
     font-weight: normal;
@@ -290,71 +259,25 @@ div.admonition p.last {
 }
 
 div.highlight {
-    background-color: #fff;
+    background-color: white;
 }
 
 dt:target, .highlight {
     background: #FAF3E8;
 }
 
-div.warning {
-    background-color: #FCC;
-    border: 1px solid #FAA;
-}
-
-div.danger {
-    background-color: #FCC;
-    border: 1px solid #FAA;
-    -moz-box-shadow: 2px 2px 4px #D52C2C;
-    -webkit-box-shadow: 2px 2px 4px #D52C2C;
-    box-shadow: 2px 2px 4px #D52C2C;
-}
-
-div.error {
-    background-color: #FCC;
-    border: 1px solid #FAA;
-    -moz-box-shadow: 2px 2px 4px #D52C2C;
-    -webkit-box-shadow: 2px 2px 4px #D52C2C;
-    box-shadow: 2px 2px 4px #D52C2C;
-}
-
-div.caution {
-    background-color: #FCC;
-    border: 1px solid #FAA;
-}
-
-div.attention {
-    background-color: #FCC;
-    border: 1px solid #FAA;
-}
-
-div.important {
-    background-color: #EEE;
-    border: 1px solid #CCC;
-}
-
 div.note {
     background-color: #EEE;
     border: 1px solid #CCC;
 }
 
-div.tip {
-    background-color: #EEE;
-    border: 1px solid #CCC;
-}
-
-div.hint {
-    background-color: #EEE;
-    border: 1px solid #CCC;
-}
-
 div.seealso {
     background-color: #EEE;
     border: 1px solid #CCC;
 }
 
 div.topic {
-    background-color: #EEE;
+    background-color: #eee;
 }
 
 p.admonition-title {
@@ -389,16 +312,16 @@ tt.descname, code.descname {
 }
 
 img.screenshot {
-    -moz-box-shadow: 2px 2px 4px #EEE;
-    -webkit-box-shadow: 2px 2px 4px #EEE;
-    box-shadow: 2px 2px 4px #EEE;
+    -moz-box-shadow: 2px 2px 4px #eee;
+    -webkit-box-shadow: 2px 2px 4px #eee;
+    box-shadow: 2px 2px 4px #eee;
 }
 
 table.docutils {
     border: 1px solid #888;
-    -moz-box-shadow: 2px 2px 4px #EEE;
-    -webkit-box-shadow: 2px 2px 4px #EEE;
-    box-shadow: 2px 2px 4px #EEE;
+    -moz-box-shadow: 2px 2px 4px #eee;
+    -webkit-box-shadow: 2px 2px 4px #eee;
+    box-shadow: 2px 2px 4px #eee;
 }
 
 table.docutils td, table.docutils th {
@@ -438,16 +361,6 @@ table.field-list p {
     margin-bottom: 0.8em;
 }
 
-/* Cloned from
- * https://github.com/sphinx-doc/sphinx/commit/ef60dbfce09286b20b7385333d63a60321784e68
- */
-.field-name {
-    -moz-hyphens: manual;
-    -ms-hyphens: manual;
-    -webkit-hyphens: manual;
-    hyphens: manual;
-}
-
 table.footnote td.label {
     width: .1px;
     padding: 0.3em 0 0.3em 0.5em;
@@ -484,15 +397,16 @@ pre {
     line-height: 1.3em;
 }
 
-div.viewcode-block:target {
-    background: #ffd;
-}
-
 dl pre, blockquote pre, li pre {
     margin-left: 0;
     padding-left: 30px;
 }
 
+dl dl pre {
+    margin-left: -90px;
+    padding-left: 90px;
+}
+
 tt, code {
     background-color: #ecf0f3;
     color: #222;
@@ -501,7 +415,7 @@ tt, code {
 
 tt.xref, code.xref, a tt {
     background-color: #FBFBFB;
-    border-bottom: 1px solid #fff;
+    border-bottom: 1px solid white;
 }
 
 a.reference {
@@ -603,7 +517,7 @@ a:hover tt, a:hover code {
 
     div.documentwrapper {
         float: none;
-        background: #fff;
+        background: white;
     }
 
     div.sphinxsidebar {
@@ -618,7 +532,7 @@ a:hover tt, a:hover code {
 
     div.sphinxsidebar h3, div.sphinxsidebar h4, div.sphinxsidebar p,
     div.sphinxsidebar h3 a {
-        color: #fff;
+        color: white;
     }
 
     div.sphinxsidebar a {