docs(python): improve structure of sphinx-generated API docs (#5376)

pola-rs · Oct 30, 2022 · 7def610 · 7def610
1 parent be02fc0
commit 7def610
Show file tree

Hide file tree

Showing 47 changed files with 1,009 additions and 907 deletions.
diff --git a/polars/polars-core/src/frame/groupby/mod.rs b/polars/polars-core/src/frame/groupby/mod.rs
@@ -233,7 +233,7 @@ impl DataFrame {
 /// +------------+------+------+
 /// | date       | temp | rain |
 /// | ---        | ---  | ---  |
-/// | Date     | i32  | f64  |
+/// | Date       | i32  | f64  |
 /// +============+======+======+
 /// | 2020-08-21 | 20   | 0.2  |
 /// +------------+------+------+
@@ -403,7 +403,7 @@ impl<'df> GroupBy<'df> {
     /// +------------+-----------+-----------+
     /// | date       | temp_mean | rain_mean |
     /// | ---        | ---       | ---       |
-    /// | Date     | f64       | f64       |
+    /// | Date       | f64       | f64       |
     /// +============+===========+===========+
     /// | 2020-08-23 | 9         | 0.1       |
     /// +------------+-----------+-----------+
@@ -441,7 +441,7 @@ impl<'df> GroupBy<'df> {
     /// +------------+----------+
     /// | date       | temp_sum |
     /// | ---        | ---      |
-    /// | Date     | i32      |
+    /// | Date       | i32      |
     /// +============+==========+
     /// | 2020-08-23 | 9        |
     /// +------------+----------+
@@ -479,7 +479,7 @@ impl<'df> GroupBy<'df> {
     /// +------------+----------+
     /// | date       | temp_min |
     /// | ---        | ---      |
-    /// | Date     | i32      |
+    /// | Date       | i32      |
     /// +============+==========+
     /// | 2020-08-23 | 9        |
     /// +------------+----------+
@@ -516,7 +516,7 @@ impl<'df> GroupBy<'df> {
     /// +------------+----------+
     /// | date       | temp_max |
     /// | ---        | ---      |
-    /// | Date     | i32      |
+    /// | Date       | i32      |
     /// +============+==========+
     /// | 2020-08-23 | 9        |
     /// +------------+----------+
@@ -553,7 +553,7 @@ impl<'df> GroupBy<'df> {
     /// +------------+------------+
     /// | date       | temp_first |
     /// | ---        | ---        |
-    /// | Date     | i32        |
+    /// | Date       | i32        |
     /// +============+============+
     /// | 2020-08-23 | 9          |
     /// +------------+------------+
@@ -590,7 +590,7 @@ impl<'df> GroupBy<'df> {
     /// +------------+------------+
     /// | date       | temp_last |
     /// | ---        | ---        |
-    /// | Date     | i32        |
+    /// | Date       | i32        |
     /// +============+============+
     /// | 2020-08-23 | 9          |
     /// +------------+------------+
@@ -627,7 +627,7 @@ impl<'df> GroupBy<'df> {
     /// +------------+---------------+
     /// | date       | temp_n_unique |
     /// | ---        | ---           |
-    /// | Date     | u32           |
+    /// | Date       | u32           |
     /// +============+===============+
     /// | 2020-08-23 | 1             |
     /// +------------+---------------+
@@ -746,7 +746,7 @@ impl<'df> GroupBy<'df> {
     /// +------------+------------+
     /// | date       | temp_count |
     /// | ---        | ---        |
-    /// | Date     | u32        |
+    /// | Date       | u32        |
     /// +============+============+
     /// | 2020-08-23 | 1          |
     /// +------------+------------+
@@ -783,7 +783,7 @@ impl<'df> GroupBy<'df> {
     /// +--------------+------------+
     /// | date         | groups     |
     /// | ---          | ---        |
-    /// | Date(days) | list [u32] |
+    /// | Date(days)   | list [u32] |
     /// +==============+============+
     /// | 2020-08-23   | "[3]"      |
     /// +--------------+------------+
@@ -818,7 +818,7 @@ impl<'df> GroupBy<'df> {
     /// +------------+------------------------+
     /// | date       | temp_agg_list          |
     /// | ---        | ---                    |
-    /// | Date     | list [i32]             |
+    /// | Date       | list [i32]             |
     /// +============+========================+
     /// | 2020-08-23 | "[Some(9)]"            |
     /// +------------+------------------------+

diff --git a/polars/src/docs/eager.rs b/polars/src/docs/eager.rs
@@ -475,22 +475,22 @@
 //! // melted:
 //!
 //! // +-----+-----+----------+-------+
-//! //  | A   | B   | variable | value |
-//! //  | --- | --- | ---      | ---   |
-//! //  | str | i32 | str      | i32   |
-//! //  +=====+=====+==========+=======+
-//! //  | "a" | 1   | "C"      | 10    |
-//! //  +-----+-----+----------+-------+
-//! //  | "b" | 3   | "C"      | 11    |
-//! //  +-----+-----+----------+-------+
-//! //  | "a" | 5   | "C"      | 12    |
-//! //  +-----+-----+----------+-------+
-//! //  | "a" | 1   | "D"      | 2     |
-//! //  +-----+-----+----------+-------+
-//! //  | "b" | 3   | "D"      | 4     |
-//! //  +-----+-----+----------+-------+
-//! //  | "a" | 5   | "D"      | 6     |
-//! //  +-----+-----+----------+-------+
+//! // | A   | B   | variable | value |
+//! // | --- | --- | ---      | ---   |
+//! // | str | i32 | str      | i32   |
+//! // +=====+=====+==========+=======+
+//! // | "a" | 1   | "C"      | 10    |
+//! // +-----+-----+----------+-------+
+//! // | "b" | 3   | "C"      | 11    |
+//! // +-----+-----+----------+-------+
+//! // | "a" | 5   | "C"      | 12    |
+//! // +-----+-----+----------+-------+
+//! // | "a" | 1   | "D"      | 2     |
+//! // +-----+-----+----------+-------+
+//! // | "b" | 3   | "D"      | 4     |
+//! // +-----+-----+----------+-------+
+//! // | "a" | 5   | "D"      | 6     |
+//! // +-----+-----+----------+-------+
 //!
 //! # Ok(())
 //! # }

diff --git a/py-polars/docs/requirements-docs.txt b/py-polars/docs/requirements-docs.txt
@@ -6,6 +6,7 @@ hypothesis==6.56.3
 
 ghp-import==2.1.0
 sphinx==5.3.0
+sphinx-autosummary-accessors==2022.4.0
 pydata-sphinx-theme==0.11.0
 sphinxcontrib-applehelp==1.0.2
 sphinxcontrib-devhelp==1.0.2

diff --git a/py-polars/docs/source/conf.py b/py-polars/docs/source/conf.py
@@ -16,6 +16,8 @@
 import sys
 import warnings
 
+import sphinx_autosummary_accessors
+
 # add polars directory
 sys.path.insert(0, os.path.abspath("../.."))
 
@@ -43,10 +45,11 @@
     "sphinx.ext.linkcode",
     "sphinx.ext.mathjax",
     "sphinx.ext.todo",
+    "sphinx_autosummary_accessors",
 ]
 
 # Add any paths that contain templates here, relative to this directory.
-templates_path = ["_templates"]
+templates_path = ["_templates", sphinx_autosummary_accessors.templates_path]
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.

diff --git a/py-polars/docs/source/reference/dataframe.rst b/py-polars/docs/source/reference/dataframe.rst
@@ -72,8 +72,8 @@ Computations
     DataFrame.fold
     DataFrame.hash_rows
 
-Manipulation/ selection
------------------------
+Manipulation / selection
+------------------------
 .. autosummary::
    :toctree: api/