Copilot commented on code in PR #2196:
URL: https://github.com/apache/sedona/pull/2196#discussion_r2244100529
##########
python/sedona/doc/conf.py:
##########
@@ -61,16 +70,74 @@
# Suppress warnings about multiple targets for cross-references
# This is expected due to shapely1/shapely2 compatibility layer
"ref.python",
+ # Suppress docstring formatting warnings
+ "docutils",
+ # Suppress autodoc import errors that may occur in CI
+ "autodoc.import_object",
+ "autodoc",
Review Comment:
[nitpick] Consider using more specific warning suppression instead of
broadly suppressing all 'autodoc' warnings. This could mask legitimate
documentation issues.
```suggestion
```
##########
python/sedona/doc/conf.py:
##########
@@ -61,16 +70,74 @@
# Suppress warnings about multiple targets for cross-references
# This is expected due to shapely1/shapely2 compatibility layer
"ref.python",
+ # Suppress docstring formatting warnings
+ "docutils",
+ # Suppress autodoc import errors that may occur in CI
+ "autodoc.import_object",
+ "autodoc",
]
+# Don't treat warnings as errors to avoid IndexError issues
+warning_is_error = False
+# Be less strict about references to avoid import errors
+nitpicky = False
+
autodoc_default_options = {
"members": True,
"undoc-members": True,
"private-members": False,
"special-members": "__init__",
"show-inheritance": True,
+ "ignore-module-all": False,
}
+# Configure autodoc to be more forgiving with import errors
+autodoc_inherit_docstrings = True
+autodoc_preserve_defaults = True
+
+
+# Add error handling for problematic imports in CI
+def skip_member(app, what, name, obj, skip, options):
+ """Skip problematic members that cause IndexError."""
Review Comment:
The function docstring should explain the parameters, especially 'what',
'obj', and 'options' which are not immediately clear from context.
```suggestion
"""
Determine whether to skip a member during autodoc processing.
This function is connected to the "autodoc-skip-member" event in Sphinx
and is used to skip specific members that are known to cause issues
during documentation generation.
Parameters:
app (Sphinx): The Sphinx application object.
what (str): The type of the object being documented (e.g., "module",
"class", "method").
name (str): The name of the member being documented.
obj (object): The actual object being documented.
skip (bool): A boolean indicating whether autodoc would skip this
member by default.
options (object): The options given to the directive, as an instance
of `autodoc.Options`.
Returns:
bool: True if the member should be skipped, False otherwise.
"""
```
##########
python/sedona/doc/conf.py:
##########
@@ -61,16 +70,74 @@
# Suppress warnings about multiple targets for cross-references
# This is expected due to shapely1/shapely2 compatibility layer
"ref.python",
+ # Suppress docstring formatting warnings
+ "docutils",
+ # Suppress autodoc import errors that may occur in CI
+ "autodoc.import_object",
+ "autodoc",
]
+# Don't treat warnings as errors to avoid IndexError issues
+warning_is_error = False
+# Be less strict about references to avoid import errors
+nitpicky = False
+
autodoc_default_options = {
"members": True,
"undoc-members": True,
"private-members": False,
"special-members": "__init__",
"show-inheritance": True,
+ "ignore-module-all": False,
}
+# Configure autodoc to be more forgiving with import errors
+autodoc_inherit_docstrings = True
+autodoc_preserve_defaults = True
+
+
+# Add error handling for problematic imports in CI
+def skip_member(app, what, name, obj, skip, options):
+ """Skip problematic members that cause IndexError."""
+ # Skip members that are known to cause import issues
+ problematic_patterns = ["raster_serde", "sedona_raster", "shapely1",
"shapely2"]
+ if any(pattern in name for pattern in problematic_patterns):
Review Comment:
[nitpick] The problematic patterns list should be configurable or documented
with explanations for why each pattern is problematic to avoid confusion for
future maintainers.
```suggestion
# List of problematic patterns that cause import issues or errors
# - "raster_serde" and "sedona_raster": Known to cause serialization issues
in CI.
# - "shapely1" and "shapely2": Compatibility layers for different Shapely
versions.
PROBLEMATIC_PATTERNS = ["raster_serde", "sedona_raster", "shapely1",
"shapely2"]
# Add error handling for problematic imports in CI
def skip_member(app, what, name, obj, skip, options):
"""Skip problematic members that cause IndexError."""
if any(pattern in name for pattern in PROBLEMATIC_PATTERNS):
```
##########
.github/workflows/docs.yml:
##########
@@ -67,8 +67,15 @@ jobs:
working-directory: './R'
- run: Rscript -e 'pkgdown::build_site(pkg = "./R", preview = FALSE,
override = list(destination = "../docs/api/rdocs"))'
- name: Install Python documentation dependencies
- run: pip install sphinx sphinx_rtd_theme
+ run: |
+ pip install sphinx sphinx_rtd_theme pyspark==3.5.4 pystac==1.13.0
Review Comment:
Hard-coding specific versions like pyspark==3.5.4 and pystac==1.13.0 may
cause compatibility issues over time. Consider using version ranges or moving
these to a requirements file.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
