Skip to content

DOC: Reorganize Getting Started documentation pages #32389

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 5 commits into from
Mar 11, 2020
Merged

DOC: Reorganize Getting Started documentation pages #32389

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
36ebffd
DOC: Reorganize Getting Started documentation pages
Mar 2, 2020
ac68cd2
Move some docs to user_guide, and adjust phrasing
Mar 3, 2020
7244976
Modify redirects, fix phrasing in getting_started
Mar 4, 2020
0a429a9
Merge remote-tracking branch 'upstream/master' into reorg_getting_sta…
Mar 6, 2020
1abd2f2
modify redirects
Mar 6, 2020
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
6 changes: 3 additions & 3 deletions doc/redirects.csv
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,13 +7,10 @@ release,whatsnew/index

# getting started
install,getting_started/install
10min,getting_started/10min
Copy link
Member Author

Choose a reason for hiding this comment

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

Not sure how to specify the redirects if they switch sections @jorisvandenbossche

Copy link
Member

Choose a reason for hiding this comment

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

I think this can be 10min,user_guide/10min ?

Copy link
Member Author

Choose a reason for hiding this comment

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

Perfect that worked.

basics,getting_started/basics
comparison_with_r,getting_started/comparison/comparison_with_r
comparison_with_sql,getting_started/comparison/comparison_with_sql
comparison_with_sas,getting_started/comparison/comparison_with_sas
comparison_with_stata,getting_started/comparison/comparison_with_stata
dsintro,getting_started/dsintro
overview,getting_started/overview
tutorials,getting_started/tutorials

Expand All @@ -38,6 +35,9 @@ text,user_guide/text
timedeltas,user_guide/timedeltas
timeseries,user_guide/timeseries
visualization,user_guide/visualization
10min,user_guide/10min
basics,user_guide/basics
dsintro,user_guide/dsintro

# development
contributing,development/contributing
Expand Down
51 changes: 25 additions & 26 deletions doc/source/getting_started/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,8 +9,6 @@ Getting started
Installation
------------

Before you can use pandas, you’ll need to get it installed.

.. raw:: html

<div class="container">
Expand All @@ -23,7 +21,7 @@ Before you can use pandas, you’ll need to get it installed.
<div class="card-body">
<p class="card-text">

Pandas is part of the `Anaconda <http://docs.continuum.io/anaconda/>`__ distribution and can be
pandas is part of the `Anaconda <http://docs.continuum.io/anaconda/>`__ distribution and can be
Copy link
Member

@MarcoGorelli MarcoGorelli Mar 2, 2020 •
edited
Loading

Choose a reason for hiding this comment

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

in #32388 , pandas is being written

*pandas*

, should that be done here as well for consistency?

Copy link
Member Author

Choose a reason for hiding this comment

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

We want to move *pandas* to pandas #32316

installed with Anaconda or Miniconda:

.. raw:: html
Expand All @@ -49,7 +47,7 @@ installed with Anaconda or Miniconda:
<div class="card-body">
<p class="card-text">

Pandas can be installed via pip from `PyPI <https://pypi.org/project/pandas>`__.
pandas can be installed via pip from `PyPI <https://pypi.org/project/pandas>`__.

.. raw:: html

Expand Down Expand Up @@ -103,7 +101,7 @@ Intro to pandas
<div class="d-flex flex-row tutorial-card-header-1">
<div class="d-flex flex-row tutorial-card-header-2">
<button class="btn btn-dark btn-sm"></button>
What kind of data does Pandas handle?
What kind of data does pandas handle?
</div>
<span class="badge gs-badge-link">

Expand All @@ -117,8 +115,8 @@ Intro to pandas
<div id="collapseOne" class="collapse" data-parent="#accordion">
<div class="card-body">

When working with tabular data, such as data stored in spreadsheets or databases, Pandas is the right tool for you. Pandas will help you
to explore, clean and process your data. In Pandas, a data table is called a :class:`DataFrame`.
When working with tabular data, such as data stored in spreadsheets or databases, pandas is the right tool for you. pandas will help you
to explore, clean and process your data. In pandas, a data table is called a :class:`DataFrame`.

.. image:: ../_static/schemas/01_table_dataframe.svg
:align: center
Expand Down Expand Up @@ -164,7 +162,7 @@ to explore, clean and process your data. In Pandas, a data table is called a :cl
<div id="collapseTwo" class="collapse" data-parent="#accordion">
<div class="card-body">

Pandas supports the integration with many file formats or data sources out of the box (csv, excel, sql, json, parquet,…). Importing data from each of these
pandas supports the integration with many file formats or data sources out of the box (csv, excel, sql, json, parquet,…). Importing data from each of these
data sources is provided by function with the prefix ``read_*``. Similarly, the ``to_*`` methods are used to store data.

.. image:: ../_static/schemas/02_io_readwrite.svg
Expand Down Expand Up @@ -212,7 +210,7 @@ data sources is provided by function with the prefix ``read_*``. Similarly, the
<div class="card-body">

Selecting or filtering specific rows and/or columns? Filtering the data on a condition? Methods for slicing, selecting, and extracting the
data you need are available in Pandas.
data you need are available in pandas.

.. image:: ../_static/schemas/03_subset_columns_rows.svg
:align: center
Expand Down Expand Up @@ -258,7 +256,7 @@ data you need are available in Pandas.
<div id="collapseFour" class="collapse" data-parent="#accordion">
<div class="card-body">

Pandas provides plotting your data out of the box, using the power of Matplotlib. You can pick the plot type (scatter, bar, boxplot,...)
pandas provides plotting your data out of the box, using the power of Matplotlib. You can pick the plot type (scatter, bar, boxplot,...)
corresponding to your data.

.. image:: ../_static/schemas/04_plot_overview.svg
Expand Down Expand Up @@ -492,7 +490,7 @@ Multiple tables can be concatenated both column wise as row wise and database-li
<div id="collapseNine" class="collapse" data-parent="#accordion">
<div class="card-body">

Pandas has great support for time series and has an extensive set of tools for working with dates, times, and time-indexed data.
pandas has great support for time series and has an extensive set of tools for working with dates, times, and time-indexed data.

.. raw:: html

Expand Down Expand Up @@ -535,7 +533,7 @@ Pandas has great support for time series and has an extensive set of tools for w
<div id="collapseTen" class="collapse" data-parent="#accordion">
<div class="card-body">

Data sets do not only contain numerical data. Pandas provides a wide range of functions to cleaning textual data and extract useful information from it.
Data sets do not only contain numerical data. pandas provides a wide range of functions to cleaning textual data and extract useful information from it.

.. raw:: html

Expand Down Expand Up @@ -568,9 +566,8 @@ Data sets do not only contain numerical data. Pandas provides a wide range of fu
Coming from...
--------------

Currently working with other software for data manipulation in a tabular format? You're probably familiar to typical
data operations and know *what* to do with your tabular data, but lacking the syntax to execute these operations. Get to know
the pandas syntax by looking for equivalents from the software you already know:
Are you familiar with other software for manipulating tablular data? Learn
the pandas-equivalent operations compared to software you already know:

.. raw:: html

Expand All @@ -580,7 +577,7 @@ the pandas syntax by looking for equivalents from the software you already know:
<div class="card text-center intro-card shadow">
<img src="../_static/logo_r.svg" class="card-img-top" alt="R project logo" height="72">
<div class="card-body flex-fill">
<p class="card-text">The <a href="https://www.r-project.org/">R programming language</a> provides the <code>data.frame</code> data structure and multiple packages,
<p class="card-text">The <a href="https://www.r-project.org/">R programming language</a> provides the <code>dataframe</code> data structure and multiple packages,
such as <a href="https://www.tidyverse.org/">tidyverse</a> use and extend <code>data.frame</code>s for convenient data handling
functionalities similar to pandas.</p>

Expand All @@ -597,7 +594,7 @@ the pandas syntax by looking for equivalents from the software you already know:
<div class="card text-center intro-card shadow">
<img src="../_static/logo_sql.svg" class="card-img-top" alt="SQL logo" height="72">
<div class="card-body flex-fill">
<p class="card-text">Already familiar to <code>SELECT</code>, <code>GROUP BY</code>, <code>JOIN</code>,...?
<p class="card-text">Already familiar to <code>SELECT</code>, <code>GROUP BY</code>, <code>JOIN</code>, etc.?
Most of these SQL manipulations do have equivalents in pandas.</p>

.. container:: custom-button
Expand All @@ -615,7 +612,7 @@ the pandas syntax by looking for equivalents from the software you already know:
<div class="card-body flex-fill">
<p class="card-text">The <code>data set</code> included in the
<a href="https://en.wikipedia.org/wiki/Stata">STATA</a> statistical software suite corresponds
to the pandas <code>data.frame</code>. Many of the operations known from STATA have an equivalent
to the pandas <code>dataframe</code>. Many of the operations known from STATA have an equivalent
in pandas.</p>

.. container:: custom-button
Expand All @@ -632,8 +629,8 @@ the pandas syntax by looking for equivalents from the software you already know:
<img src="../_static/logo_sas.svg" class="card-img-top" alt="SAS logo" height="52">
<div class="card-body flex-fill">
<p class="card-text">The <a href="https://en.wikipedia.org/wiki/SAS_(software)">SAS</a> statistical software suite
also provides the <code>data set</code> corresponding to the pandas <code>data.frame</code>.
Also vectorized operations, filtering, string processing operations,... from SAS have similar
also provides the <code>data set</code> corresponding to the pandas <code>dataframe</code>.
Also SAS vectorized operations, filtering, string processing operations, and more have similar
functions in pandas.</p>

.. container:: custom-button
Expand All @@ -648,11 +645,16 @@ the pandas syntax by looking for equivalents from the software you already know:
</div>
</div>

Community tutorials
-------------------
Tutorials
---------

For a quick overview of pandas functionality, see :ref:`10 Minutes to pandas<10min>`.

You can also reference the pandas `cheat sheet <https://pandas.pydata.org/Pandas_Cheat_Sheet.pdf>`_
for a succinct guide for manipulating data with pandas.

The community produces a wide variety of tutorials available online. Some of the
material is enlisted in the community contributed :ref:`tutorials`.
material is enlisted in the community contributed :ref:`communitytutorials`.


.. If you update this toctree, also update the manual toctree in the
Expand All @@ -664,9 +666,6 @@ material is enlisted in the community contributed :ref:`tutorials`.

install
overview
10min
intro_tutorials/index
basics
dsintro
Copy link
Member

Choose a reason for hiding this comment

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

I don't think we should just remove basics and dsintro, but keep them somewhere in the docs. I personally would move them to the user guide, but so that means they need to be added to the toctree there if we want to do that.

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 added them as links in the user guide but hadn't added it to the toctree there yet.

https://github.com/pandas-dev/pandas/pull/32389/files#diff-e81313c8de3a67eb46e6744b7c895af2R15

comparison/index
tutorials
22 changes: 5 additions & 17 deletions doc/source/getting_started/tutorials.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,24 +1,12 @@
.. _tutorials:
.. _communitytutorials:

{{ header }}

*********
Tutorials
*********
*******************
Community Tutorials
*******************

This is a guide to many pandas tutorials, geared mainly for new users.

Internal guides
===============

pandas' own :ref:`10 Minutes to pandas<10min>`.

More complex recipes are in the :ref:`Cookbook<cookbook>`.

A handy pandas `cheat sheet <https://pandas.pydata.org/Pandas_Cheat_Sheet.pdf>`_.

Community guides
================
This is a guide to many pandas tutorials by the community, geared mainly for new users.

pandas Cookbook by Julia Evans
------------------------------
Expand Down
0 doc/source/getting_started/10min.rst → doc/source/user_guide/10min.rst
View file
Open in desktop
File renamed without changes.
0 doc/source/getting_started/basics.rst → doc/source/user_guide/basics.rst
View file
Open in desktop
File renamed without changes.
0 doc/source/getting_started/dsintro.rst → doc/source/user_guide/dsintro.rst
View file
Open in desktop
File renamed without changes.
5 changes: 5 additions & 0 deletions doc/source/user_guide/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,8 @@ pandas approaches the problem, with many examples throughout.

Users brand-new to pandas should start with :ref:`10min`.

For a high level summary of the pandas fundamentals, see :ref:`dsintro` and :ref:`basics`.

Further information on any specific method can be obtained in the
:ref:`api`.

Expand All @@ -21,6 +23,9 @@ Further information on any specific method can be obtained in the
.. toctree::
:maxdepth: 2

10min
dsintro
basics
io
indexing
advanced
Expand Down