Docs feature: auto-build documentation

[RNHTTR]

What do you see as an issue?

It currently takes a few minutes each time to build the docs. So, each small mistake requires a few minutes to wait for the docs to re-build.

Solving the problem

I tried using sphinx-autobuild, but I haven't been able to get it to work.

Anything else

I'd be happy to work on a PR with someone who knows restructured text/sphinx better than I do.

Are you willing to submit PR?

• Yes I am willing to submit a PR!

Code of Conduct

• I agree to follow this project's Code of Conduct

[potiuk]

I am all for you attempting to do it. It would be fantasic to get equivalent of --dev-mode for breeze start-airflow for docs ....

But I am afraid whoever wants to look at any of that is already head-start from everyone else (so in short - you are ahead of everyone else by even trying sphinx-autobuild) . There is very little understanding on details and intricasies of how docs building of our works in detail.

I continue reverse engineering it - especially on the parts which are interfacing with breeze tooling, but I merely know what commands to execute when, and other than having to dig deeply into the details of sphinx-autobuild and how it works - you are largely on your own. What we have is quite a lot of tsphinx extensions written in https://github.com/apache/airflow/tree/main/docs/exts that might not work well with sphinx-autobuild. But I think you will not find anyone here who already knows anything deep enough to resolve the issues and explain in detail how it works.

However, I am absolutely happy to help.

If you want to lead the effort and come with some specific questions and problems and results of your attempt - I am definitely happy to help. Ideally in the #documentation channel on slack. I know enough to be able to help when asked (not necesarily to solve the problems but possibly help to unstuck when you will get stuck), Also there ar enouhg people in the #documentation that might help independently if you share where you are stuck there. Maybe even at some point of time we can drag back @mik-laj to help us (It's been years since he did it and his focus is elsewhere, but if we get really stuck, maybe he will be able to remember something done years ago). I do not want to drag Kamil-in needlessly, as this is really a long time and I think we should build our own knowledge on how it works.

This will be similar and connected to what @utkarsharma2 is doing on attempting to migrate our CSS to Sphinx 7 (which is largely a replacement of dependencies - still waiting for https://pypi.org/project/sphinx-rtd-theme/1.3.0rc1/ to be released officially and some CSS work done by @utkarsharma2 to make our documentation look nice after migration to docutils > 0.19. By exploring how the toolset works to turn our documentation with the current CI pipeline and possibly updating some of the pipeline components, there is a chance that we will build such a more shared knowledge.

So maybe simply let's start discussing where everyone is stuck and the findings in the channel... and let's make our documentation buiilding better :). Seems that we have now at least 3 people who are vitally implement improvements there -(2 of them leading their parts and 1 (me) willing to help with the experience). I am sure also when we start discussing it in the channel, more helpful hands will show up.

PR of mine for Sphinx 7 migration here: apache/airflow-site#843