From 1695e8c54ff4171734abd090682aae8cd07d1f59 Mon Sep 17 00:00:00 2001 From: Jonathan Shi Date: Fri, 14 Jun 2024 17:18:12 -0700 Subject: [PATCH] add big comment --- docs/source/conf.py | 27 ++++++++++++++++++++++++++- 1 file changed, 26 insertions(+), 1 deletion(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index b0e6b46baf1..c9ff1656f7b 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -90,9 +90,34 @@ # Disable footer message "Built with Sphinx using a theme provided by Read the Docs." html_show_sphinx = False -# Add custom Documenter classes to pre-process accessor classes like pd.Series.str, pd.Series.dt +# Custom Documenter and AutoSummary classes to render friendly names for accessor attributes/methods +# like pd.Series.str.replace and pd.Series.dt.date, rather than pd.series_utils.StringMethods.replace +# and pd.series_utils.DatetimeProperties.date. # See implementation from pandas: # https://github.com/pandas-dev/pandas/blob/bbe0e531383358b44e94131482e122bda43b33d7/doc/source/conf.py#L484-L485 +# The rough control flow of autosummary/autodoc, and the manner in which our custom classes interact +# it, is as follows: +# (0.) The autosummary-generate directive creates rst files for each method detected within an "autosummary" +# block. I'm not completely sure how this resolution is performed, but it will only pick up elements +# defined in an explicit "autosummary" block, and does not find those declared within custom directives +# that inherit the Autosummary class. See comments on `ModinAutosummary` below. +# 1. `Autosummary` reads the :toctree: elements specified in modin/series.rst. +# These elements are listed by the names we want displayed ("Series.str.replace", "Series.dt.date", etc.), +# as autosummary does not provide simple mechanisms for replacing a path with a different label. +# 2. Our custom autosummary class (`ModinAutosummary`) replaces vanity names (e.g. "Series.str.replace") +# with the canonical import path ("series_utils.StringMethods.replace") before passing it to the base +# `Autosummary` class, which imports the appropriate module and class to parse type signatures and +# docstrings. After the base `Autosummary` import is done, `ModinAutosummary` restores the vanity names +# so they are properly rendered within the output of Series.html. +# 3. Individual method/attribute stubs are generated from our custom files in _templates/autosummary/. +# The subclasses of `ModinAccessorLevelDocumenter` define the custom "automodinaccessormethod" and +# "automodinaccessorattribute" directives, which are necessary to perform formatting and avoid certain +# autodoc warnings. This is similar to the approach taken by native pandas. See comments on these +# classes for more details. +# (4.) Sphinx or autodoc or some other thing out of our control resolves path names and turns them into +# links. In order for these links to properly generate, the `real_name` parsed in our custom +# `ModinAutosummary` class must match the `format_name` value generated from autodoc in our +# custom `ModinAccessorLevelDocumenter` class and its children. import sphinx # isort:skip from sphinx.ext.autodoc import ( # isort:skip AttributeDocumenter,