diff --git a/docs/conf.py b/docs/conf.py index 8afba7fed2601..81e06c80aa771 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -128,7 +128,6 @@ # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. extensions = [ - 'provider_init_hack', 'sphinx.ext.autodoc', 'sphinx.ext.viewcode', 'sphinxarg.ext', @@ -678,6 +677,9 @@ def _get_params(root_schema: dict, prefix: str = "", default_section: str = "") # Useful for debugging. autoapi_keep_files = True +# Providers are namespace packages so we need to set this for them to be found. +autoapi_python_use_implicit_namespaces = True + # Relative path to output the AutoAPI files into. This can also be used to place the generated documentation # anywhere in your documentation hierarchy. autoapi_root = '_api' diff --git a/docs/exts/docs_build/docs_builder.py b/docs/exts/docs_build/docs_builder.py index 7164ac641a16a..bb160422f87a4 100644 --- a/docs/exts/docs_build/docs_builder.py +++ b/docs/exts/docs_build/docs_builder.py @@ -138,7 +138,7 @@ def check_spelling(self, verbose: bool) -> List[SpellingError]: os.makedirs(self.log_spelling_output_dir, exist_ok=True) build_cmd = [ - os.path.join(ROOT_PROJECT_DIR, "docs", "exts", "docs_build", "run_patched_sphinx.py"), + "sphinx-build", "-W", # turn warnings into errors "--color", # do emit colored output "-T", # show full traceback on exception @@ -213,7 +213,7 @@ def build_sphinx_docs(self, verbose: bool) -> List[DocBuildError]: os.makedirs(self._build_dir, exist_ok=True) build_cmd = [ - os.path.join(ROOT_PROJECT_DIR, "docs", "exts", "docs_build", "run_patched_sphinx.py"), + "sphinx-build", "-T", # show full traceback on exception "--color", # do emit colored output "-b", # builder to use diff --git a/docs/exts/docs_build/run_patched_sphinx.py b/docs/exts/docs_build/run_patched_sphinx.py deleted file mode 100755 index d93a84fccf517..0000000000000 --- a/docs/exts/docs_build/run_patched_sphinx.py +++ /dev/null @@ -1,104 +0,0 @@ -#!/usr/bin/env python -# Licensed to the Apache Software Foundation (ASF) under one -# or more contributor license agreements. See the NOTICE file -# distributed with this work for additional information -# regarding copyright ownership. The ASF licenses this file -# to you under the Apache License, Version 2.0 (the -# "License"); you may not use this file except in compliance -# with the License. You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, -# software distributed under the License is distributed on an -# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY -# KIND, either express or implied. See the License for the -# specific language governing permissions and limitations -# under the License. - -import os -import sys - -import autoapi -from autoapi.extension import ( - LOGGER, - ExtensionError, - bold, - darkgreen, - default_backend_mapping, - default_file_mapping, - default_ignore_patterns, -) -from sphinx.cmd.build import main - - -def run_autoapi(app): - """Load AutoAPI data from the filesystem.""" - if not app.config.autoapi_dirs: - raise ExtensionError("You must configure an autoapi_dirs setting") - - # Make sure the paths are full - normalized_dirs = [] - autoapi_dirs = app.config.autoapi_dirs - if isinstance(autoapi_dirs, str): - autoapi_dirs = [autoapi_dirs] - for path in autoapi_dirs: - if os.path.isabs(path): - normalized_dirs.append(path) - else: - normalized_dirs.append(os.path.normpath(os.path.join(app.confdir, path))) - - for _dir in normalized_dirs: - if not os.path.exists(_dir): - raise ExtensionError( - f"AutoAPI Directory `{_dir}` not found. Please check your `autoapi_dirs` setting." - ) - - # Change from app.confdir to app.srcdir. - # Before: - # - normalized_root = os.path.normpath( - # - os.path.join(app.confdir, app.config.autoapi_root) - # -) - normalized_root = os.path.normpath(os.path.join(app.srcdir, app.config.autoapi_root)) - url_root = os.path.join("/", app.config.autoapi_root) - sphinx_mapper = default_backend_mapping[app.config.autoapi_type] - sphinx_mapper_obj = sphinx_mapper(app, template_dir=app.config.autoapi_template_dir, url_root=url_root) - app.env.autoapi_mapper = sphinx_mapper_obj - - if app.config.autoapi_file_patterns: - file_patterns = app.config.autoapi_file_patterns - else: - file_patterns = default_file_mapping.get(app.config.autoapi_type, []) - - if app.config.autoapi_ignore: - ignore_patterns = app.config.autoapi_ignore - else: - ignore_patterns = default_ignore_patterns.get(app.config.autoapi_type, []) - - if ".rst" in app.config.source_suffix: - out_suffix = ".rst" - elif ".txt" in app.config.source_suffix: - out_suffix = ".txt" - else: - # Fallback to first suffix listed - out_suffix = app.config.source_suffix[0] - - # Actual meat of the run. - LOGGER.info(bold("[AutoAPI] ") + darkgreen("Loading Data")) - sphinx_mapper_obj.load(patterns=file_patterns, dirs=normalized_dirs, ignore=ignore_patterns) - - LOGGER.info(bold("[AutoAPI] ") + darkgreen("Mapping Data")) - sphinx_mapper_obj.map(options=app.config.autoapi_options) - - if app.config.autoapi_generate_api_docs: - LOGGER.info(bold("[AutoAPI] ") + darkgreen("Rendering Data")) - sphinx_mapper_obj.output_rst(root=normalized_root, source_suffix=out_suffix) - - -# HACK: sphinx-auto map did not correctly use the confdir attribute instead of srcdir when specifying the -# directory to contain the generated files. -# Unfortunately we have a problem updating to a newer version of this library and we have to use -# sphinx-autoapi v1.0.0, so I am monkeypatching this library to fix this one problem. -autoapi.extension.run_autoapi = run_autoapi - -sys.exit(main(sys.argv[1:])) diff --git a/docs/exts/provider_init_hack.py b/docs/exts/provider_init_hack.py deleted file mode 100644 index 40f7fefa5b18f..0000000000000 --- a/docs/exts/provider_init_hack.py +++ /dev/null @@ -1,52 +0,0 @@ -# Licensed to the Apache Software Foundation (ASF) under one -# or more contributor license agreements. See the NOTICE file -# distributed with this work for additional information -# regarding copyright ownership. The ASF licenses this file -# to you under the Apache License, Version 2.0 (the -# "License"); you may not use this file except in compliance -# with the License. You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, -# software distributed under the License is distributed on an -# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY -# KIND, either express or implied. See the License for the -# specific language governing permissions and limitations -# under the License. - -""" -Bugs in sphinx-autoapi using metaclasses prevent us from upgrading to 1.3 -which has implicit namespace support. Until that time, we make it look -like a real package for building docs -""" -import os - -from sphinx.application import Sphinx - -ROOT_PROJECT_DIR = os.path.abspath( - os.path.join(os.path.dirname(os.path.realpath(__file__)), os.pardir, os.pardir) -) - -PROVIDER_INIT_FILE = os.path.join(ROOT_PROJECT_DIR, "airflow", "providers", "__init__.py") - - -def _create_init_py(app, config): - del app - del config - # This file is deleted by /docs/build_docs.py. If you are not using the script, the file will be - # deleted by pre-commit. - with open(PROVIDER_INIT_FILE, "wt"): - pass - - -def setup(app: Sphinx): - """ - Sets the plugin up and returns configuration of the plugin. - - :param app: application. - :return json description of the configuration that is needed by the plugin. - """ - app.connect("config-inited", _create_init_py) - - return {"version": "builtin", "parallel_read_safe": True, "parallel_write_safe": True} diff --git a/setup.py b/setup.py index 29690dc52f3ce..c1e970bce0a8b 100644 --- a/setup.py +++ b/setup.py @@ -257,7 +257,7 @@ def write_version(filename: str = os.path.join(*[my_dir, "airflow", "git_version 'sphinx>=2.1.2, <3.5.0', 'sphinx-airflow-theme', 'sphinx-argparse>=0.1.13', - 'sphinx-autoapi==1.0.0', + 'sphinx-autoapi~=1.5', 'sphinx-copybutton', 'sphinx-jinja~=1.1', 'sphinx-rtd-theme>=0.1.6',