Repository: apache/airflow
Pull request: Add exit clause suggesting --clean-build if toctree contains nonexisting _api/* reference
<!--
 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.
 -->

<!--
Thank you for contributing! Please make sure that your code changes
are covered with tests. And in case of new features or big changes
remember to adjust the documentation.

Feel free to ping committers for the review!

In case of an existing issue, reference it using one of the following:

closes: #ISSUE
related: #ISSUE

How to write a good git commit message:
http://chris.beams.io/posts/git-commit/
-->

This PR introduces an exit clause that suggests using the --clean-build option if the toctree contains a reference to a nonexisting document in the _api/* directory.
closes: #40302 

![Screenshot 2024-07-03 at 8 43 09 PM](https://github.com/apache/airflow/assets/53335539/61af8c1f-a84c-49f1-a170-bbc3fcbb6af7)

<!-- Please keep an empty line above the dashes. -->
---
**^ Add meaningful description above**
Read the **[Pull Request Guidelines](https://github.com/apache/airflow/blob/main/contributing-docs/05_pull_requests.rst#pull-request-guidelines)** for more information.
In case of fundamental code changes, an Airflow Improvement Proposal ([AIP](https://cwiki.apache.org/confluence/display/AIRFLOW/Airflow+Improvement+Proposals)) is needed.
In case of a new dependency, check compliance with the [ASF 3rd Party License Policy](https://www.apache.org/legal/resolved.html#category-x).
In case of backwards incompatible changes please leave a note in a newsfragment file, named `{pr_number}.significant.rst` or `{issue_number}.significant.rst`, in [newsfragments](https://github.com/apache/airflow/tree/main/newsfragments).


Problem statement:
Handle  toctree contains reference to nonexisting document `_api/` errors better when building docs
### Body

When building documentation (`breeze build-docs`) and you press ctrl-c in-between, the autoapi docs might remain empty and they cause

```
toctree contains reference to nonexisting document '_api/*` errors better when building docs
```

Currently the way to fix it is to add `--clean-build` option when you build docs.

We should likely improve the build process to handle it a bit better. Either 

a) detect it happens and regenerate api docs
b) suggest the user to use `--clean-build` when it happens

### Committer

- [X] I acknowledge that I am a maintainer/committer of the Apache Airflow project.

Hints from issue discussion:
@potiuk I would like to try this. Could you please assign this to me? 
Feel free to work on this

Commit message: Adding a suggestion to use --clean-build if toctree contains reference to a nonexisting doc

Patch to review:
diff --git a/docs/build_docs.py b/docs/build_docs.py
index 7520c247c6a52..47749f56607ca 100755
--- a/docs/build_docs.py
+++ b/docs/build_docs.py
@@ -450,6 +450,14 @@ def main():
         for pkg in sorted(available_packages):
             console.print(f" - {pkg}")
 
+    for package in available_packages:
+        api_dir = os.path.join(DOCS_DIR, package, "_api")
+        if os.path.exists(api_dir):
+            console.print(
+                f"[red] The toctree already contains a reference to a nonexisting document for provider [green]'{package}'[/green]. Please use the --clean-build option"
+            )
+            sys.exit(1)
+
     if package_filters:
         console.print("Current package filters: ", package_filters)
     packages_to_build = process_package_filters(available_packages, package_filters)


Code review comments:
diff_hunk: @@ -450,6 +450,14 @@ def main():
         for pkg in sorted(available_packages):
             console.print(f" - {pkg}")
 
+    for package in available_packages:
+        api_dir = os.path.join(DOCS_DIR, package, "_api")
+        if os.path.exists(api_dir):
+            console.print(
+                f"[red] The toctree already contains a reference to a nonexisting document for provider [green]'{package}'[/green]. Please use the --clean-build option"
path: docs/build_docs.py
text: @user1:
```suggestion
                f"[red]The toctree already contains a reference to a non-existing document for provider [green]'{package}'[/green]. Use the --clean-build option while building docs"
```

@author:
Made the changes to this.