From b35bd041c1bf6b10f6796a54a6ae60283f469e8b Mon Sep 17 00:00:00 2001 From: stijnvanhoey Date: Mon, 13 Jan 2020 22:07:02 +0100 Subject: [PATCH 1/8] Add first update to general doc page --- doc/source/index.rst.template | 43 +++++++++++++++++++++++++++-------- 1 file changed, 33 insertions(+), 10 deletions(-) diff --git a/doc/source/index.rst.template b/doc/source/index.rst.template index 4ced92cbda81a..501faf98caa66 100644 --- a/doc/source/index.rst.template +++ b/doc/source/index.rst.template @@ -1,27 +1,50 @@ +:notoc: + .. pandas documentation master file, created by .. module:: pandas -********************************************* -pandas: powerful Python data analysis toolkit -********************************************* +******************** +pandas documentation +******************** **Date**: |today| **Version**: |version| **Download documentation**: `PDF Version `__ | `Zipped HTML `__ -**Useful links**: -`Binary Installers `__ | -`Source Repository `__ | +:mod:`pandas` is an open source, BSD-licensed library providing high-performance, +easy-to-use data structures and data analysis tools for the `Python `__ +programming language. + +---------------------------------- +How the documentation is organized +---------------------------------- + +Pandas has a lot of documentation. A high-level overview of how it’s organized will help you know where to look for certain things: + +TODO -> 4 blokken (cfr. coming from) + +- :ref:`getting_started` contains a :ref:`_gentle_intro` first introduction to some of the main pandas core concepts. Furthermore, it contains an overview of +:ref:`community_guides` community provided tutorials. +- :ref:`user_guide` provides in-depth information on the key concepts of pandas with useful background information and explanation. +- :ref:`api` contains a technical reference of the pandas API and available functionalities. The reference describes how the methods work and which parameters +can be used. It assumes that you have an understanding of the key concepts. +- Saw a typo in the documentation? Want to improve existing functionalities. The :ref:`development` guidelines will guide you through the process of setting up a development environment. + +------------ +Getting help +------------ + `Issues & Ideas `__ | `Q&A Support `__ | `Mailing List `__ -:mod:`pandas` is an open source, BSD-licensed library providing high-performance, -easy-to-use data structures and data analysis tools for the `Python `__ -programming language. +----------------------------- +pandas documentation overview +----------------------------- -See the :ref:`overview` for more detail about what's in the library. +`Binary Installers `__ | +`Source Repository `__ | {% if single_doc and single_doc.endswith('.rst') -%} .. toctree:: From 2de0f1304fa1470cc27d6f9f1d7f67a6b54f4cc4 Mon Sep 17 00:00:00 2001 From: stijnvanhoey Date: Mon, 20 Jan 2020 10:21:14 +0100 Subject: [PATCH 2/8] add boxes and css from getting started --- doc/source/_static/css/pandas.css | 62 +++++++++++++++++++++++++ doc/source/conf.py | 4 ++ doc/source/index.rst.template | 77 +++++++++++++++++++++++++++++++ 3 files changed, 143 insertions(+) create mode 100644 doc/source/_static/css/pandas.css diff --git a/doc/source/_static/css/pandas.css b/doc/source/_static/css/pandas.css new file mode 100644 index 0000000000000..39b5054ae937b --- /dev/null +++ b/doc/source/_static/css/pandas.css @@ -0,0 +1,62 @@ +/* Getting started index page */ + +.intro-card { + background: #fff; + border-radius: 0; + padding: 30px 10px 10px 10px; + margin: 10px 0px; +} + +.intro-card .card-text { + margin: 20px 0px; + /*min-height: 150px; */ +} + +.intro-card .card-img-top { + margin: 10px; +} + +.install-block { + padding-bottom: 30px; +} + +.install-card .card-header { + border: none; + background-color: white; + color: #150458; + font-size: 1.1rem; + font-weight: bold; + padding: 1rem 1rem 0rem 1rem; +} + +.install-card .card-footer { + border: none; + background-color: white; +} + +.install-card pre { + margin: 0 1em 1em 1em; +} + +.custom-button { + background-color: #dcdcdc; + border: none; + color: #484848; + text-align: center; + text-decoration: none; + display: inline-block; + font-size: 0.9rem; + border-radius: 0.5rem; + max-width: 120px; + padding: 0.5rem 0rem; +} + +.custom-button a { + color: #484848; +} + +.custom-button p { + margin-top: 0; + margin-bottom: 0rem; + color: #484848; +} diff --git a/doc/source/conf.py b/doc/source/conf.py index 7f24d02a496e1..08c21bb8d9bd5 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -230,6 +230,10 @@ # so a file named "default.css" will overwrite the builtin "default.css". html_static_path = ["_static"] +html_css_files = [ + "css/pandas.css", +] + # The name of an image file (within the static path) to use as favicon of the # docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 # pixels large. diff --git a/doc/source/index.rst.template b/doc/source/index.rst.template index 501faf98caa66..4dd9b691f2744 100644 --- a/doc/source/index.rst.template +++ b/doc/source/index.rst.template @@ -22,6 +22,83 @@ How the documentation is organized Pandas has a lot of documentation. A high-level overview of how it’s organized will help you know where to look for certain things: + +.. raw:: html + +
+
+
+
+ Getting started +
+

The R programming language provides the data.frame data structure and multiple packages, + such as tidyverse use and extend data.frames for convenient data handling + functionalities similar to pandas.

+ +.. container:: custom-button + + :ref:`Learn more ` + +.. raw:: html + +
+
+
+
+
+ SQL logo +
+

Already familiar to SELECT, GROUP BY, JOIN,...? + Most of these SQL manipulations do have equivalents in pandas.

+ +.. container:: custom-button + + :ref:`Learn more ` + +.. raw:: html + +
+
+
+
+
+ STATA logo +
+

The data set included in the + STATA statistical software suite corresponds + to the pandas data.frame. Many of the operations known from STATA have an equivalent + in pandas.

+ +.. container:: custom-button + + :ref:`Learn more ` + +.. raw:: html + +
+
+
+
+
+ SAS logo +
+

The SAS statistical software suite + also provides the data set corresponding to the pandas data.frame. + Also vectorized operations, filtering, string processing operations,... from SAS have similar + functions in pandas.

+ +.. container:: custom-button + + :ref:`Learn more ` + +.. raw:: html + +
+
+
+
+
+ TODO -> 4 blokken (cfr. coming from) - :ref:`getting_started` contains a :ref:`_gentle_intro` first introduction to some of the main pandas core concepts. Furthermore, it contains an overview of From 9b189ea6ab845dfb7c7444f5650095850e548681 Mon Sep 17 00:00:00 2001 From: Joris Van den Bossche Date: Mon, 20 Jan 2020 11:22:13 +0100 Subject: [PATCH 3/8] update content of cards --- doc/source/_static/css/pandas.css | 24 +------ doc/source/index.rst.template | 102 ++++++++++++------------------ 2 files changed, 40 insertions(+), 86 deletions(-) diff --git a/doc/source/_static/css/pandas.css b/doc/source/_static/css/pandas.css index 39b5054ae937b..84dbba823afa0 100644 --- a/doc/source/_static/css/pandas.css +++ b/doc/source/_static/css/pandas.css @@ -16,28 +16,6 @@ margin: 10px; } -.install-block { - padding-bottom: 30px; -} - -.install-card .card-header { - border: none; - background-color: white; - color: #150458; - font-size: 1.1rem; - font-weight: bold; - padding: 1rem 1rem 0rem 1rem; -} - -.install-card .card-footer { - border: none; - background-color: white; -} - -.install-card pre { - margin: 0 1em 1em 1em; -} - .custom-button { background-color: #dcdcdc; border: none; @@ -47,7 +25,7 @@ display: inline-block; font-size: 0.9rem; border-radius: 0.5rem; - max-width: 120px; + max-width: 220px; padding: 0.5rem 0rem; } diff --git a/doc/source/index.rst.template b/doc/source/index.rst.template index 4dd9b691f2744..f725cbeac1ce4 100644 --- a/doc/source/index.rst.template +++ b/doc/source/index.rst.template @@ -12,32 +12,32 @@ pandas documentation **Download documentation**: `PDF Version `__ | `Zipped HTML `__ +**Useful links**: +`Binary Installers `__ | +`Source Repository `__ | +`Issues & Ideas `__ | +`Q&A Support `__ | +`Mailing List `__ + :mod:`pandas` is an open source, BSD-licensed library providing high-performance, easy-to-use data structures and data analysis tools for the `Python `__ programming language. ----------------------------------- -How the documentation is organized ----------------------------------- - -Pandas has a lot of documentation. A high-level overview of how it’s organized will help you know where to look for certain things: - - .. raw:: html
- Getting started
-

The R programming language provides the data.frame data structure and multiple packages, - such as tidyverse use and extend data.frames for convenient data handling - functionalities similar to pandas.

+
Getting started
+

New to pandas? Check out the getting started guides. They + contain a first introduction to some of the main pandas concepts. Furthermore, + it contains an overview of community provided tutorials.

.. container:: custom-button - :ref:`Learn more ` + :ref:`To the getting started guides` .. raw:: html @@ -46,82 +46,58 @@ Pandas has a lot of documentation. A high-level overview of how it’s organized
- SQL logo
-

Already familiar to SELECT, GROUP BY, JOIN,...? - Most of these SQL manipulations do have equivalents in pandas.

+
User guide
+

The user guide provides in-depth information on the + key concepts of pandas with useful background information and explanation.

.. container:: custom-button - :ref:`Learn more ` + :ref:`To the user guide` .. raw:: html -
-
-
-
- STATA logo -
-

The data set included in the - STATA statistical software suite corresponds - to the pandas data.frame. Many of the operations known from STATA have an equivalent - in pandas.

+
+
+
+
+
+
API reference
+

The reference guide contains a detailed overview of + all functionalities in the pandas API. The reference describes how + the methods work and which parameters can be used. It assumes that you + have an understanding of the key concepts.

.. container:: custom-button - :ref:`Learn more ` + :ref:`To the reference guide` .. raw:: html -
-
-
-
- SAS logo -
-

The SAS statistical software suite - also provides the data set corresponding to the pandas data.frame. - Also vectorized operations, filtering, string processing operations,... from SAS have similar - functions in pandas.

+
+
+
+
+
+
Developer guide
+

Saw a typo in the documentation? Want to improve + existing functionalities? The contributing guidelines will guide + you through the process of setting up a development environment.

.. container:: custom-button - :ref:`Learn more ` + :ref:`To the development guide` .. raw:: html -
-
+
+
-TODO -> 4 blokken (cfr. coming from) - -- :ref:`getting_started` contains a :ref:`_gentle_intro` first introduction to some of the main pandas core concepts. Furthermore, it contains an overview of -:ref:`community_guides` community provided tutorials. -- :ref:`user_guide` provides in-depth information on the key concepts of pandas with useful background information and explanation. -- :ref:`api` contains a technical reference of the pandas API and available functionalities. The reference describes how the methods work and which parameters -can be used. It assumes that you have an understanding of the key concepts. -- Saw a typo in the documentation? Want to improve existing functionalities. The :ref:`development` guidelines will guide you through the process of setting up a development environment. - ------------- -Getting help ------------- - -`Issues & Ideas `__ | -`Q&A Support `__ | -`Mailing List `__ - ------------------------------ -pandas documentation overview ------------------------------ - -`Binary Installers `__ | -`Source Repository `__ | {% if single_doc and single_doc.endswith('.rst') -%} .. toctree:: From e72cd7c520131d6d7194d4e63228eeb72daa973a Mon Sep 17 00:00:00 2001 From: Joris Van den Bossche Date: Mon, 20 Jan 2020 11:28:58 +0100 Subject: [PATCH 4/8] remove manual table of contents --- doc/source/index.rst.template | 65 ----------------------------------- 1 file changed, 65 deletions(-) diff --git a/doc/source/index.rst.template b/doc/source/index.rst.template index f725cbeac1ce4..607da17ad1de2 100644 --- a/doc/source/index.rst.template +++ b/doc/source/index.rst.template @@ -126,68 +126,3 @@ programming language. development/index whatsnew/index {% endif %} - -* :doc:`whatsnew/v1.1.0` -* :doc:`getting_started/index` - - * :doc:`getting_started/install` - * :doc:`getting_started/overview` - * :doc:`getting_started/10min` - * :doc:`getting_started/basics` - * :doc:`getting_started/dsintro` - * :doc:`getting_started/comparison/index` - * :doc:`getting_started/tutorials` - -* :doc:`user_guide/index` - - * :doc:`user_guide/io` - * :doc:`user_guide/indexing` - * :doc:`user_guide/advanced` - * :doc:`user_guide/merging` - * :doc:`user_guide/reshaping` - * :doc:`user_guide/text` - * :doc:`user_guide/missing_data` - * :doc:`user_guide/categorical` - * :doc:`user_guide/integer_na` - * :doc:`user_guide/boolean` - * :doc:`user_guide/visualization` - * :doc:`user_guide/computation` - * :doc:`user_guide/groupby` - * :doc:`user_guide/timeseries` - * :doc:`user_guide/timedeltas` - * :doc:`user_guide/style` - * :doc:`user_guide/options` - * :doc:`user_guide/enhancingperf` - * :doc:`user_guide/scale` - * :doc:`user_guide/sparse` - * :doc:`user_guide/gotchas` - * :doc:`user_guide/cookbook` - -* :doc:`ecosystem` -* :doc:`reference/index` - - * :doc:`reference/io` - * :doc:`reference/general_functions` - * :doc:`reference/series` - * :doc:`reference/frame` - * :doc:`reference/arrays` - * :doc:`reference/panel` - * :doc:`reference/indexing` - * :doc:`reference/offset_frequency` - * :doc:`reference/window` - * :doc:`reference/groupby` - * :doc:`reference/resampling` - * :doc:`reference/style` - * :doc:`reference/plotting` - * :doc:`reference/general_utility_functions` - * :doc:`reference/extensions` - -* :doc:`development/index` - - * :doc:`development/contributing` - * :doc:`development/code_style` - * :doc:`development/internals` - * :doc:`development/extending` - * :doc:`development/developer` - -* :doc:`whatsnew/index` From c15c1c17c52e504e14038a202f0399d1c33a03ac Mon Sep 17 00:00:00 2001 From: stijnvanhoey Date: Mon, 20 Jan 2020 21:42:43 +0100 Subject: [PATCH 5/8] Add icons to cards --- doc/source/_static/index_api.svg | 97 ++++++++++++++++++++ doc/source/_static/index_contribute.svg | 76 +++++++++++++++ doc/source/_static/index_getting_started.svg | 66 +++++++++++++ doc/source/_static/index_user_guide.svg | 67 ++++++++++++++ doc/source/index.rst.template | 4 + 5 files changed, 310 insertions(+) create mode 100644 doc/source/_static/index_api.svg create mode 100644 doc/source/_static/index_contribute.svg create mode 100644 doc/source/_static/index_getting_started.svg create mode 100644 doc/source/_static/index_user_guide.svg diff --git a/doc/source/_static/index_api.svg b/doc/source/_static/index_api.svg new file mode 100644 index 0000000000000..70bf0d3504b1a --- /dev/null +++ b/doc/source/_static/index_api.svg @@ -0,0 +1,97 @@ + + + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + diff --git a/doc/source/_static/index_contribute.svg b/doc/source/_static/index_contribute.svg new file mode 100644 index 0000000000000..e86c3e9fd0b3e --- /dev/null +++ b/doc/source/_static/index_contribute.svg @@ -0,0 +1,76 @@ + + + + + + + + + + image/svg+xml + + + + + + + + + + + + diff --git a/doc/source/_static/index_getting_started.svg b/doc/source/_static/index_getting_started.svg new file mode 100644 index 0000000000000..d00e462427193 --- /dev/null +++ b/doc/source/_static/index_getting_started.svg @@ -0,0 +1,66 @@ + + + + + + + + + + image/svg+xml + + + + + + + + + diff --git a/doc/source/_static/index_user_guide.svg b/doc/source/_static/index_user_guide.svg new file mode 100644 index 0000000000000..a567103af5918 --- /dev/null +++ b/doc/source/_static/index_user_guide.svg @@ -0,0 +1,67 @@ + + + + + + + + + + image/svg+xml + + + + + + + + + diff --git a/doc/source/index.rst.template b/doc/source/index.rst.template index 607da17ad1de2..e7d5939547590 100644 --- a/doc/source/index.rst.template +++ b/doc/source/index.rst.template @@ -29,6 +29,7 @@ programming language.
+ getting started with pandas action icon
Getting started

New to pandas? Check out the getting started guides. They @@ -46,6 +47,7 @@ programming language.

+ pandas user guide action icon
User guide

The user guide provides in-depth information on the @@ -62,6 +64,7 @@ programming language.

+ api of pandas action icon
API reference

The reference guide contains a detailed overview of @@ -80,6 +83,7 @@ programming language.

+ contribute to pandas action icon
Developer guide

Saw a typo in the documentation? Want to improve From 1ea7971012975605194e0953b9c171f0406aa916 Mon Sep 17 00:00:00 2001 From: stijnvanhoey Date: Mon, 20 Jan 2020 22:05:46 +0100 Subject: [PATCH 6/8] Fix relative paths --- doc/source/index.rst.template | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/doc/source/index.rst.template b/doc/source/index.rst.template index e7d5939547590..5ec7a93ad4002 100644 --- a/doc/source/index.rst.template +++ b/doc/source/index.rst.template @@ -29,7 +29,7 @@ programming language.

- getting started with pandas action icon + getting started with pandas action icon
Getting started

New to pandas? Check out the getting started guides. They @@ -47,7 +47,7 @@ programming language.

- pandas user guide action icon + pandas user guide action icon
User guide

The user guide provides in-depth information on the @@ -64,7 +64,7 @@ programming language.

- api of pandas action icon + api of pandas action icon
API reference

The reference guide contains a detailed overview of @@ -83,7 +83,7 @@ programming language.

- contribute to pandas action icon + contribute to pandas action icon
Developer guide

Saw a typo in the documentation? Want to improve From 02d609caef003f23017162b99de25bd38bfe5ad9 Mon Sep 17 00:00:00 2001 From: Joris Van den Bossche Date: Fri, 24 Jan 2020 13:14:41 +0100 Subject: [PATCH 7/8] Apply suggestions from code review Co-Authored-By: Tom Augspurger --- doc/source/index.rst.template | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/doc/source/index.rst.template b/doc/source/index.rst.template index 5ec7a93ad4002..9f71c03c81844 100644 --- a/doc/source/index.rst.template +++ b/doc/source/index.rst.template @@ -33,7 +33,7 @@ programming language.

Getting started

New to pandas? Check out the getting started guides. They - contain a first introduction to some of the main pandas concepts. Furthermore, + contain an introduction to pandas' main concepts and links to additional tutorials. it contains an overview of community provided tutorials.

.. container:: custom-button @@ -67,8 +67,8 @@ programming language. api of pandas action icon
API reference
-

The reference guide contains a detailed overview of - all functionalities in the pandas API. The reference describes how +

The reference guide contains a detailed description of + the pandas API. The reference describes how the methods work and which parameters can be used. It assumes that you have an understanding of the key concepts.

@@ -88,7 +88,7 @@ programming language.
Developer guide

Saw a typo in the documentation? Want to improve existing functionalities? The contributing guidelines will guide - you through the process of setting up a development environment.

+ you through the process of improving pandas.

.. container:: custom-button From babdb718106cf080728708b725df321fbf43e068 Mon Sep 17 00:00:00 2001 From: Joris Van den Bossche Date: Fri, 24 Jan 2020 13:18:45 +0100 Subject: [PATCH 8/8] fixups --- doc/source/index.rst.template | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/doc/source/index.rst.template b/doc/source/index.rst.template index 9f71c03c81844..5690bb2e4a875 100644 --- a/doc/source/index.rst.template +++ b/doc/source/index.rst.template @@ -33,8 +33,7 @@ programming language.
Getting started

New to pandas? Check out the getting started guides. They - contain an introduction to pandas' main concepts and links to additional tutorials. - it contains an overview of community provided tutorials.

+ contain an introduction to pandas' main concepts and links to additional tutorials.

.. container:: custom-button @@ -68,9 +67,8 @@ programming language.
API reference

The reference guide contains a detailed description of - the pandas API. The reference describes how - the methods work and which parameters can be used. It assumes that you - have an understanding of the key concepts.

+ the pandas API. The reference describes how the methods work and which parameters can + be used. It assumes that you have an understanding of the key concepts.

.. container:: custom-button