From f530adcf33c696828fa2208f81503b57f02057e3 Mon Sep 17 00:00:00 2001 From: Joris Van den Bossche Date: Fri, 8 May 2020 12:42:32 +0200 Subject: [PATCH 1/8] DOC: use the sphinx-panels extension for cards instead of raw html --- doc/source/conf.py | 5 ++ doc/source/getting_started/index.rst | 85 ++++++++-------------------- 2 files changed, 30 insertions(+), 60 deletions(-) diff --git a/doc/source/conf.py b/doc/source/conf.py index ee0d4ca3f2a24..b66b5ad18d860 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -65,6 +65,7 @@ "sphinx.ext.ifconfig", "sphinx.ext.linkcode", "nbsphinx", + "sphinx_panels", "contributors", # custom pandas extension ] @@ -125,6 +126,10 @@ # nbsphinx do not use requirejs (breaks bootstrap) nbsphinx_requirejs_path = "" +# sphinx-panels shouldn't add bootstrap css since the pydata-sphinx-theme +# already loads it +panels_add_boostrap_css = False + # Add any paths that contain templates here, relative to this directory. templates_path = ["../_templates"] diff --git a/doc/source/getting_started/index.rst b/doc/source/getting_started/index.rst index eb7ee000a9a86..02391eb5e04ff 100644 --- a/doc/source/getting_started/index.rst +++ b/doc/source/getting_started/index.rst @@ -9,82 +9,47 @@ Getting started Installation ------------ -.. raw:: html +.. panels:: + :card: shadow install-card + :column: col-lg-6 col-md-6 col-sm-12 col-xs-12 p-3 -
-
-
-
-
- Working with conda? -
-
-

+ Working with conda? + ^^^^^^^^^^^^^^^^^^^ -pandas is part of the `Anaconda `__ distribution and can be -installed with Anaconda or Miniconda: + pandas is part of the `Anaconda `__ + distribution and can be installed with Anaconda or Miniconda: -.. raw:: html + ++++++++++++++++++++++ -

-
-
+ .. code-block:: bash -.. code-block:: bash + conda install pandas - conda install pandas + ... -.. raw:: html + Prefer pip? + ^^^^^^^^^^^ -
-
-
-
-
-
- Prefer pip? -
-
-

+ pandas can be installed via pip from `PyPI `__. -pandas can be installed via pip from `PyPI `__. + ++++ -.. raw:: html + .. code-block:: bash -

-
-
+ conda install pandas -.. code-block:: bash + ... + column = col-12 p-3 - pip install pandas + In-depth instructions? + ^^^^^^^^^^^^^^^^^^^^^^ -.. raw:: html + Installing a specific version? Installing from source? Check the advanced + installation page. -
-
-
-
-
-
- In-depth instructions? -
-
-

Installing a specific version? - Installing from source? - Check the advanced installation page.

- -.. container:: custom-button - - :ref:`Learn more ` + .. container:: custom-button -.. raw:: html - -
-
-
-
-
+ :ref:`Learn more ` .. _gentle_intro: From a5716c1d683a2826588a8bba2b18c58d8e296aaa Mon Sep 17 00:00:00 2001 From: Joris Van den Bossche Date: Sat, 9 May 2020 09:47:58 +0200 Subject: [PATCH 2/8] update syntax --- doc/source/getting_started/index.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/doc/source/getting_started/index.rst b/doc/source/getting_started/index.rst index 02391eb5e04ff..27f1e17b3266e 100644 --- a/doc/source/getting_started/index.rst +++ b/doc/source/getting_started/index.rst @@ -10,7 +10,7 @@ Installation ------------ .. panels:: - :card: shadow install-card + :card: + install-card :column: col-lg-6 col-md-6 col-sm-12 col-xs-12 p-3 Working with conda? @@ -25,7 +25,7 @@ Installation conda install pandas - ... + --- Prefer pip? ^^^^^^^^^^^ @@ -38,8 +38,8 @@ Installation conda install pandas - ... - column = col-12 p-3 + --- + :column: col-12 p-3 In-depth instructions? ^^^^^^^^^^^^^^^^^^^^^^ From f0784290d0fd3f4a5e1da95be0e0d70ed531b280 Mon Sep 17 00:00:00 2001 From: Joris Van den Bossche Date: Sun, 28 Mar 2021 11:36:02 +0200 Subject: [PATCH 3/8] convert + style front page cards --- doc/source/_static/css/getting_started.css | 6 +- doc/source/_static/css/pandas.css | 48 ++++--- doc/source/conf.py | 2 +- doc/source/getting_started/index.rst | 10 +- doc/source/index.rst.template | 145 ++++++++++----------- 5 files changed, 105 insertions(+), 106 deletions(-) diff --git a/doc/source/_static/css/getting_started.css b/doc/source/_static/css/getting_started.css index bb24761cdb159..e6a977d9f38aa 100644 --- a/doc/source/_static/css/getting_started.css +++ b/doc/source/_static/css/getting_started.css @@ -131,19 +131,19 @@ ul.task-bullet > li > p:first-child { /* Getting started index page */ -.intro-card { +.comparison-card { background:#FFF; border-radius:0; padding: 30px 10px 10px 10px; margin: 10px 0px; } -.intro-card .card-text { +.comparison-card .card-text { margin:20px 0px; /*min-height: 150px; */ } -.intro-card .card-img-top { +.comparison-card .card-img-top { margin: 10px; } diff --git a/doc/source/_static/css/pandas.css b/doc/source/_static/css/pandas.css index 87357fd8ae716..d493723517b96 100644 --- a/doc/source/_static/css/pandas.css +++ b/doc/source/_static/css/pandas.css @@ -5,39 +5,45 @@ --pst-color-info: 23, 162, 184; } -/* Getting started index page */ +/* Main index page overview cards */ .intro-card { background: #fff; border-radius: 0; - padding: 30px 10px 10px 10px; + padding: 30px 10px 20px 10px; margin: 10px 0px; } -.intro-card .card-text { - margin: 20px 0px; - /*min-height: 150px; */ +.intro-card p.card-text { + margin: 0px; } -.custom-button { - background-color: #dcdcdc; +.intro-card .card-img-top { + margin: 10px; + height: 52px; +} + +.intro-card .card-header { border: none; - color: #484848; - text-align: center; - text-decoration: none; - display: inline-block; - font-size: 0.9rem; - border-radius: 0.5rem; - max-width: 220px; - padding: 0.5rem 0rem; + background-color:white; + color: #150458 !important; + font-size: var(--pst-font-size-h5); + font-weight: bold; + padding: 2.5rem 0rem 0.5rem 0rem; +} + +.intro-card .card-footer { + border: none; + background-color:white; } -.custom-button a { - color: #484848; +.intro-card .card-footer { + border: none; + background-color:white; } -.custom-button p { - margin-top: 0; - margin-bottom: 0rem; - color: #484848; +.intro-card .card-footer p.card-text{ + max-width: 220px; + margin-left: auto; + margin-right: auto; } diff --git a/doc/source/conf.py b/doc/source/conf.py index c355cdea1c521..8df048ce65582 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -142,7 +142,7 @@ # sphinx-panels shouldn't add bootstrap css since the pydata-sphinx-theme # already loads it -panels_add_boostrap_css = False +panels_add_bootstrap_css = False # Add any paths that contain templates here, relative to this directory. templates_path = ["../_templates"] diff --git a/doc/source/getting_started/index.rst b/doc/source/getting_started/index.rst index ce8b95b34fcef..bbbcf261ed18d 100644 --- a/doc/source/getting_started/index.rst +++ b/doc/source/getting_started/index.rst @@ -539,7 +539,7 @@ the pandas-equivalent operations compared to software you already know:
-
+
R project logo

The R programming language provides the dataframe data structure and multiple packages, @@ -556,7 +556,7 @@ the pandas-equivalent operations compared to software you already know:

-
+
SQL logo

Already familiar to SELECT, GROUP BY, JOIN, etc.? @@ -572,7 +572,7 @@ the pandas-equivalent operations compared to software you already know:

-
+
STATA logo

The data set included in the @@ -590,7 +590,7 @@ the pandas-equivalent operations compared to software you already know:

-
+
Excel logo

Users of Excel @@ -606,7 +606,7 @@ the pandas-equivalent operations compared to software you already know:

-
+
SAS logo

The SAS statistical software suite diff --git a/doc/source/index.rst.template b/doc/source/index.rst.template index c6deb4b7ea383..51a6807b30e2a 100644 --- a/doc/source/index.rst.template +++ b/doc/source/index.rst.template @@ -23,82 +23,75 @@ pandas documentation easy-to-use data structures and data analysis tools for the `Python `__ programming language. -.. raw:: html - -

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

New to pandas? Check out the getting started guides. They - contain an introduction to pandas' main concepts and links to additional tutorials.

- -.. container:: custom-button - - :ref:`To the getting started guides` - -.. raw:: html - -
-
-
-
-
- pandas user guide action icon -
-
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:`To the user guide` - -.. raw:: html - -
-
-
-
-
- api of pandas action icon -
-
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.

- -.. container:: custom-button - - :ref:`To the reference guide` - -.. raw:: html - -
-
-
-
-
- contribute to pandas action icon -
-
Developer guide
-

Saw a typo in the documentation? Want to improve - existing functionalities? The contributing guidelines will guide - you through the process of improving pandas.

- -.. container:: custom-button - - :ref:`To the development guide` - -.. raw:: html - -
-
-
-
-
+.. panels:: + :card: + intro-card text-center + :column: col-lg-6 col-md-6 col-sm-6 col-xs-12 d-flex + + --- + :img-top: _static/index_getting_started.svg + + Getting started + ^^^^^^^^^^^^^^^ + + New to *pandas*? Check out the getting started guides. They contain an + introduction to *pandas'* main concepts and links to additional tutorials. + + +++ + + .. link-button:: getting_started + :type: ref + :text: To the getting started guides + :classes: btn-block btn-secondary stretched-link + + --- + :img-top: _static/index_user_guide.svg + + User guide + ^^^^^^^^^^ + + The user guide provides in-depth information on the + key concepts of pandas with useful background information and explanation. + + +++ + + .. link-button:: user_guide + :type: ref + :text: To the user guide + :classes: btn-block btn-secondary stretched-link + + --- + :img-top: _static/index_api.svg + + 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. + + +++ + + .. link-button:: api + :type: ref + :text: To the reference guide + :classes: btn-block btn-secondary stretched-link + + --- + :img-top: _static/index_contribute.svg + + Developer guide + ^^^^^^^^^^^^^^^ + + Saw a typo in the documentation? Want to improve + existing functionalities? The contributing guidelines will guide + you through the process of improving pandas. + + +++ + + .. link-button:: development + :type: ref + :text: To the development guide + :classes: btn-block btn-secondary stretched-link {% if single_doc and single_doc.endswith('.rst') -%} From e4346a56f6b6b8d73928fc4ab397fd01a5cfe36a Mon Sep 17 00:00:00 2001 From: Joris Van den Bossche Date: Sun, 28 Mar 2021 13:35:44 +0200 Subject: [PATCH 4/8] add sphinx-panels to requirements --- environment.yml | 1 + requirements-dev.txt | 1 + 2 files changed, 2 insertions(+) diff --git a/environment.yml b/environment.yml index 1259d0dd4ae44..540e62bc18d1d 100644 --- a/environment.yml +++ b/environment.yml @@ -32,6 +32,7 @@ dependencies: - gitpython # obtain contributors from git for whatsnew - gitdb - sphinx + - sphinx-panels # documentation (jupyter notebooks) - nbconvert>=5.4.1 diff --git a/requirements-dev.txt b/requirements-dev.txt index 1817d79f96139..d194c1748e32e 100644 --- a/requirements-dev.txt +++ b/requirements-dev.txt @@ -18,6 +18,7 @@ pyupgrade gitpython gitdb sphinx +sphinx-panels nbconvert>=5.4.1 nbsphinx pandoc From ab11841efa330813429038e31f070ef0b7a9c495 Mon Sep 17 00:00:00 2001 From: Joris Van den Bossche Date: Thu, 8 Apr 2021 09:00:11 +0200 Subject: [PATCH 5/8] fixup install cards --- doc/source/_static/css/getting_started.css | 5 ++++- doc/source/getting_started/index.rst | 6 ++++-- 2 files changed, 8 insertions(+), 3 deletions(-) diff --git a/doc/source/_static/css/getting_started.css b/doc/source/_static/css/getting_started.css index e6a977d9f38aa..45f3ddc331e35 100644 --- a/doc/source/_static/css/getting_started.css +++ b/doc/source/_static/css/getting_started.css @@ -154,10 +154,13 @@ ul.task-bullet > li > p:first-child { .install-card .card-header { border: none; background-color:white; + padding: 1rem 1rem 0rem 1rem; +} + +.install-card .card-header p.card-text { color: #150458; font-size: 1.1rem; font-weight: bold; - padding: 1rem 1rem 0rem 1rem; } .install-card .card-footer { diff --git a/doc/source/getting_started/index.rst b/doc/source/getting_started/index.rst index bbbcf261ed18d..f9f7d4e548650 100644 --- a/doc/source/getting_started/index.rst +++ b/doc/source/getting_started/index.rst @@ -47,9 +47,11 @@ Installation Installing a specific version? Installing from source? Check the advanced installation page. - .. container:: custom-button + .. link-button:: install + :type: ref + :text: Learn more + :classes: btn-secondary stretched-link - :ref:`Learn more ` .. _gentle_intro: From cded67326b213494ee4b49c46e74db90c424aec4 Mon Sep 17 00:00:00 2001 From: Joris Van den Bossche Date: Thu, 8 Apr 2021 09:38:04 +0200 Subject: [PATCH 6/8] also convert the comparison cards --- doc/source/_static/css/getting_started.css | 16 ++- doc/source/_static/css/pandas.css | 5 - doc/source/getting_started/index.rst | 133 ++++++++++----------- 3 files changed, 76 insertions(+), 78 deletions(-) diff --git a/doc/source/_static/css/getting_started.css b/doc/source/_static/css/getting_started.css index 45f3ddc331e35..84eafa308175c 100644 --- a/doc/source/_static/css/getting_started.css +++ b/doc/source/_static/css/getting_started.css @@ -138,13 +138,23 @@ ul.task-bullet > li > p:first-child { margin: 10px 0px; } -.comparison-card .card-text { - margin:20px 0px; - /*min-height: 150px; */ +.comparison-card p.card-text { + margin: 0px; } .comparison-card .card-img-top { margin: 10px; + margin-bottom: 20px; + height: 72px; +} + +.comparison-card-excel .card-img-top, .comparison-card-stata .card-img-top, .comparison-card-sas .card-img-top { + height: 52px; +} + +.comparison-card .card-footer { + border: none; + background-color:white; } .install-block { diff --git a/doc/source/_static/css/pandas.css b/doc/source/_static/css/pandas.css index d493723517b96..452c7d20ff5df 100644 --- a/doc/source/_static/css/pandas.css +++ b/doc/source/_static/css/pandas.css @@ -37,11 +37,6 @@ background-color:white; } -.intro-card .card-footer { - border: none; - background-color:white; -} - .intro-card .card-footer p.card-text{ max-width: 220px; margin-left: auto; diff --git a/doc/source/getting_started/index.rst b/doc/source/getting_started/index.rst index f9f7d4e548650..8e40bf63f3680 100644 --- a/doc/source/getting_started/index.rst +++ b/doc/source/getting_started/index.rst @@ -536,97 +536,90 @@ Coming from... Are you familiar with other software for manipulating tablular data? Learn the pandas-equivalent operations compared to software you already know: -.. raw:: html +.. panels:: + :card: + comparison-card text-center shadow + :column: col-lg-6 col-md-6 col-sm-6 col-xs-12 d-flex -
-
-
-
- R project logo -
-

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

+ --- + :card: + comparison-card-r + :img-top: ../_static/logo_r.svg -.. container:: custom-button + The `R programming language `__ provides the + ``data.frame`` data structure and multiple packages, such as + `tidyverse `__ use and extend ``data.frame`` + for convenient data handling functionalities similar to pandas. - :ref:`Learn more ` + +++ -.. raw:: html + .. link-button:: compare_with_r + :type: ref + :text: Learn more + :classes: btn-secondary stretched-link -
-
-
-
-
- SQL logo -
-

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

-.. container:: custom-button + --- + :card: + comparison-card-sql + :img-top: ../_static/logo_sql.svg - :ref:`Learn more ` + Already familiar to ``SELECT``, ``GROUP BY``, ``JOIN``, etc.? + Most of these SQL manipulations do have equivalents in pandas. -.. raw:: html + +++ -
-
-
-
-
- STATA logo -
-

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

+ .. link-button:: compare_with_sql + :type: ref + :text: Learn more + :classes: btn-secondary stretched-link -.. container:: custom-button - :ref:`Learn more ` + --- + :card: + comparison-card-stata + :img-top: ../_static/logo_stata.svg -.. raw:: html + The ``data set`` included in the `STATA `__ + statistical software suite corresponds to the pandas ``DataFrame``. + Many of the operations known from STATA have an equivalent in pandas. -
-
-
-
-
- Excel logo -
-

Users of Excel - or other spreadsheet programs will find that many of the concepts are transferrable to pandas.

+ +++ -.. container:: custom-button + .. link-button:: compare_with_stata + :type: ref + :text: Learn more + :classes: btn-secondary stretched-link - :ref:`Learn more ` -.. raw:: html + --- + :card: + comparison-card-excel + :img-top: ../_static/spreadsheets/logo_excel.svg -
-
-
-
-
- SAS logo -
-

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

+ Users of `Excel `__ + or other spreadsheet programs will find that many of the concepts are + transferrable to pandas. -.. container:: custom-button + +++ - :ref:`Learn more ` + .. link-button:: compare_with_spreadsheets + :type: ref + :text: Learn more + :classes: btn-secondary stretched-link -.. raw:: html -
-
-
-
-
+ --- + :card: + comparison-card-sas + :img-top: ../_static/logo_sas.svg + + The `SAS `__ statistical software suite + also provides the ``data set`` corresponding to the pandas ``DataFrame``. + Also SAS vectorized operations, filtering, string processing operations, + and more have similar functions in pandas. + + +++ + + .. link-button:: compare_with_sas + :type: ref + :text: Learn more + :classes: btn-secondary stretched-link + Tutorials --------- From d3cf39989e5de2849da73eb2d1cb2ad8f9bc66d2 Mon Sep 17 00:00:00 2001 From: Joris Van den Bossche Date: Thu, 8 Apr 2021 11:04:03 +0200 Subject: [PATCH 7/8] workaround ambiguous install ref --- doc/source/getting_started/index.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/source/getting_started/index.rst b/doc/source/getting_started/index.rst index 8e40bf63f3680..16a58e7532008 100644 --- a/doc/source/getting_started/index.rst +++ b/doc/source/getting_started/index.rst @@ -47,8 +47,8 @@ Installation Installing a specific version? Installing from source? Check the advanced installation page. - .. link-button:: install - :type: ref + .. link-button:: ./install.html + :type: url :text: Learn more :classes: btn-secondary stretched-link From 1ecbdb7e8d3dc261437e4a82ea26c21e89ad7c05 Mon Sep 17 00:00:00 2001 From: Joris Van den Bossche Date: Thu, 8 Apr 2021 21:11:47 +0200 Subject: [PATCH 8/8] conda/pip typo --- doc/source/getting_started/index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/source/getting_started/index.rst b/doc/source/getting_started/index.rst index 16a58e7532008..4792d26d021d6 100644 --- a/doc/source/getting_started/index.rst +++ b/doc/source/getting_started/index.rst @@ -36,7 +36,7 @@ Installation .. code-block:: bash - conda install pandas + pip install pandas --- :column: col-12 p-3