Fix/issue 835 docstrings

tools/expand_docstrings.py

@@ -4,6 +4,7 @@
 
 import ast
 import importlib
+import inspect
 import re
 import sys
 from pathlib import Path
@@ -62,12 +63,12 @@ def _rewrite_file(path: Path, package_root: Path, snippets) -> int:
     if not literals:
         return 0
 
-    expanded = [_expand(node.value, snippets) for node in literals]
+    expanded = [_expand(inspect.cleandoc(node.value), snippets) for node in literals]
     if any(missing for _, missing in expanded):
         # Some registries live in the module containing the documented object,
         # so import only when a key cannot be resolved from the central registry.
         importlib.import_module(_module_name(package_root, path))
-        expanded = [_expand(node.value, snippets) for node in literals]
+        expanded = [_expand(inspect.cleandoc(node.value), snippets) for node in literals]
 
     lines = source.splitlines(keepends=True)
     offsets = []

ultraplot/axes/base.py

@@ -89,8 +89,7 @@
 
 # Projection docstring
 _proj_docstring = """
-projection :
-str, `cartopy.crs.Projection`, or `~mpl_toolkits.basemap.Basemap`, optional
+projection : str, `cartopy.crs.Projection`, or `~mpl_toolkits.basemap.Basemap`, optional
     The map projection specification(s). If ``'cart'`` or ``'cartesian'``
     (the default), a :class:`~ultraplot.axes.CartesianAxes` is created. If ``'polar'``,
     a :class:`~ultraplot.axes.PolarAxes` is created. Otherwise, the argument is

ultraplot/figure.py

@@ -232,7 +232,7 @@ def _any_not_none(*values):
     The number of rows and columns in the subplot grid. Ignored
     if `array` was passed. Use these arguments for simple subplot grids.
 order : {'C', 'F'}, default: 'C'
-    Whether subplots are numbered in column-major (``'C'``) or row-major (``'F'``)
+    Whether subplots are numbered in row-major (``'C'``) or column-major (``'F'``)
     order. Analogous to `numpy.array` ordering. This controls the order that
     subplots appear in the `SubplotGrid` returned by this function, and the order
     of subplot a-b-c labels (see `~ultraplot.axes.Axes.format`).

ultraplot/tests/test_docstrings.py

@@ -0,0 +1,64 @@
+#!/usr/bin/env python3
+"""Tests for shared and build-time materialized docstrings."""
+
+import inspect
+import runpy
+from pathlib import Path
+
+import ultraplot as uplt
+
+
+def _load_docstring_expander():
+    path = Path(__file__).resolve().parents[2] / "tools" / "expand_docstrings.py"
+    return runpy.run_path(str(path))
+
+
+def test_build_docstring_expansion_preserves_numpy_indentation(tmp_path):
+    """Build-time expansion should match runtime normalize-before-substitute semantics."""
+    rewrite_file = _load_docstring_expander()["_rewrite_file"]
+    package_root = tmp_path / "pkg"
+    package_root.mkdir()
+    path = package_root / "example.py"
+    path.write_text(
+        "def example():\n"
+        '    """Summary.\n'
+        "\n"
+        "    Parameters\n"
+        "    ----------\n"
+        "    %(params)s\n"
+        '    """\n'
+    )
+    snippets = {
+        "params": (
+            "first : int\n" "    First value.\n" "second : str\n" "    Second value."
+        )
+    }
+
+    assert rewrite_file(path, package_root, snippets) == 1
+
+    namespace = {}
+    exec(compile(path.read_text(), str(path), "exec"), namespace)
+    assert inspect.getdoc(namespace["example"]) == (
+        "Summary.\n"
+        "\n"
+        "Parameters\n"
+        "----------\n"
+        "first : int\n"
+        "    First value.\n"
+        "second : str\n"
+        "    Second value."
+    )
+
+
+def test_subplots_parameter_docstrings_are_numpy_style():
+    """Shared subplot parameter snippets should render as valid NumPy-style entries."""
+    doc = inspect.getdoc(uplt.subplots) or ""
+    assert (
+        "projection : str, `cartopy.crs.Projection`, "
+        "or `~mpl_toolkits.basemap.Basemap`, optional"
+    ) in doc
+    assert "\nprojection :\n" not in doc
+    assert (
+        "Whether subplots are numbered in row-major (``'C'``) "
+        "or column-major (``'F'``)"
+    ) in doc