docs: Improve Python API docs

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

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;
+}

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.

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>`_).

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:

py-polars/docs/source/reference/datatypes.rst

@@ -53,8 +53,8 @@ Other
     :toctree: api/
     :nosignatures:
 
-    Boolean
     Binary
+    Boolean
     Categorical
     Enum
     Null

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.
 
 ----
 

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

py-polars/docs/source/reference/index.rst

@@ -1,24 +1,108 @@
-=============
-API reference
-=============
+====================
+Python API reference
+====================
 
-This page gives an overview of all public polars objects, functions and
+This page gives a high-level 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
+
+.. 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

py-polars/docs/source/reference/sql.rst

@@ -1,6 +1,6 @@
-===
-SQL
-===
+=============
+SQL Interface
+=============
 .. currentmodule:: polars
 
 .. py:class:: SQLContext