Merge remote-tracking branch 'upstream/master' into fu1+sort

Author: TomAugspurger

doc/make.py

@@ -78,9 +78,11 @@ class DocBuilder:
     All public methods of this class can be called as parameters of the
     script.
     """
-    def __init__(self, num_jobs=1, include_api=True, single_doc=None):
+    def __init__(self, num_jobs=1, include_api=True, single_doc=None,
+                 verbosity=0):
         self.num_jobs = num_jobs
         self.include_api = include_api
+        self.verbosity = verbosity
         self.single_doc = None
         self.single_doc_type = None
         if single_doc is not None:
@@ -120,7 +122,7 @@ def _process_single_doc(self, single_doc):
         """
         self.include_api = False
 
-        if single_doc == 'api.rst':
+        if single_doc == 'api.rst' or single_doc == 'api':
             self.single_doc_type = 'api'
             self.single_doc = 'api'
         elif os.path.exists(os.path.join(SOURCE_PATH, single_doc)):
@@ -229,6 +231,8 @@ def _sphinx_build(self, kind):
         self._run_os('sphinx-build',
                      '-j{}'.format(self.num_jobs),
                      '-b{}'.format(kind),
+                     '-{}'.format(
+                         'v' * self.verbosity) if self.verbosity else '',
                      '-d{}'.format(os.path.join(BUILD_PATH, 'doctrees')),
                      '-Dexclude_patterns={}'.format(self.exclude_patterns),
                      SOURCE_PATH,
@@ -330,6 +334,9 @@ def main():
                            type=str,
                            default=os.path.join(DOC_PATH, '..'),
                            help='path')
+    argparser.add_argument('-v', action='count', dest='verbosity', default=0,
+                           help=('increase verbosity (can be repeated), '
+                                 'passed to the sphinx build command'))
     args = argparser.parse_args()
 
     if args.command not in cmds:
@@ -338,9 +345,9 @@ def main():
 
     os.environ['PYTHONPATH'] = args.python_path
 
-    getattr(DocBuilder(args.num_jobs,
-                       not args.no_api,
-                       args.single), args.command)()
+    builder = DocBuilder(args.num_jobs, not args.no_api, args.single,
+                         args.verbosity)
+    getattr(builder, args.command)()
 
 
 if __name__ == '__main__':

doc/source/conf.py

@@ -552,6 +552,45 @@ def remove_flags_docstring(app, what, name, obj, options, lines):
         del lines[:]
 
 
+def process_class_docstrings(app, what, name, obj, options, lines):
+    """
+    For those classes for which we use ::
+
+    :template: autosummary/class_without_autosummary.rst
+
+    the documented attributes/methods have to be listed in the class
+    docstring. However, if one of those lists is empty, we use 'None',
+    which then generates warnings in sphinx / ugly html output.
+    This "autodoc-process-docstring" event connector removes that part
+    from the processed docstring.
+
+    """
+    if what == "class":
+        joined = '\n'.join(lines)
+
+        templates = [
+            """.. rubric:: Attributes
+
+.. autosummary::
+   :toctree:
+
+   None
+""",
+            """.. rubric:: Methods
+
+.. autosummary::
+   :toctree:
+
+   None
+"""
+        ]
+
+        for template in templates:
+            if template in joined:
+                joined = joined.replace(template, '')
+        lines[:] = joined.split('\n')
+
+
 suppress_warnings = [
     # We "overwrite" autosummary with our PandasAutosummary, but
     # still want the regular autosummary setup to run. So we just
@@ -562,6 +601,7 @@ def remove_flags_docstring(app, what, name, obj, options, lines):
 
 def setup(app):
     app.connect("autodoc-process-docstring", remove_flags_docstring)
+    app.connect("autodoc-process-docstring", process_class_docstrings)
     app.add_autodocumenter(AccessorDocumenter)
     app.add_autodocumenter(AccessorAttributeDocumenter)
     app.add_autodocumenter(AccessorMethodDocumenter)

doc/source/dsintro.rst

@@ -81,9 +81,28 @@ index is passed, one will be created having values ``[0, ..., len(data) - 1]``.
 
 **From dict**
 
-If ``data`` is a dict, if **index** is passed the values in data corresponding
-to the labels in the index will be pulled out. Otherwise, an index will be
-constructed from the sorted keys of the dict, if possible.
+Series can be instantiated from dicts:
+
+.. ipython:: python
+
+   d = {'b' : 1, 'a' : 0, 'c' : 2}
+   pd.Series(d)
+
+.. note::
+
+   When the data is a dict, and an index is not passed, the ``Series`` index
+   will be ordered by the dict's insertion order, if you're using Python
+   version >= 3.6 and Pandas version >= 0.23.
+
+   If you're using Python < 3.6 or Pandas < 0.23, and an index is not passed,
+   the ``Series`` index will be the lexically ordered list of dict keys.
+
+In the example above, if you were on a Python version lower than 3.6 or a
+Pandas version lower than 0.23, the ``Series`` would be ordered by the lexical
+order of the dict keys (i.e. ``['a', 'b', 'c']`` rather than ``['b', 'a', 'c']``).
+
+If an index is passed, the values in data corresponding to the labels in the
+index will be pulled out.
 
 .. ipython:: python
 
@@ -243,12 +262,22 @@ not matching up to the passed index.
 If axis labels are not passed, they will be constructed from the input data
 based on common sense rules.
 
+.. note::
+
+   When the data is a dict, and ``columns`` is not specified, the ``DataFrame``
+   columns will be ordered by the dict's insertion order, if you are using
+   Python version >= 3.6 and Pandas >= 0.23.
+
+   If you are using Python < 3.6 or Pandas < 0.23, and ``columns`` is not
+   specified, the ``DataFrame`` columns will be the lexically ordered list of dict
+   keys.
+
 From dict of Series or dicts
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The resulting **index** will be the **union** of the indexes of the various
 Series. If there are any nested dicts, these will first be converted to
-Series. If no columns are passed, the columns will be the sorted list of dict
+Series. If no columns are passed, the columns will be the ordered list of dict
 keys.
 
 .. ipython:: python

doc/source/install.rst

@@ -12,7 +12,7 @@ cross platform distribution for data analysis and scientific computing.
 This is the recommended installation method for most users.
 
 Instructions for installing from source,
-`PyPI <http://pypi.python.org/pypi/pandas>`__, various Linux distributions, or a
+`PyPI <http://pypi.python.org/pypi/pandas>`__, `ActivePython <https://www.activestate.com/activepython/downloads>`__, various Linux distributions, or a
 `development version <http://github.com/pandas-dev/pandas>`__ are also provided.
 
 Python version support
@@ -25,8 +25,8 @@ Installing pandas
 
 .. _install.anaconda:
 
-Installing pandas with Anaconda
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Installing with Anaconda
+~~~~~~~~~~~~~~~~~~~~~~~~
 
 Installing pandas and the rest of the `NumPy <http://www.numpy.org/>`__ and
 `SciPy <http://www.scipy.org/>`__ stack can be a little
@@ -58,8 +58,8 @@ that folder).
 
 .. _install.miniconda:
 
-Installing pandas with Miniconda
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Installing with Miniconda
+~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The previous section outlined how to get pandas installed as part of the
 `Anaconda <http://docs.continuum.io/anaconda/>`__ distribution.
@@ -134,6 +134,13 @@ pandas can be installed via pip from
 
     pip install pandas
 
+Installing with ActivePython
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Installation instructions for 
+`ActivePython <https://www.activestate.com/activepython>`__ can be found 
+`here <https://www.activestate.com/activepython/downloads>`__. Versions
+2.7 and 3.5 include pandas.
 
 Installing using your Linux distribution's package manager.
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -164,7 +171,7 @@ Installing from source
 See the :ref:`contributing documentation <contributing>` for complete instructions on building from the git source tree. Further, see :ref:`creating a development environment <contributing.dev_env>` if you wish to create a *pandas* development environment.
 
 Running the test suite
-~~~~~~~~~~~~~~~~~~~~~~
+----------------------
 
 pandas is equipped with an exhaustive set of unit tests, covering about 97% of
 the codebase as of this writing. To run it on your machine to verify that
@@ -299,5 +306,5 @@ Optional Dependencies
 
    Without the optional dependencies, many useful features will not
    work. Hence, it is highly recommended that you install these. A packaged
-   distribution like `Anaconda <http://docs.continuum.io/anaconda/>`__, or `Enthought Canopy
+   distribution like `Anaconda <http://docs.continuum.io/anaconda/>`__, `ActivePython <https://www.activestate.com/activepython/downloads>`__  (version 2.7 or 3.5), or `Enthought Canopy
    <http://enthought.com/products/canopy>`__ may be worth considering.

doc/source/merging.rst

@@ -152,7 +152,7 @@ functionality below.
 Set logic on the other axes
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-When gluing together multiple ``DataFrame``s, you have a choice of how to handle 
+When gluing together multiple DataFrames, you have a choice of how to handle
 the other axes (other than the one being concatenated). This can be done in 
 the following three ways:
 
@@ -636,7 +636,7 @@ key combination:
 
 Here is a more complicated example with multiple join keys. Only the keys 
 appearing in ``left`` and ``right`` are present (the intersection), since 
-``how='inner'```by default.
+``how='inner'`` by default.
 
 .. ipython:: python
 
@@ -721,7 +721,7 @@ either the left or right tables, the values in the joined table will be
           labels=['left', 'right'], vertical=False);
    plt.close('all');
 
-Here is another example with duplicate join keys in ``DataFrame``s:
+Here is another example with duplicate join keys in DataFrames:
 
 .. ipython:: python
 

doc/source/options.rst

@@ -402,6 +402,10 @@ display.html.table_schema               False        Whether to publish a Table
 display.html.border                     1            A ``border=value`` attribute is
                                                      inserted in the ``<table>`` tag
                                                      for the DataFrame HTML repr.
+display.html.use_mathjax                True         When True, Jupyter notebook will process 
+                                                     table contents using MathJax, rendering 
+                                                     mathematical expressions enclosed by the 
+                                                     dollar symbol.
 io.excel.xls.writer                     xlwt         The default Excel writer engine for
                                                      'xls' files.
 io.excel.xlsm.writer                    openpyxl     The default Excel writer engine for

doc/source/tutorials.rst

@@ -180,13 +180,13 @@ Video Tutorials
 
 - `Pandas From The Ground Up <https://www.youtube.com/watch?v=5JnMutdy6Fw>`_ 
   (2015) (2:24)
-  `GitHub repo <https://github.com/brandon-rhodes/pycon-pandas-tutorial>`_ 
+  `GitHub repo <https://github.com/brandon-rhodes/pycon-pandas-tutorial>`__
 - `Introduction Into Pandas <https://www.youtube.com/watch?v=-NR-ynQg0YM>`_ 
   (2016) (1:28)
-  `GitHub repo <https://github.com/chendaniely/2016-pydata-carolinas-pandas>`_ 
+  `GitHub repo <https://github.com/chendaniely/2016-pydata-carolinas-pandas>`__
 - `Pandas: .head() to .tail() <https://www.youtube.com/watch?v=7vuO9QXDN50>`_ 
   (2016) (1:26)
-  `GitHub repo <https://github.com/TomAugspurger/pydata-chi-h2t>`_ 
+  `GitHub repo <https://github.com/TomAugspurger/pydata-chi-h2t>`__
 
 
 Various Tutorials

doc/source/visualization.rst

@@ -870,7 +870,7 @@ Andrews Curves
 
 Andrews curves allow one to plot multivariate data as a large number
 of curves that are created using the attributes of samples as coefficients
-for Fourier series, see the `Uncyclopedia entry<https://en.wikipedia.org/wiki/Andrews_plot>`_
+for Fourier series, see the `Uncyclopedia entry <https://en.wikipedia.org/wiki/Andrews_plot>`__
 for more information. By coloring these curves differently for each class
 it is possible to visualize data clustering. Curves belonging to samples
 of the same class will usually be closer together and form larger structures.
@@ -894,7 +894,7 @@ Parallel Coordinates
 ~~~~~~~~~~~~~~~~~~~~
 
 Parallel coordinates is a plotting technique for plotting multivariate data,
-see the `Uncyclopedia entry<https://en.wikipedia.org/wiki/Parallel_coordinates>`_
+see the `Uncyclopedia entry <https://en.wikipedia.org/wiki/Parallel_coordinates>`__
 for an introduction.
 Parallel coordinates allows one to see clusters in data and to estimate other statistics visually.
 Using parallel coordinates points are represented as connected line segments.
@@ -962,7 +962,7 @@ all time-lag separations. If time series is non-random then one or more of the
 autocorrelations will be significantly non-zero. The horizontal lines displayed
 in the plot correspond to 95% and 99% confidence bands. The dashed line is 99%
 confidence band. See the 
-`Uncyclopedia entry<https://en.wikipedia.org/wiki/Correlogram>`_ for more about
+`Uncyclopedia entry <https://en.wikipedia.org/wiki/Correlogram>`__ for more about
 autocorrelation plots.
 
 .. ipython:: python
@@ -1032,7 +1032,7 @@ unit interval). The point in the plane, where our sample settles to (where the
 forces acting on our sample are at an equilibrium) is where a dot representing
 our sample will be drawn. Depending on which class that sample belongs it will
 be colored differently.
-See the R package `Radviz<https://cran.r-project.org/web/packages/Radviz/>`_
+See the R package `Radviz <https://cran.r-project.org/web/packages/Radviz/>`__
 for more information.
 
 **Note**: The "Iris" dataset is available `here <https://raw.github.com/pandas-dev/pandas/master/pandas/tests/data/iris.csv>`__.