chore: Add script to automatically sort members in docs/api-reference (#3200)

Author: FBruzzesi

.pre-commit-config.yaml

@@ -47,6 +47,11 @@ repos:
       entry: python -m utils.check_api_reference
       language: python
       additional_dependencies: [polars]
+    - id: sort-api-reference
+      name: sort-api-reference
+      pass_filenames: false
+      entry: python -m utils.sort_api_reference
+      language: python
     - id: imports-are-banned
       name: import are banned (use `get_pandas` instead of `import pandas`)
       entry: python utils/import_check.py

docs/api-reference/dataframe.md

@@ -44,13 +44,13 @@
         - shape
         - sort
         - tail
-        - top_k
         - to_arrow
         - to_dict
         - to_native
         - to_numpy
         - to_pandas
         - to_polars
+        - top_k
         - unique
         - unpivot
         - with_columns

docs/api-reference/expr_dt.md

@@ -18,12 +18,12 @@
         - replace_time_zone
         - second
         - timestamp
+        - to_string
         - total_microseconds
         - total_milliseconds
         - total_minutes
         - total_nanoseconds
         - total_seconds
-        - to_string
         - truncate
         - weekday
         - year

docs/api-reference/lazyframe.md

@@ -25,8 +25,8 @@
         - sink_parquet
         - sort
         - tail
-        - top_k
         - to_native
+        - top_k
         - unique
         - unpivot
         - with_columns

docs/api-reference/narwhals.md

@@ -44,9 +44,9 @@ Here are the top-level functions available in Narwhals.
         - read_parquet
         - scan_csv
         - scan_parquet
+        - show_versions
         - sum
         - sum_horizontal
-        - show_versions
         - to_native
         - to_py_scalar
         - when

docs/api-reference/schema.md

@@ -4,13 +4,13 @@
     handler: python
     options:
       members:
-        - names
         - dtypes
         - from_arrow
         - from_native
         - from_pandas_like
         - from_polars
         - len
+        - names
         - to_arrow
         - to_pandas
         - to_polars

docs/api-reference/series.md

@@ -59,8 +59,8 @@
         - median
         - min
         - mode
-        - name
         - n_unique
+        - name
         - null_count
         - pipe
         - quantile
@@ -76,8 +76,8 @@
         - scatter
         - shape
         - shift
-        - sort
         - skew
+        - sort
         - sqrt
         - std
         - sum
@@ -86,10 +86,10 @@
         - to_dummies
         - to_frame
         - to_list
+        - to_native
         - to_numpy
         - to_pandas
         - to_polars
-        - to_native
         - unique
         - value_counts
         - var

docs/api-reference/series_dt.md

@@ -18,12 +18,12 @@
         - replace_time_zone
         - second
         - timestamp
+        - to_string
         - total_microseconds
         - total_milliseconds
         - total_minutes
         - total_nanoseconds
         - total_seconds
-        - to_string
         - truncate
         - weekday
         - year

docs/api-reference/utils.md

@@ -4,8 +4,8 @@
     handler: python
     options:
       members:
-        - parse_version
         - Implementation
+        - parse_version
       show_root_heading: false
       show_source: false
       show_bases: false

utils/sort_api_reference.py

@@ -0,0 +1,54 @@
+"""Script to automatically sort members lists in API reference markdown files."""
+# ruff: noqa: T201
+
+from __future__ import annotations
+
+import re
+import sys
+from pathlib import Path
+
+
+def sort_members_in_markdown(file_path: Path) -> int:
+    """Sort members lists in a markdown file alphabetically.
+
+    Returns:
+        1 if the file was modified, 0 if no changes were needed.
+    """
+    content = file_path.read_text(encoding="utf-8")
+
+    # Pattern matches "members:" followed by list items (lines starting with "- ")
+    pattern = r"(members:)((?:\n\s+-[^\n]+)+)"
+
+    def sort_list(match: re.Match[str]) -> str:
+        """Sort a matched members list section."""
+        prefix = match.group(1)  # "members:"
+        items = match.group(2)  # All list items with newlines and indentation
+
+        item_pattern = r"(\n\s+-)([^\n]+)"  # Extract individual items: (\n + spaces + -) and (content)
+        matches = re.findall(item_pattern, items)
+
+        # Sort alphabetically by the item content (excluding indentation and dash)
+        sorted_items = sorted(matches, key=lambda x: x[1].strip())
+
+        # Reconstruct: "members:" + sorted items with their indentation preserved
+        return prefix + "".join(f"{indent}{content}" for indent, content in sorted_items)
+
+    sorted_content = re.sub(pattern, sort_list, content)
+    if sorted_content == content:
+        return 0
+
+    file_path.write_text(sorted_content, encoding="utf-8")
+    print(f"Sorting members in {file_path}")
+    return 1
+
+
+PATH = Path("docs") / "api-reference"
+FILES_TO_SKIP = {"dtypes", "typing"}
+
+ret = max(
+    sort_members_in_markdown(file_path=file_path)
+    for file_path in PATH.glob("*.md")
+    if file_path.stem not in FILES_TO_SKIP
+)
+
+sys.exit(ret)