potiuk opened a new issue, #45613: URL: https://github.com/apache/airflow/issues/45613
During the recent "quest" with upgrading Sphinx for airflow docs generation we found that the current approach of sharing sphinx-airflow-theme and doc updates in airflow is a very difficult one to make and test changes. The process - especially when involving changes that require modifications in both - theme and doc generation process in Airflow is very complex today: 1) someone has to figure out changes in both "theme" and doc building 2) there should be a PR merged in "airflow-site" sphinx-airflow-theme 3) the sphinx-airflow-theme has to be build (which is a challenge on its own on a modern OS - we have to use some old versions of OS as a base and it does not work on MacOS) 4) the sphinx-airlfow-theme has to be published in PyPI (only a handful of people can do it) 5) there should be a PR in Airlfow docs building to switch to using this new theme and only then you can really test if this worked You can somehow manually attempt and builld those theme projects between repos and use them without publishing to PyPI - and try to locally build image, but - for example until the `sphinx-airlfow-theme` package is published to PyPI, we cannot reall run PR in Airlfow docs through CI. This is very complex and difficult and we should simplify it. The proposal to simplify it: - [ ] modernize "sphinx-airflow-theme" to use standard pyproject.toml and build backends to build the theme with `uv build` or `hatch build` frontend - including node/npm setup and conifiguration that does not require old OS - [ ] move the `sphinx-airlfow-theme` to **airflow** repo as sub-project, all separated from airflow code (in docs dir) and connected via `uv workspace` with the main airflow repo. This will allow also to remove `doc` extra from `airflow` package (dependencies will move to the `sphinx-airlfow-theme` project and will be used from there. The `sphinx-airflow-theme` package will be used by doc building process from the locally installed package, which means that you will be able to test and modify the process as a single `PR` - all runnable and testable in CI and you will be able to use regular `breeze build-docs` to build and test the documentation - [ ] once we move the standard pyproject.toml exposed in Airflow repo, we could modify airlfow-site to NOT use local version or PyPI - but install the `sphinx-airlfow-theme` following the github URL installation pattern `pip install "sphinx-airflow-theme @ git+https://github.com/apache/airflow/docs/sphinx-airflow-theme/@BRANCH` - which is one of the standard ways of instaling modern python packages https://pip.pypa.io/en/stable/topics/vcs-support/ - that would completely remove the need of publishing the `sphinx-airflow-theme` to PyPI -- 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]
