Dev-iL commented on code in PR #63630:
URL: https://github.com/apache/airflow/pull/63630#discussion_r2936573744
##########
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:
My thought was roughly this: assuming 1) inventories can't be fetched from
the regular source; 2) there's an alternate source for them (e.g. internet
archive) but it's rate limited or there's another reason to not use it
frequently; and 3) we need to refresh the cache "right now" - allow fetching
inventories from fallback path via tag.
Maybe this is sufficiently rare that we don't even care. Feel free to
ignore...
--
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]
