docs(python): Improve API reference landing page (#14888)

Co-authored-by: Stijn de Gooijer <stijndegooijer@gmail.com>
pola-rs · Mar 13, 2024 · 1d7b49e · 1d7b49e
1 parent bc3acf3
commit 1d7b49e
Show file tree

Hide file tree

Showing 16 changed files with 204 additions and 100 deletions.
diff --git a/docs/development/versioning.md b/docs/development/versioning.md
@@ -31,7 +31,7 @@ We know it takes time and energy for our users to keep up with new releases but,
 
 **A breaking change occurs when an existing component of the public API is changed or removed.**
 
-A feature is part of the public API if it is documented in the [API reference](https://docs.pola.rs/py-polars/html/reference/).
+A feature is part of the public API if it is documented in the [API reference](https://docs.pola.rs/py-polars/html/reference/index.html).
 
 Examples of breaking changes:
 

diff --git a/py-polars/docs/requirements-docs.txt b/py-polars/docs/requirements-docs.txt
@@ -14,6 +14,7 @@ sphinx-autosummary-accessors==2023.4.0
 sphinx-copybutton==0.5.2
 sphinx-design==0.5.0
 sphinx-favicon==1.0.1
+sphinx_reredirects==0.1.3
 sphinx-toolbox==3.5.0
 
 livereload==2.6.3
diff --git a/py-polars/docs/source/_static/css/custom.css b/py-polars/docs/source/_static/css/custom.css
@@ -24,26 +24,36 @@ html[data-theme="dark"] {
     --pst-color-border: #444444;
 }
 
+/* add subtle gradients to sidebar and card elements */
 div.bd-sidebar-primary {
     background-image: linear-gradient(90deg, var(--pst-gradient-sidebar-left) 0%, var(--pst-gradient-sidebar-right) 100%);
 }
+div.sd-card {
+    background-image: linear-gradient(0deg, var(--pst-gradient-sidebar-left) 0%, var(--pst-gradient-sidebar-right) 100%);
+}
 
+/* match docs footer colour to the header */
 footer.bd-footer {
     background-color: var(--pst-color-on-background);
 }
 
 /*
- We're not currently doing anything meaningful with the right
- ToC, so hide until there's actually something to put there...
+ we're not currently doing anything meaningful with the
+ right toc, so hide until there's something to put there
  */
 div.bd-sidebar-secondary {
     display: none;
 }
-
 label.sidebar-toggle.secondary-toggle {
     display: none !important;
 }
 
+/* fix visited link colour */
 a:visited {
     color: var(--pst-color-link);
 }
+
+/* fix ugly navbar scrollbar display */
+.sidebar-primary-items__end {
+    margin: 0 !important;
+}
diff --git a/py-polars/docs/source/conf.py b/py-polars/docs/source/conf.py
@@ -21,12 +21,14 @@
 # Add py-polars directory
 sys.path.insert(0, str(Path("../..").resolve()))
 
+
 # -- Project information -----------------------------------------------------
 
 project = "Polars"
 author = "Ritchie Vink"
 copyright = f"2020, {author}"
 
+
 # -- General configuration ---------------------------------------------------
 
 extensions = [
@@ -44,6 +46,7 @@
     "sphinx_copybutton",
     "sphinx_design",
     "sphinx_favicon",
+    "sphinx_reredirects",
     "sphinx_toolbox.more_autodoc.overloads",
 ]
 
@@ -67,6 +70,7 @@
 # https://sphinx-toolbox.readthedocs.io/en/latest/
 overloads_location = ["bottom"]
 
+
 # -- Extension settings  -----------------------------------------------------
 
 # sphinx.ext.intersphinx - link to other projects' documentation
@@ -89,6 +93,10 @@
 copybutton_prompt_text = r">>> |\.\.\. "
 copybutton_prompt_is_regexp = True
 
+# redirect empty root to the actual landing page
+redirects = {"index": "reference/index.html"}
+
+
 # -- Options for HTML output -------------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.

diff --git a/py-polars/docs/source/reference/api.rst b/py-polars/docs/source/reference/api.rst
@@ -7,7 +7,7 @@ Providing new functionality
 ---------------------------
 
 These functions allow you to register custom functionality in a dedicated
-namespace on the underlying polars classes without requiring subclassing
+namespace on the underlying Polars classes without requiring subclassing
 or mixins. Expr, DataFrame, LazyFrame, and Series are all supported targets.
 
 This feature is primarily intended for use by library authors providing
@@ -29,7 +29,7 @@ Available registrations
 
 .. note::
 
-   You cannot override existing polars namespaces (such as ``.str`` or ``.dt``), and attempting to do so
+   You cannot override existing Polars namespaces (such as ``.str`` or ``.dt``), and attempting to do so
    will raise an `AttributeError <https://docs.python.org/3/library/exceptions.html#AttributeError>`_.
    However, you *can* override other custom namespaces (which will only generate a
    `UserWarning <https://docs.python.org/3/library/exceptions.html#UserWarning>`_).

diff --git a/py-polars/docs/source/reference/config.rst b/py-polars/docs/source/reference/config.rst
@@ -34,8 +34,8 @@ Config options
     Config.set_trim_decimal_zeros
     Config.set_verbose
 
-Config load, save, and current state
-------------------------------------
+Config load, save, state
+------------------------
 .. autosummary::
    :toctree: api/
 
@@ -81,8 +81,8 @@ explicitly calling one or more of the available "set\_" methods on it...
     with pl.Config(verbose=True):
         do_various_things()
 
-Use as a function decorator
----------------------------
+Use as a decorator
+------------------
 
 In the same vein, you can also use ``Config`` as a function decorator to
 temporarily set options for the duration of the function call:

diff --git a/py-polars/docs/source/reference/datatypes.rst b/py-polars/docs/source/reference/datatypes.rst
@@ -53,8 +53,8 @@ Other
     :toctree: api/
     :nosignatures:
 
-    Boolean
     Binary
+    Boolean
     Categorical
     Enum
     Null

diff --git a/py-polars/docs/source/reference/expressions/functions.rst b/py-polars/docs/source/reference/expressions/functions.rst
@@ -2,7 +2,7 @@
 Functions
 =========
 
-These functions are available from the polars module root and can be used as expressions, and sometimes also in eager contexts.
+These functions are available from the Polars module root and can be used as expressions, and sometimes also in eager contexts.
 
 ----
 

diff --git a/py-polars/docs/source/reference/expressions/index.rst b/py-polars/docs/source/reference/expressions/index.rst
@@ -2,7 +2,7 @@
 Expressions
 ===========
 
-This page gives an overview of all public polars expressions.
+This page gives an overview of all public Polars expressions.
 
 .. toctree::
    :maxdepth: 2

diff --git a/py-polars/docs/source/reference/index.rst b/py-polars/docs/source/reference/index.rst
@@ -1,24 +1,108 @@
-=============
-API reference
-=============
-
-This page gives an overview of all public polars objects, functions and
-methods. All classes and functions exposed in ``polars.*`` namespace are public.
-
-.. toctree::
-   :maxdepth: 2
-
-   io
-   series/index
-   dataframe/index
-   lazyframe/index
-   expressions/index
-   selectors
-   api
-   functions
-   datatypes
-   config
-   exceptions
-   testing
-   sql
-   metadata
+====================
+Python API reference
+====================
+
+This page gives a high-level overview of all public Polars objects, functions and
+methods. All classes and functions exposed in the ``polars.*`` namespace are public.
+
+
+.. grid::
+
+    .. grid-item-card::
+
+        .. toctree::
+           :maxdepth: 2
+
+           dataframe/index
+
+    .. grid-item-card::
+
+        .. toctree::
+           :maxdepth: 2
+
+           lazyframe/index
+
+    .. grid-item-card::
+
+        .. toctree::
+           :maxdepth: 2
+
+           series/index
+
+
+.. grid::
+
+    .. grid-item-card::
+
+        .. toctree::
+           :maxdepth: 2
+
+           expressions/index
+           selectors
+
+    .. grid-item-card::
+
+        .. toctree::
+           :maxdepth: 2
+
+           functions
+
+    .. grid-item-card::
+
+        .. toctree::
+           :maxdepth: 2
+
+           datatypes
+
+
+.. grid::
+
+    .. grid-item-card::
+
+        .. toctree::
+           :maxdepth: 2
+
+           io
+
+    .. grid-item-card::
+
+        .. toctree::
+           :maxdepth: 2
+
+           config
+
+    .. grid-item-card::
+
+        .. toctree::
+           :maxdepth: 2
+
+           api
+
+
+.. grid::
+
+    .. grid-item-card::
+
+        .. toctree::
+           :maxdepth: 2
+
+           sql
+
+    .. grid-item-card::
+
+        .. toctree::
+           :maxdepth: 1
+
+           exceptions
+
+        .. toctree::
+           :maxdepth: 2
+
+           testing
+
+    .. grid-item-card::
+
+        .. toctree::
+           :maxdepth: 1
+
+           metadata