The change is merged now and it should be - I hope -very easy to iterate on the docs - that includes some.guildelines on solving typical Sphinx riddles: https://github.com/apache/airflow/blob/main/contributing-docs/11_documentation_building.rst
It should be much easier and faster to build docs (just note the Python 3.11 requirement for local doc building - there is a weird bug in Core Python 3.12 that does not allow us to build samba/google provider docs (something to workaround later). Simply `uv pin 3.11` solves the issue (details in the docs). You can still use breeze to build, docs but you can also build the docs locally: cd FOLDER uv run --group docs build-docs Then in order to get automatically refreshing server (this is the coolest part): cd FOLDER uv run --group docs build-docs --autobuild But also you can build several packages together (including solving updated cross-package doc references) uv run --group docs build-docs PACKAGE1 PACKAGE 2 Or even build docs for all packages together (when run in the top directory): uv run --group docs build-docs The tool to build docs has now nice rich-click interface: [image: Screenshot 2025-04-06 at 02.03.46.png] J. On Thu, Apr 3, 2025 at 8:02 PM Jarek Potiuk <ja...@potiuk.com> wrote: > Hello. > > Another day, another Contributor Journey Optimization improvement. > > Just about to get an RC from Airflow, I followed up after all the > restructuring / uv work done and here is one true gem that has been made > possible by that restructuring (or repainting) work -sp improving doc build > iteration speed. > > I just completed the docs (in the background of Open Lineage Meetup in > Warsaw) - where I made it super (I think) easy to iterate on our docs. > Something that will be truly needed now - when we likely need to write a > lot of docs for all the new things we created. > > Here is hte PR https://github.com/apache/airflow/pull/48760 > > After this PR is merged, with `uv` and separate distributions and > refactoring and moving the doc code to `devel-common` it's literally as > easy as: > > cd devel-common > uv run src/sphinx_exts/docs_build/fetch_inventories.py > > This one downloads inventories that documentation links to) > > cd <YOUR-DISTRIBUTION>/docs > uv run sphinx-autobuild -T --color -b html . _build > > This will (locally - without breeze) open an auto-refreshing web server > with the documentation build (after some initial startup) . With my tests, > it takes a few seconds for a change in your sources to get automatically > (!) refreshed in your browser (both on airflow-core docs and individual > providers docs). > > There is one prerequisite (enchant library) that needs to be set-up > locally (but in the docs I explained how to do it on Mac OS especially). > The "contributing-docs" are already updated in my PR to explain what to do. > > Here are the possible distributions you can run that sphinx-autobuild > command in. > > * ``airflow-core/docs`` - documentation for Airflow Core > * ``providers/**/docs`` - documentation for Providers (90+ folders) > * ``chart/docs`` - documentation for Helm Chart > * ``task-sdk/docs`` - documentation for Task SDK (new format not yet > published) > * ``airflow-ctl/docs`` - documentation for Airflow CLI (future) > > Documentation for general overview and summaries not connected with amy > specific distribution: > > * ``docker-stack-docs`` - documentation for Docker Stack' > * ``providers-summary-docs`` - documentation for provider summary page > > There will likely be some teething issues - but If you would like to check > the PR out and let me know in #documentation slack channel if you see any > issues - we can solve them before or after. > > J. > > >
