DOC: Creating top-level user guide section, and moving pages inside (p…

…andas-dev#24677)
Pingviinituutti · Feb 28, 2019 · 92e8996 · 92e8996
1 parent c7e2b96
commit 92e8996
Show file tree

Hide file tree

Showing 21 changed files with 62 additions and 41 deletions.
diff --git a/doc/source/index.rst.template b/doc/source/index.rst.template
@@ -131,25 +131,7 @@ See the package overview for more detail about what's in the library.
     cookbook
     dsintro
     basics
-    text
-    options
-    indexing
-    advanced
-    computation
-    missing_data
-    groupby
-    merging
-    reshaping
-    timeseries
-    timedeltas
-    categorical
-    integer_na
-    visualization
-    style
-    io
-    enhancingperf
-    sparse
-    gotchas
+    user_guide/index
     r_interface
     ecosystem
     comparison_with_r

diff --git a/doc/source/advanced.rst → doc/source/user_guide/advanced.rst b/doc/source/advanced.rst → doc/source/user_guide/advanced.rst
diff --git a/doc/source/categorical.rst → doc/source/user_guide/categorical.rst b/doc/source/categorical.rst → doc/source/user_guide/categorical.rst
diff --git a/doc/source/computation.rst → doc/source/user_guide/computation.rst b/doc/source/computation.rst → doc/source/user_guide/computation.rst
diff --git a/doc/source/enhancingperf.rst → doc/source/user_guide/enhancingperf.rst b/doc/source/enhancingperf.rst → doc/source/user_guide/enhancingperf.rst
@@ -783,15 +783,15 @@ significant performance benefit.  Here is a plot showing the running time of
 computation. The two lines are two different engines.
 
 
-.. image:: _static/eval-perf.png
+.. image:: ../_static/eval-perf.png
 
 
 .. note::
 
    Operations with smallish objects (around 15k-20k rows) are faster using
    plain Python:
 
-       .. image:: _static/eval-perf-small.png
+       .. image:: ../_static/eval-perf-small.png
 
 
 This plot was created using a ``DataFrame`` with 3 columns each containing

diff --git a/doc/source/gotchas.rst → doc/source/user_guide/gotchas.rst b/doc/source/gotchas.rst → doc/source/user_guide/gotchas.rst
diff --git a/doc/source/groupby.rst → doc/source/user_guide/groupby.rst b/doc/source/groupby.rst → doc/source/user_guide/groupby.rst
diff --git a/doc/source/user_guide/index.rst b/doc/source/user_guide/index.rst
@@ -0,0 +1,39 @@
+{{ header }}
+
+.. _user_guide:
+
+==========
+User Guide
+==========
+
+The User Guide covers all of pandas by topic area. Each of the subsections
+introduces a topic (such as "working with missing data"), and discusses how
+pandas approaches the problem, with many examples throughout.
+
+Users brand-new to pandas should start with :ref:`10min`.
+
+Further information on any specific method can be obtained in the
+:ref:`api`.
+
+.. toctree::
+    :maxdepth: 2
+
+    io
+    indexing
+    advanced
+    merging
+    reshaping
+    text
+    missing_data
+    categorical
+    integer_na
+    visualization
+    computation
+    groupby
+    timeseries
+    timedeltas
+    style
+    options
+    enhancingperf
+    sparse
+    gotchas
diff --git a/doc/source/indexing.rst → doc/source/user_guide/indexing.rst b/doc/source/indexing.rst → doc/source/user_guide/indexing.rst
@@ -1392,15 +1392,15 @@ Performance of :meth:`~pandas.DataFrame.query`
 ``DataFrame.query()`` using ``numexpr`` is slightly faster than Python for
 large frames.
 
-.. image:: _static/query-perf.png
+.. image:: ../_static/query-perf.png
 
 .. note::
 
    You will only see the performance benefits of using the ``numexpr`` engine
    with ``DataFrame.query()`` if your frame has more than approximately 200,000
    rows.
 
-      .. image:: _static/query-perf-small.png
+      .. image:: ../_static/query-perf-small.png
 
 This plot was created using a ``DataFrame`` with 3 columns each containing
 floating point values generated using ``numpy.random.randn()``.

diff --git a/doc/source/integer_na.rst → doc/source/user_guide/integer_na.rst b/doc/source/integer_na.rst → doc/source/user_guide/integer_na.rst
diff --git a/doc/source/io.rst → doc/source/user_guide/io.rst b/doc/source/io.rst → doc/source/user_guide/io.rst
@@ -2549,7 +2549,7 @@ in the method ``to_string`` described above.
 HTML:
 
 .. raw:: html
-   :file: _static/basic.html
+   :file: ../_static/basic.html
 
 The ``columns`` argument will limit the columns shown:
 
@@ -2565,7 +2565,7 @@ The ``columns`` argument will limit the columns shown:
 HTML:
 
 .. raw:: html
-   :file: _static/columns.html
+   :file: ../_static/columns.html
 
 ``float_format`` takes a Python callable to control the precision of floating
 point values:
@@ -2582,7 +2582,7 @@ point values:
 HTML:
 
 .. raw:: html
-   :file: _static/float_format.html
+   :file: ../_static/float_format.html
 
 ``bold_rows`` will make the row labels bold by default, but you can turn that
 off:
@@ -2597,7 +2597,7 @@ off:
    write_html(df, 'nobold', bold_rows=False)
 
 .. raw:: html
-   :file: _static/nobold.html
+   :file: ../_static/nobold.html
 
 The ``classes`` argument provides the ability to give the resulting HTML
 table CSS classes. Note that these classes are *appended* to the existing
@@ -2627,7 +2627,7 @@ that contain URLs.
 HTML:
 
 .. raw:: html
-   :file: _static/render_links.html
+   :file: ../_static/render_links.html
 
 Finally, the ``escape`` argument allows you to control whether the
 "<", ">" and "&" characters escaped in the resulting HTML (by default it is
@@ -2651,7 +2651,7 @@ Escaped:
    print(df.to_html())
 
 .. raw:: html
-   :file: _static/escape.html
+   :file: ../_static/escape.html
 
 Not escaped:
 
@@ -2660,7 +2660,7 @@ Not escaped:
    print(df.to_html(escape=False))
 
 .. raw:: html
-   :file: _static/noescape.html
+   :file: ../_static/noescape.html
 
 .. note::
 

diff --git a/doc/source/merging.rst → doc/source/user_guide/merging.rst b/doc/source/merging.rst → doc/source/user_guide/merging.rst
diff --git a/doc/source/missing_data.rst → doc/source/user_guide/missing_data.rst b/doc/source/missing_data.rst → doc/source/user_guide/missing_data.rst
diff --git a/doc/source/options.rst → doc/source/user_guide/options.rst b/doc/source/options.rst → doc/source/user_guide/options.rst
@@ -487,7 +487,7 @@ If a DataFrame or Series contains these characters, the default output mode may
    df = pd.DataFrame({u'国籍': ['UK', u'日本'], u'名前': ['Alice', u'しのぶ']})
    df
 
-.. image:: _static/option_unicode01.png
+.. image:: ../_static/option_unicode01.png
 
 Enabling ``display.unicode.east_asian_width`` allows pandas to check each character's "East Asian Width" property.
 These characters can be aligned properly by setting this option to ``True``. However, this will result in longer render
@@ -498,7 +498,7 @@ times than the standard ``len`` function.
    pd.set_option('display.unicode.east_asian_width', True)
    df
 
-.. image:: _static/option_unicode02.png
+.. image:: ../_static/option_unicode02.png
 
 In addition, Unicode characters whose width is "Ambiguous" can either be 1 or 2 characters wide depending on the
 terminal setting or encoding. The option ``display.unicode.ambiguous_as_wide`` can be used to handle the ambiguity.
@@ -510,7 +510,7 @@ By default, an "Ambiguous" character's width, such as "¡" (inverted exclamation
    df = pd.DataFrame({'a': ['xxx', u'¡¡'], 'b': ['yyy', u'¡¡']})
    df
 
-.. image:: _static/option_unicode03.png
+.. image:: ../_static/option_unicode03.png
 
 Enabling ``display.unicode.ambiguous_as_wide`` makes pandas interpret these characters' widths to be 2.
 (Note that this option will only be effective when ``display.unicode.east_asian_width`` is enabled.)
@@ -522,7 +522,7 @@ However, setting this option incorrectly for your terminal will cause these char
    pd.set_option('display.unicode.ambiguous_as_wide', True)
    df
 
-.. image:: _static/option_unicode04.png
+.. image:: ../_static/option_unicode04.png
 
 .. ipython:: python
    :suppress:

diff --git a/doc/source/reshaping.rst → doc/source/user_guide/reshaping.rst b/doc/source/reshaping.rst → doc/source/user_guide/reshaping.rst
@@ -9,7 +9,7 @@ Reshaping and Pivot Tables
 Reshaping by pivoting DataFrame objects
 ---------------------------------------
 
-.. image:: _static/reshaping_pivot.png
+.. image:: ../_static/reshaping_pivot.png
 
 .. ipython:: python
    :suppress:
@@ -101,7 +101,7 @@ are homogeneously-typed.
 Reshaping by stacking and unstacking
 ------------------------------------
 
-.. image:: _static/reshaping_stack.png
+.. image:: ../_static/reshaping_stack.png
 
 Closely related to the :meth:`~DataFrame.pivot` method are the related
 :meth:`~DataFrame.stack` and :meth:`~DataFrame.unstack` methods available on
@@ -116,7 +116,7 @@ Closely related to the :meth:`~DataFrame.pivot` method are the related
   (possibly hierarchical) row index to the column axis, producing a reshaped
   ``DataFrame`` with a new inner-most level of column labels.
 
-.. image:: _static/reshaping_unstack.png
+.. image:: ../_static/reshaping_unstack.png
 
 The clearest way to explain is by example. Let's take a prior example data set
 from the hierarchical indexing section:
@@ -158,7 +158,7 @@ unstacks the **last level**:
 
 .. _reshaping.unstack_by_name:
 
-.. image:: _static/reshaping_unstack_1.png
+.. image:: ../_static/reshaping_unstack_1.png
 
 If the indexes have names, you can use the level names instead of specifying
 the level numbers:
@@ -168,7 +168,7 @@ the level numbers:
    stacked.unstack('second')
 
 
-.. image:: _static/reshaping_unstack_0.png
+.. image:: ../_static/reshaping_unstack_0.png
 
 Notice that the ``stack`` and ``unstack`` methods implicitly sort the index
 levels involved. Hence a call to ``stack`` and then ``unstack``, or vice versa,
@@ -279,7 +279,7 @@ the right thing:
 Reshaping by Melt
 -----------------
 
-.. image:: _static/reshaping_melt.png
+.. image:: ../_static/reshaping_melt.png
 
 The top-level :func:`~pandas.melt` function and the corresponding :meth:`DataFrame.melt`
 are useful to massage a ``DataFrame`` into a format where one or more columns

diff --git a/doc/source/sparse.rst → doc/source/user_guide/sparse.rst b/doc/source/sparse.rst → doc/source/user_guide/sparse.rst
diff --git a/doc/source/style.ipynb → doc/source/user_guide/style.ipynb b/doc/source/style.ipynb → doc/source/user_guide/style.ipynb
@@ -992,7 +992,7 @@
    "source": [
     "A screenshot of the output:\n",
     "\n",
-    "![Excel spreadsheet with styled DataFrame](_static/style-excel.png)\n"
+    "![Excel spreadsheet with styled DataFrame](../_static/style-excel.png)\n"
    ]
   },
   {

diff --git a/doc/source/text.rst → doc/source/user_guide/text.rst b/doc/source/text.rst → doc/source/user_guide/text.rst
diff --git a/doc/source/timedeltas.rst → doc/source/user_guide/timedeltas.rst b/doc/source/timedeltas.rst → doc/source/user_guide/timedeltas.rst
diff --git a/doc/source/timeseries.rst → doc/source/user_guide/timeseries.rst b/doc/source/timeseries.rst → doc/source/user_guide/timeseries.rst
diff --git a/doc/source/visualization.rst → doc/source/user_guide/visualization.rst b/doc/source/visualization.rst → doc/source/user_guide/visualization.rst