Updating docstring documentation with the last fixes and changes

Author: datapythonista

pandas/guide/_sources/pandas_docstring.rst.txt

@@ -7,9 +7,9 @@ pandas docstring guide
 About docstrings and standards
 ------------------------------
 
-A Python docstring is a string used to document a Python function or method,
-so programmers can understand what it does without having to read the details
-of the implementation.
+A Python docstring is a string used to document a Python module, class,
+function or method, so programmers can understand what it does without having
+to read the details of the implementation.
 
 Also, it is a common practice to generate online (html) documentation
 automatically from docstrings. `Sphinx <http://www.sphinx-doc.org>`_ serves
@@ -95,19 +95,29 @@ left before or after the docstring. The text starts in the next line after the
 opening quotes. The closing quotes have their own line
 (meaning that they are not at the end of the last sentence).
 
+In rare occasions reST styles like bold text or itallics will be used in
+docstrings, but is it common to have inline code, which is presented between
+backticks. It is considered inline code:
+
+- The name of a parameter
+- Python code, a module, function, built-in, type, literal... (e.g. `os`, `list`, `numpy.abs`, `datetime.date`, `True`)
+- A pandas class (in the form ``:class:`~pandas.Series```)
+- A pandas method (in the form ``:meth:`pandas.Series.sum```)
+- A pandas function (in the form ``:func:`pandas.to_datetime```)
+
 **Good:**
 
 .. code-block:: python
 
-    def func():
+    def add_values(arr):
         """
-        Some function.
+        Add the values in `arr`.
 
-        With a good docstring.
+        This is equivalent to Python `sum` of :meth:`pandas.Series.sum`.
+
+        Some sections are omitted here for simplicity.
         """
-        foo = 1
-        bar = 2
-        return foo + bar
+        return sum(arr)
 
 **Bad:**
 
@@ -121,7 +131,7 @@ opening quotes. The closing quotes have their own line
 
         It has a blank like after the signature `def func():`.
 
-        The text 'Some function' should go in the next line then the
+        The text 'Some function' should go in the line after the
         opening quotes of the docstring, not in the same line.
 
         There is a blank line between the docstring and the first line
@@ -141,9 +151,10 @@ Section 1: Short summary
 The short summary is a single sentence that express what the function does in a
 concise way.
 
-The short summary must start with a verb infinitive, end with a dot, and fit in
-a single line. It needs to express what the function does without providing
-details.
+The short summary must start with a capital letter, end with a dot, and fit in
+a single line. It needs to express what the object does without providing
+details. For functions and methods, the short summary must start with an
+infinitive verb.
 
 **Good:**
 
@@ -247,20 +258,20 @@ required to have a line with the parameter description, which is indented, and
 can have multiple lines. The description must start with a capital letter, and
 finish with a dot.
 
-Keyword arguments with a default value, the default will be listed in brackets
-at the end of the type. The exact form of the type in this case would be for
-example "int (default is 0)". In some cases it may be useful to explain what
-the default argument means, which can be added after a comma "int (default is
--1, which means all cpus)".
+For keyword arguments with a default value, the default will be listed after a
+comma at the end of the type. The exact form of the type in this case will be
+"int, default 0". In some cases it may be useful to explain what the default
+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 is None)" it is preferred to use "str, optional".
-When `None` is a value being used, we will keep the form "str (default None).
-For example consider `.fillna(value=None)`, in which `None` is the value being
-used to replace missing values. This is different from
-`.to_csv(compression=None)`, where `None` is not a value being used, but means
-that compression is optional, and will not be used, unless a compression type
-is provided. In this case we will use `str, optional`.
+used. Instead of "str, default None" is preferred "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
+provided. In this case we will use `str, optional`. Only in cases like
+`func(value=None)` and `None` is being used in the same way as `0` or `foo`
+would be used, then we will specify "str, int or None, default None".
 
 **Good:**
 
@@ -278,7 +289,7 @@ is provided. In this case we will use `str, optional`.
             ----------
             kind : str
                 Kind of matplotlib plot.
-            color : str (default 'blue')
+            color : str, default 'blue'
                 Color name or rgb code.
             **kwargs
                 These parameters will be passed to the matplotlib plotting
@@ -470,9 +481,9 @@ If the method yields its value:
 Section 5: See Also
 ~~~~~~~~~~~~~~~~~~~
 
-This is an optional section, used to let users know about pandas functionality
-related to the one being documented. While optional, this section should exist
-in most cases, unless no related methods or functions can be found at all.
+This section is used to let users know about pandas functionality
+related to the one being documented. In rare cases, if no related methods
+or functions can be found at all, this section can be skipped.
 
 An obvious example would be the `head()` and `tail()` methods. As `tail()` does
 the equivalent as `head()` but at the end of the `Series` or `DataFrame`
@@ -586,13 +597,6 @@ The way to present examples is as follows:
 4. Add examples with explanations that illustrate how the parameters can be
    used for extended functionality
 
-.. note::
-   Which data should be used in examples is a topic still under discussion.
-   We'll likely be importing a standard dataset from `pandas.io.samples`, but
-   this still needs confirmation. You can work with the data from this pull
-   request: https://github.com/pandas-dev/pandas/pull/19933/files but
-   consider this could still change.
-
 A simple example could be:
 
 .. code-block:: python
@@ -640,6 +644,10 @@ A simple example could be:
             """
             return self.iloc[:n]
 
+The examples should be as concise as possible. In cases where the complexity of
+the function requires long examples, is recommended to use blocks with headers
+in bold. Use double star \*\* to make a text bold, like in \*\*this example\*\*.
+
 .. _docstring.example_conventions:
 
 Conventions for the examples
@@ -661,11 +669,11 @@ the standard library go first, followed by third-party libraries (like
 matplotlib).
 
 When illustrating examples with a single `Series` use the name `s`, and if
-illustrating with a single `DataFrame` use the name `df`. If a set of
-homogeneous `Series` or `DataFrame` is used, name them `s1`, `s2`, `s3`...
-or `df1`, `df2`, `df3`... If the data is not homogeneous, and more than
-one structure is needed, name them with something meaningful, for example
-`df_main` and `df_to_join`.
+illustrating with a single `DataFrame` use the name `df`. For indices, `idx`
+is the preferred name. If a set of homogeneous `Series` or `DataFrame` is used,
+name them `s1`, `s2`, `s3`...  or `df1`, `df2`, `df3`... If the data is not
+homogeneous, and more than one structure is needed, name them with something
+meaningful, for example `df_main` and `df_to_join`.
 
 Data used in the example should be as compact as possible. The number of rows
 is recommended to be around 4, but make it a number that makes sense for the
@@ -708,12 +716,12 @@ positional arguments `head(3)`.
             Examples
             --------
             >>> s = pd.Series([1, np.nan, 3])
-            >>> s.fillna(9)
-            [1, 9, 3]
+            >>> s.fillna(0)
+            [1, 0, 3]
             """
             pass
 
-        def groupby_mean(df):
+        def groupby_mean(self):
             """
             Group by index and return mean.
 
@@ -723,28 +731,113 @@ positional arguments `head(3)`.
             ...               name='max_speed',
             ...               index=['falcon', 'falcon', 'parrot', 'parrot'])
             >>> s.groupby_mean()
-            falcon  375.
-            parrot   25.
+            index
+            falcon    375.0
+            parrot     25.0
+            Name: max_speed, dtype: float64
             """
             pass
 
+        def contains(self, pattern, case_sensitive=True, na=numpy.nan):
+            """
+            Return whether each value contains `pattern`.
+
+            In this case, we are illustrating how to use sections, even
+            if the example is simple enough and does not require them.
+
+            Examples
+            --------
+            >>> s = pd.Series('Antelope', 'Lion', 'Zebra', numpy.nan)
+            >>> s.contains(pattern='a')
+            0    False
+            1    False
+            2     True
+            3      NaN
+            dtype: bool
+
+            **Case sensitivity**
+
+            With `case_sensitive` set to `False` we can match `a` with both
+            `a` and `A`:
+
+            >>> s.contains(pattern='a', case_sensitive=False)
+            0     True
+            1    False
+            2     True
+            3      NaN
+            dtype: bool
+
+            **Missing values**
+
+            We can fill missing values in the output using the `na` parameter:
+
+            >>> s.contains(pattern='a', na=False)
+            0    False
+            1    False
+            2     True
+            3    False
+            dtype: bool
+
 **Bad:**
 
 .. code-block:: python
 
-    def method():
+    def method(foo=None, bar=None):
         """
         A sample DataFrame method.
 
         Do not import numpy and pandas.
 
-        Try to use meaningful data, when it adds value.
+        Try to use meaningful data, when it makes the example easier
+        to understand.
+
+        Try to avoid positional arguments like in `df.method(1)`. They
+        can be all right if previously defined with a meaningful name,
+        like in `present_value(interest_rate)`, but avoid them otherwise.
+
+        When presenting the behavior with different parameters, do not place
+        all the calls one next to the other. Instead, add a short sentence
+        explaining what the example shows.
 
         Examples
         --------
         >>> import numpy as np
         >>> import pandas as pd
         >>> df = pd.DataFrame(numpy.random.randn(3, 3),
         ...                   columns=('a', 'b', 'c'))
+        >>> df.method(1)
+        21
+        >>> df.method(bar=14)
+        123
         """
         pass
+
+
+.. _docstring.example_plots:
+
+Plots in examples
+^^^^^^^^^^^^^^^^^
+
+There are some methods in pandas returning plots. To render the plots generated
+by the examples in the documentation, the `.. plot::` directive exists.
+
+To use it, place the next code after the "Examples" header as shown below. The
+plot will be generated automatically when building the documentation.
+
+.. code-block:: python
+
+    class Series:
+        def plot(self):
+            """
+            Generate a plot with the `Series` data.
+
+            Examples
+            --------
+
+            .. plot::
+                :context: close-figs
+
+            >>> s = pd.Series([1, 2, 3])
+            >>> s.plot()
+            """
+            pass

pandas/guide/_sources/pandas_setup.rst.txt

@@ -37,6 +37,7 @@ version of pandas. Do not make them to a version downloaded from the Internet
 via pip, conda or a zip.
 
 To get the latest development version:
+
 * Fork the `pandas repository <https://github.com/pandas-dev/pandas>`_ on GitHub by click on the top-right `Fork` button
 
 .. note::
@@ -51,6 +52,10 @@ This will create a directory named `pandas`, containing the latest version of
 the source code. We will name this directory `<pandas-dir>` in the rest of
 this document.
 
+Make sure you're in the root of the `<pandas-dir>` directory.
+
+    | ``cd <pandas-dir>``
+
 Then, set the upstream remote, so you can fetch the updates from the pandas
 repository:
 
@@ -59,21 +64,25 @@ repository:
 3. Set up a Python environment
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-* Download and install `Anaconda <https://www.anaconda.com/download/>`
+* Download and install `Anaconda <https://www.anaconda.com/download/>`_.
 
 .. note::
     **Windows users**: run the next commands in the Anaconda Prompt (found in the Anaconda
-    folder of the Start menu.
+    folder of the Start menu).
 
 * Activate conda by one of the next (or equivalent, if you know what you're doing):
     * If you chose to prepend Anaconda to your PATH during install adding it to your ``~/.bashrc``, just restart your terminal.
     * Otherwise, run ``export PATH="<path-to-anaconda>/bin:$PATH"`` in your terminal. Keep in mind that it will be active exclusively in the terminal you run this command.
 * Create a conda environment:
-    ``conda env create -n pandas_dev -f <path-to-pandas>/ci/environment-dev.yaml``
+    ``conda env create -n pandas_dev -f <path-to-pandas-dir>/ci/environment-dev.yaml``
+
+.. note::
+    **Windows users**: If you're copy-pasting the path, replace all pasted ``\`` characters with ``/`` for the command to work.
+
 * Activate the new conda environment:
-    ``source activate pandas_dev``    
+    ``conda activate pandas_dev``    
 * Install pandas development dependencies:
-    ``conda install -c defaults -c conda-forge --file=<pandas-dir>/ci/requirements-optional-conda.txt``
+    ``conda install -c defaults -c conda-forge --file=<path-to-pandas-dir>/ci/requirements-optional-conda.txt``
 
 4. Compile C code in pandas
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -82,7 +91,7 @@ Besides the Python `.py` files, pandas source code includes C/Cython files
 which need to be compiled in order to run the development version of pandas.
 
 .. note::
-    **Windows users**: to compile pandas, you need to install `Visual Studio 2017 <https://www.visualstudio.com/>`_.
+    **Windows users**: to compile pandas, you need to install `Visual Studio 2017 <https://www.visualstudio.com/>`_. You need the Community edition as a minimum. Visual Studio Code does not support the required Build Tools and will not work.
     Select the Python development workload and the Native development tools option.
 
     (Users of legacy Python 2.7 should install `Microsoft Visual C++ Compiler for Python 2.7 <https://www.microsoft.com/download/details.aspx?id=44266>`_ instead).