Skip to content

DOC: Creating top-level user guide section, and moving pages inside #24677

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 7 commits into from
Jan 23, 2019
Merged

DOC: Creating top-level user guide section, and moving pages inside #24677

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
c20b02a
DOC: Moving user guide to its own directory to help navigation
datapythonista Dec 30, 2018
21967f5
Fixing typo in toctree formatting
datapythonista Dec 30, 2018
bd2aeb2
Merging from master
datapythonista Jan 9, 2019
256d622
Fixing path to static files
datapythonista Jan 9, 2019
9e90f4a
Updating excluded doc file from flake8-rst
datapythonista Jan 9, 2019
175ef47
Merging from master
datapythonista Jan 22, 2019
97f427e
Adding introductory text to the user guide index
datapythonista Jan 23, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 1 addition & 19 deletions doc/source/index.rst.template
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
0 doc/source/advanced.rst → doc/source/user_guide/advanced.rst
View file
Open in desktop
File renamed without changes.
0 doc/source/categorical.rst → doc/source/user_guide/categorical.rst
View file
Open in desktop
File renamed without changes.
0 doc/source/computation.rst → doc/source/user_guide/computation.rst
View file
Open in desktop
File renamed without changes.
4 changes: 2 additions & 2 deletions doc/source/enhancingperf.rst → doc/source/user_guide/enhancingperf.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
0 doc/source/gotchas.rst → doc/source/user_guide/gotchas.rst
View file
Open in desktop
File renamed without changes.
0 doc/source/groupby.rst → doc/source/user_guide/groupby.rst
View file
Open in desktop
File renamed without changes.
39 changes: 39 additions & 0 deletions doc/source/user_guide/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,39 @@
{{ header }}

.. _user_guide:

==========
User Guide
==========

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

A bit of introductory text here would be nice, explaining this section of the docs.

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 ... (10 min?)

Further information on any specific method can be obtained in the API reference.

We might also want to link to this page from a few places

  • overview
  • 10min
  • dsintro
  • basics

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I 100% agree, but it makes more sense to me to work on those in separate PRs after the whole restructure. There is already another PR for a top level "Getting started" section, that probably should be the linked for the "Users brand-new..." comment.

I think moving all the pages and finding an agreement on all the structures will actually take quite a lot of time, and will require a decent amount of discussion. That's why I'm proposing smaller PRs, to be able to keep some progress. Also, I think that will let us see the progress at every step, and make us move in the right direction (kind of agile methodology).

I mentioned it somewhere, but it was already work on trying to migrate all the documentation in a one-shot (see https://pandas-dev.github.io/pandas-sphinx-theme/pr-datapythonista_base/). After all the work on that, I think the approach will fail. If anyone else thinks a single PR or bigger PRs are better, I'm more than happy to leave this for someone else.

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
4 changes: 2 additions & 2 deletions doc/source/indexing.rst → doc/source/user_guide/indexing.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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()``.
Expand Down
0 doc/source/integer_na.rst → doc/source/user_guide/integer_na.rst
View file
Open in desktop
File renamed without changes.
14 changes: 7 additions & 7 deletions doc/source/io.rst → doc/source/user_guide/io.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:

Expand All @@ -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:
Expand All @@ -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:
Expand All @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -2651,7 +2651,7 @@ Escaped:
print(df.to_html())

.. raw:: html
:file: _static/escape.html
:file: ../_static/escape.html

Not escaped:

Expand All @@ -2660,7 +2660,7 @@ Not escaped:
print(df.to_html(escape=False))

.. raw:: html
:file: _static/noescape.html
:file: ../_static/noescape.html

.. note::

Expand Down
0 doc/source/merging.rst → doc/source/user_guide/merging.rst
View file
Open in desktop
File renamed without changes.
0 doc/source/missing_data.rst → doc/source/user_guide/missing_data.rst
View file
Open in desktop
File renamed without changes.
8 changes: 4 additions & 4 deletions doc/source/options.rst → doc/source/user_guide/options.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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.
Expand All @@ -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.)
Expand All @@ -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:
Expand Down
12 changes: 6 additions & 6 deletions doc/source/reshaping.rst → doc/source/user_guide/reshaping.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down Expand Up @@ -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
Expand All @@ -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:
Expand Down Expand Up @@ -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:
Expand All @@ -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,
Expand Down Expand Up @@ -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
Expand Down
0 doc/source/sparse.rst → doc/source/user_guide/sparse.rst
View file
Open in desktop
File renamed without changes.
2 changes: 1 addition & 1 deletion doc/source/style.ipynb → doc/source/user_guide/style.ipynb
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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"
]
},
{
Expand Down
0 doc/source/text.rst → doc/source/user_guide/text.rst
View file
Open in desktop
File renamed without changes.
0 doc/source/timedeltas.rst → doc/source/user_guide/timedeltas.rst
View file
Open in desktop
File renamed without changes.
0 doc/source/timeseries.rst → doc/source/user_guide/timeseries.rst
View file
Open in desktop
File renamed without changes.
0 doc/source/visualization.rst → doc/source/user_guide/visualization.rst
View file
Open in desktop
File renamed without changes.