potiuk commented on code in PR #63630:
URL: https://github.com/apache/airflow/pull/63630#discussion_r2936563422
##########
contributing-docs/11_documentation_building.rst:
##########
@@ -239,7 +239,30 @@ For example:
breeze build-docs --doc-only --clean fab
-Will build ``fab`` provider documentation and clean inventories and other
build artifacts before.
+Will build ``fab`` provider documentation and clean build artifacts before.
+
+Inventory cache handling
+........................
+
+When building documentation, Sphinx downloads intersphinx inventories from
external sources (both Airflow
+packages hosted on S3 and third-party packages like Pandas, SQLAlchemy, etc.).
These inventories enable
+cross-references between documentation sets.
+
+By default, missing third-party inventories produce warnings but do **not**
fail the build. This is
+because third-party inventory servers can be temporarily unavailable and
should not block documentation
+builds. If a cached version of the inventory exists, it will be used instead.
+
+The following flags control inventory behavior:
+
+- ``--clean-inventory-cache`` — deletes the inventory cache before fetching.
Use this when you want
+ to force a completely fresh download of all inventories.
+- ``--clean-build`` — cleans build artifacts (``_build``, ``_doctrees``,
``apis``) but does **not**
+ delete the inventory cache. This allows rebuilding docs from scratch while
preserving cached
+ inventories.
+- ``--refresh-airflow-inventories`` — forces a refresh of only Airflow package
inventories, without
+ cleaning build artifacts or external inventories.
+- ``--fail-on-missing-third-party-inventories`` — fails the build if any
third-party inventory cannot
+ be downloaded (useful for publishing workflows where complete
cross-references are important).
Review Comment:
I don't think so:
* we have canary build posting us warnings where inventories are missing (so
we will be aware of it )
* ignore missing inventories is set to false by default in publishing
workflow (i.e. the one we are using to publish docs to airflow.apache.org
* We can als override it when publishing if it holds us back and we want to
publish docs quickly anyway (`breeze workflow-run publish-docs
--ignore-missing-inventories`.
I do not think we should do anything different with tag? But maybe I am
missing something ? Not sure exactly if I understand what you propose :)
--
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]
