Skip to content

Commit bd0e820

Browse files
authored
Doc/cross reference (#791)
* Update docstrings so that cross references work in online docs. Also switch from autosummary to autoapi in sphinx for building API reference documents * Update documentation to cross reference * Correct class names and internal attr * Revert changes that will end up coming in via PR #782 * Add autoapi to requirements file * Add git ignore for files retrieved during local site building * Remove unused portions of doc config * Reset substrait capitalization that was reverted during rebase * Small example changes
1 parent 1d61548 commit bd0e820

34 files changed

+370
-517
lines changed

docs/.gitignore

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
pokemon.csv
2+
yellow_trip_data.parquet

docs/requirements.txt

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -22,4 +22,5 @@ maturin
2222
jinja2
2323
ipython
2424
pandas
25-
pickleshare
25+
pickleshare
26+
sphinx-autoapi

docs/source/api.rst

Lines changed: 0 additions & 31 deletions
This file was deleted.

docs/source/api/dataframe.rst

Lines changed: 0 additions & 27 deletions
This file was deleted.

docs/source/api/execution_context.rst

Lines changed: 0 additions & 29 deletions
This file was deleted.

docs/source/api/expression.rst

Lines changed: 0 additions & 27 deletions
This file was deleted.

docs/source/api/functions.rst

Lines changed: 0 additions & 27 deletions
This file was deleted.

docs/source/api/object_store.rst

Lines changed: 0 additions & 27 deletions
This file was deleted.

docs/source/conf.py

Lines changed: 26 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -46,15 +46,11 @@
4646
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
4747
# ones.
4848
extensions = [
49-
"sphinx.ext.autodoc",
50-
"sphinx.ext.autosummary",
51-
"sphinx.ext.doctest",
52-
"sphinx.ext.ifconfig",
5349
"sphinx.ext.mathjax",
54-
"sphinx.ext.viewcode",
5550
"sphinx.ext.napoleon",
5651
"myst_parser",
5752
"IPython.sphinxext.ipython_directive",
53+
"autoapi.extension",
5854
]
5955

6056
source_suffix = {
@@ -70,33 +66,35 @@
7066
# This pattern also affects html_static_path and html_extra_path.
7167
exclude_patterns = []
7268

73-
# Show members for classes in .. autosummary
74-
autodoc_default_options = {
75-
"members": None,
76-
"undoc-members": None,
77-
"show-inheritance": None,
78-
"inherited-members": None,
79-
}
80-
81-
autosummary_generate = True
82-
69+
autoapi_dirs = ["../../python"]
70+
autoapi_ignore = ["*tests*"]
71+
autoapi_member_order = "groupwise"
72+
suppress_warnings = ["autoapi.python_import_resolution"]
73+
autoapi_python_class_content = "both"
8374

84-
def autodoc_skip_member(app, what, name, obj, skip, options):
85-
exclude_functions = "__init__"
86-
exclude_classes = ("Expr", "DataFrame")
8775

88-
class_name = ""
89-
if hasattr(obj, "__qualname__"):
90-
if obj.__qualname__ is not None:
91-
class_name = obj.__qualname__.split(".")[0]
76+
def autoapi_skip_member_fn(app, what, name, obj, skip, options):
77+
skip_contents = [
78+
# Re-exports
79+
("class", "datafusion.DataFrame"),
80+
("class", "datafusion.SessionContext"),
81+
("module", "datafusion.common"),
82+
# Deprecated
83+
("class", "datafusion.substrait.serde"),
84+
("class", "datafusion.substrait.plan"),
85+
("class", "datafusion.substrait.producer"),
86+
("class", "datafusion.substrait.consumer"),
87+
("method", "datafusion.context.SessionContext.tables"),
88+
("method", "datafusion.dataframe.DataFrame.unnest_column"),
89+
]
90+
if (what, name) in skip_contents:
91+
skip = True
9292

93-
should_exclude = name in exclude_functions and class_name in exclude_classes
93+
return skip
9494

95-
return True if should_exclude else None
9695

97-
98-
def setup(app):
99-
app.connect("autodoc-skip-member", autodoc_skip_member)
96+
def setup(sphinx):
97+
sphinx.connect("autoapi-skip-member", autoapi_skip_member_fn)
10098

10199

102100
# -- Options for HTML output -------------------------------------------------
@@ -106,9 +104,7 @@ def setup(app):
106104
#
107105
html_theme = "pydata_sphinx_theme"
108106

109-
html_theme_options = {
110-
"use_edit_page_button": True,
111-
}
107+
html_theme_options = {"use_edit_page_button": False, "show_toc_level": 2}
112108

113109
html_context = {
114110
"github_user": "apache",

docs/source/index.rst

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -104,5 +104,3 @@ Example
104104
:hidden:
105105
:maxdepth: 1
106106
:caption: API
107-
108-
api

0 commit comments

Comments
 (0)