[GitHub] [airflow] potiuk opened a new issue, #31963: Upgrade Sphinx to version 7 to improve documentation errors

["potiuk (via GitHub)" <gi...@apache.org>]

potiuk opened a new issue, #31963:
URL: https://github.com/apache/airflow/issues/31963

   ### Body
   
   We should upgrade Sphinx to version 7
   
   Sphinx 6 has known issues with informing about various errors in our documentation and it becomes REALLY painful. Quite often contributors are mind-boggled by the errors in their documentation after they have done apparently and innocent change. Even super-experienced engineers have hard time figuring out what the error really is and often we have to revert to some woodo-like practices like bisecting in order to narrow down and fix the problems. 
   
   Recent examples of such problems which caused us hours of debugging are :
   
   * https://github.com/apache/airflow/pull/30326#discussion_r1162323325 - where ` -> ' change cause hours of debugging and was only found by bisecting
   
   * https://github.com/apache/airflow/pull/31731#discussion_r1232236952 - where lack of empty lines caused the same and also was found by bisecting
   
   What holds us freom migration though is the lack of support for sphinx 7 in the sphinx_rtd-theme which we are using as the base for airflow theme. We build and publish our theme in https://github.com/apache/airflow-site and the sphinx_rtd_theme issue is:
   
   * Described here https://github.com/readthedocs/sphinx_rtd_theme/issues/1463
   * Proposed PR to fix it here: https://github.com/readthedocs/sphinx_rtd_theme/pull/1464
   
   There are three ways how this can be solved:
   
   1) make sphinx_rtd_theme release sphinx7 theme and switch to it
   2) vendor in sphinx_rtd_theme into airlfow theme and make necessary changes to support sphinx7 
   3) switch to another theme.
   
   
   If 1) cannot be achieved, seems that 2) might be the easiest one to achieve it.
   
   
   
   ### Committer
   
   - [X] I acknowledge that I am a maintainer/committer of the Apache Airflow project.


-- 
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: commits-unsubscribe@airflow.apache.org.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org