Skip to content

Use lazy import for generate_mapping_docs by moving it in setup function #2188

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
pankajastro wants to merge 2 commits into from
Closed

Use lazy import for generate_mapping_docs by moving it in setup function #2188

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
30ee581
Use lazy import for moving generate_mapping_docs by moving it in func…
pankajastro Dec 8, 2025
1ba5a30
Fix path
pankajastro Dec 8, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
30 changes: 27 additions & 3 deletions docs/conf.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,8 +4,6 @@
# Add the project root to the path so we can import the package
sys.path.insert(0, os.path.abspath("../"))

from docs.generate_mappings import generate_mapping_docs # noqa: E402

# Configuration file for the Sphinx documentation builder.
#
# For the full list of built-in configuration values, see the documentation:
Expand Down Expand Up @@ -51,4 +49,30 @@
"footer_start": ["copyright"],
}

generate_mapping_docs()

def setup(app):
"""
Sphinx setup function that runs after configuration is loaded and dependencies are installed.
This generates mapping docs by importing and calling generate_mapping_docs() lazily.
"""
try:
from docs.generate_mappings import generate_mapping_docs # noqa: E402

# Get the directory where conf.py is located (docs/ directory)
docs_dir = os.path.dirname(os.path.abspath(__file__))
templates_dir = os.path.join(docs_dir, "templates")
output_dir = os.path.join(docs_dir, "profiles")

# Generate the mapping docs - this will create the profile documentation pages
generate_mapping_docs(templates_dir=templates_dir, output_dir=output_dir)
except (ImportError, ModuleNotFoundError) as e:
# If Airflow is not available, skip generating mapping docs
# This can happen during local development if dependencies aren't installed
import warnings

warnings.warn(
f"Could not generate mapping docs: {e}. "
"Make sure Airflow is installed (pip install -r docs/requirements.txt). "
Comment on lines +69 to +75
Copy link

Copilot AI Dec 8, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The error message says "If Airflow is not available" but the actual import is from docs.generate_mappings. The import could fail for reasons other than Airflow not being available (e.g., missing jinja2). Consider making the error message more accurate:

# If dependencies are not available, skip generating mapping docs
# This can happen during local development if dependencies aren't fully installed
Suggested change
# If Airflow is not available, skip generating mapping docs
# This can happen during local development if dependencies aren't installed
import warnings
warnings.warn(
f"Could not generate mapping docs: {e}. "
"Make sure Airflow is installed (pip install -r docs/requirements.txt). "
# If required dependencies are not available, skip generating mapping docs
# This can happen during local development if all documentation dependencies aren't installed
import warnings
warnings.warn(
f"Could not generate mapping docs: {e}. "
"Make sure all documentation dependencies are installed (pip install -r docs/requirements.txt). "

Copilot uses AI. Check for mistakes.
"Documentation will be built without profile mapping pages.",
UserWarning,
)
Copy link

Copilot AI Dec 8, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The Sphinx setup function should return a metadata dictionary. This is a best practice that helps Sphinx understand the extension's requirements and capabilities. Consider adding a return statement at the end:

return {
    'version': '0.1',
    'parallel_read_safe': True,
    'parallel_write_safe': True,
}
Suggested change
)
)
return {
'version': '0.1',
'parallel_read_safe': True,
'parallel_write_safe': True,
}

Copilot uses AI. Check for mistakes.