docs(python): fix bad bullet points

py-polars/Makefile

@@ -62,6 +62,7 @@ fmt: .venv  ## Run autoformatting and linting
 	$(VENV_BIN)/blackdoc .
 	$(VENV_BIN)/typos ..
 	$(VENV_BIN)/python scripts/check_stacklevels.py
+	$(VENV_BIN)/python scripts/find_bad_docstring_bullet_points.py
 	cargo fmt --all
 	-dprint fmt
 	-$(VENV_BIN)/mypy

py-polars/polars/functions/lazy.py

@@ -2065,6 +2065,7 @@ def from_epoch(
     Utility function that parses an epoch timestamp (or Unix time) to Polars Date(time).
 
     Depending on the `time_unit` provided, this function will return a different dtype:
+
     - time_unit="d" returns pl.Date
     - time_unit="s" returns pl.Datetime["us"] (pl.Datetime's default)
     - time_unit="ms" returns pl.Datetime["ms"]

py-polars/polars/io/delta.py

@@ -227,6 +227,7 @@ def scan_delta(
     <https://docs.rs/object_store/latest/object_store/azure/enum.AzureConfigKey.html#variants>`__.
 
     Following type of table paths are supported,
+
     * az://<container>/<path>
     * adl://<container>/<path>
     * abfs[s]://<container>/<path>

py-polars/scripts/check_stacklevels.py

@@ -16,9 +16,9 @@
 
 
 class StackLevelChecker(NodeVisitor):  # noqa: D101
-    def __init__(self, file) -> None:
+    def __init__(self, file: str) -> None:
         self.file = file
-        self.violations = set()
+        self.violations: set[str] = set()
 
     def visit_Call(self, node: ast.Call) -> None:  # noqa: D102
         for keyword in node.keywords:

py-polars/scripts/find_bad_docstring_bullet_points.py

@@ -0,0 +1,82 @@
+"""
+Find cases where docstring bullet points will not render correctly in the documentation.
+
+Do this:
+```
+Here is a list of things:
+
+- thing 1
+- thing 2
+```
+Not this:
+```
+Here is a list of things:
+- thing 1
+- thing 2
+```.
+"""
+import ast
+import subprocess
+import sys
+from pathlib import Path
+
+
+def _find_bad_docstring_bullet_points(file_path: str) -> bool:
+    content = Path(file_path).read_text(encoding="utf-8")
+    parsed_tree = ast.parse(content)
+    has_issue = False
+
+    for node in ast.walk(parsed_tree):
+        if isinstance(node, (ast.FunctionDef, ast.ClassDef)):
+            function_or_class_body = node.body
+            if (
+                len(function_or_class_body) > 0
+                and isinstance(function_or_class_body[0], ast.Expr)
+                and isinstance(function_or_class_body[0].value, ast.Constant)
+            ):
+                docstring = function_or_class_body[0].value.value
+
+                if isinstance(docstring, str):
+                    lines = docstring.split("\n")
+                    for i, line in enumerate(lines[1:], start=1):
+                        previous_line = lines[i - 1]
+                        current_line_indentation = len(line) - len(line.lstrip())
+                        previous_line_indentation = len(lines[i - 1]) - len(
+                            lines[i - 1].lstrip()
+                        )
+
+                        if (
+                            current_line_indentation == previous_line_indentation
+                            and not previous_line.lstrip().startswith("*")
+                            and not previous_line.lstrip().startswith("-")
+                            and (
+                                line.lstrip().startswith("- ")
+                                or line.lstrip().startswith("* ")
+                            )
+                        ):
+                            line_number = (
+                                lines.index(line)
+                                + function_or_class_body[0].value.lineno
+                            )
+                            print(
+                                f"{file_path}:{line_number}:9: Found docstring bullet points which will not render."
+                            )
+                            has_issue = True
+
+    return has_issue
+
+
+if __name__ == "__main__":
+    git_files = subprocess.run(
+        ["git", "ls-files"], capture_output=True, text=True
+    ).stdout.split()
+    has_issues = False
+
+    for file_path in git_files:
+        if file_path.endswith(".py"):
+            has_issues |= _find_bad_docstring_bullet_points(file_path)
+
+    if has_issues:
+        sys.exit(1)
+    else:
+        sys.exit(0)