docs(python): Improved structure for DataFrame and LazyFrame API …

…docs, misc design improvements (#5433)
pola-rs · Nov 7, 2022 · 3450bc2 · 3450bc2
1 parent 6e0bf88
commit 3450bc2
Show file tree

Hide file tree

Showing 36 changed files with 495 additions and 356 deletions.
diff --git a/py-polars/docs/img/polars_logo.png b/py-polars/docs/img/polars_logo.png
diff --git a/py-polars/docs/requirements-docs.txt b/py-polars/docs/requirements-docs.txt
@@ -2,19 +2,20 @@ numpy
 pandas
 pyarrow
 
-hypothesis==6.56.3
+hypothesis==6.56.4
 
+autodocsumm==0.2.9
+commonmark==0.9.1
 ghp-import==2.1.0
-sphinx==5.3.0
+numpydoc==1.5.0
+pydata-sphinx-theme==0.11.0
 sphinx-autosummary-accessors==2022.4.0
 sphinx-copybutton==0.5.0
-pydata-sphinx-theme==0.11.0
+sphinx==5.3.0
 sphinxcontrib-applehelp==1.0.2
 sphinxcontrib-devhelp==1.0.2
 sphinxcontrib-htmlhelp==2.0.0
 sphinxcontrib-jsmath==1.0.1
+sphinxcontrib-napoleon==0.7
 sphinxcontrib-qthelp==1.0.3
 sphinxcontrib-serializinghtml==1.1.5
-sphinxcontrib-napoleon==0.7
-commonmark==0.9.1
-numpydoc==1.5.0
diff --git a/py-polars/docs/source/_static/css/custom.css b/py-polars/docs/source/_static/css/custom.css
@@ -21,3 +21,36 @@ dl.class > dt:first-of-type {
 .bd-toc-item {
     overflow-wrap: break-word;
 }
+
+/* Dark & light theme tweaks */
+html[data-theme="light"] {
+    --pst-color-on-background: #ecf4ff;
+    --pst-gradient-sidebar-left: #ffffff;
+    --pst-gradient-sidebar-right: #fbfbfb;
+    --pst-color-border: #cccccc;
+}
+
+html[data-theme="dark"] {
+    --pst-color-on-background: #333333;
+    --pst-gradient-sidebar-left: #121212;
+    --pst-gradient-sidebar-right: #181818;
+    --pst-color-sidebar-nav: #181818;
+    --pst-color-border: #444444;
+}
+
+div.bd-sidebar-primary {
+    background-image: linear-gradient(90deg, var(--pst-gradient-sidebar-left) 0%, var(--pst-gradient-sidebar-right) 100%);
+}
+
+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...
+ */
+div.bd-sidebar-secondary {
+    position: absolute;
+    display: none;
+}
diff --git a/py-polars/docs/source/conf.py b/py-polars/docs/source/conf.py
@@ -35,7 +35,9 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
-    "numpydoc",  # numpy docstrings
+    # ----------------------
+    # sphinx extensions
+    # ----------------------
     "sphinx.ext.autodoc",
     "sphinx.ext.autosummary",
     "sphinx.ext.coverage",
@@ -46,6 +48,11 @@
     "sphinx.ext.linkcode",
     "sphinx.ext.mathjax",
     "sphinx.ext.todo",
+    # ----------------------
+    # third-party extensions
+    # ----------------------
+    "autodocsumm",
+    "numpydoc",
     "sphinx_autosummary_accessors",
     "sphinx_copybutton",
 ]
@@ -72,14 +79,14 @@
 html_static_path = ["_static"]
 html_css_files = ["css/custom.css"]  # relative to html_static_path
 html_show_sourcelink = False
-html_logo = "../img/polars_logo.png"
 
 # adds useful copy functionality to all the examples; also
 # strips the '>>>' and '...' prompt/continuation prefixes.
 copybutton_prompt_text = r">>> |\.\.\. "
 copybutton_prompt_is_regexp = True
 
 autosummary_generate = True
+numpydoc_show_class_members = False
 
 html_theme_options = {
     "external_links": [
@@ -118,6 +125,10 @@
             "href": "https://raw.githubusercontent.com/pola-rs/polars-static/master/icons/touchicon-180x180.png",  # noqa: E501
         },
     ],
+    "logo": {
+        "image_light": "https://raw.githubusercontent.com/pola-rs/polars-static/master/logos/polars-logo-dark-medium.png",  # noqa: E501
+        "image_dark": "https://raw.githubusercontent.com/pola-rs/polars-static/master/logos/polars-logo-dimmed-medium.png",  # noqa: E501
+    },
 }
 
 intersphinx_mapping = {
@@ -195,10 +206,25 @@ def _minify_classpaths(s: str) -> str:
     # * "pli.Expr" -> "Expr"
     # * "polars.internals.expr.expr.Expr" -> "Expr"
     # * "polars.internals.lazyframe.frame.LazyFrame" -> "LazyFrame"
+    # also:
+    # * "datetime.date" => "date"
+    s = s.replace("datetime.", "")
     return re.sub(
-        pattern=r"~?(pli|polars\.(?:internals|datatypes)[\w.]+?)\.([A-Z][\w.]+)",
+        pattern=r"""
+        ~?
+        (
+          (?:pli|
+            (?:polars\.
+              (?:internals|datatypes)
+            )
+          )
+          (?:\.[a-z.]+)?\.
+          ([A-Z][\w.]+)
+        )
+        """,
         repl=r"\2",
         string=s,
+        flags=re.VERBOSE,
     )
 
 

diff --git a/py-polars/docs/source/reference/dataframe.rst b/py-polars/docs/source/reference/dataframe.rst
diff --git a/py-polars/docs/source/reference/dataframe/aggregation.rst b/py-polars/docs/source/reference/dataframe/aggregation.rst
@@ -0,0 +1,17 @@
+===========
+Aggregation
+===========
+
+.. currentmodule:: polars
+.. autosummary::
+   :toctree: api/
+
+    DataFrame.max
+    DataFrame.mean
+    DataFrame.median
+    DataFrame.min
+    DataFrame.product
+    DataFrame.quantile
+    DataFrame.std
+    DataFrame.sum
+    DataFrame.var
diff --git a/py-polars/docs/source/reference/dataframe/attributes.rst b/py-polars/docs/source/reference/dataframe/attributes.rst
@@ -0,0 +1,14 @@
+==========
+Attributes
+==========
+
+.. currentmodule:: polars
+.. autosummary::
+   :toctree: api/
+
+    DataFrame.columns
+    DataFrame.dtypes
+    DataFrame.height
+    DataFrame.schema
+    DataFrame.shape
+    DataFrame.width
diff --git a/py-polars/docs/source/reference/dataframe/computation.rst b/py-polars/docs/source/reference/dataframe/computation.rst
@@ -0,0 +1,10 @@
+===========
+Computation
+===========
+
+.. currentmodule:: polars
+.. autosummary::
+   :toctree: api/
+
+    DataFrame.fold
+    DataFrame.hash_rows
diff --git a/py-polars/docs/source/reference/dataframe/descriptive.rst b/py-polars/docs/source/reference/dataframe/descriptive.rst
@@ -0,0 +1,16 @@
+===========
+Descriptive
+===========
+
+.. currentmodule:: polars
+.. autosummary::
+   :toctree: api/
+
+    DataFrame.describe
+    DataFrame.estimated_size
+    DataFrame.is_duplicated
+    DataFrame.is_empty
+    DataFrame.is_unique
+    DataFrame.n_chunks
+    DataFrame.n_unique
+    DataFrame.null_count