[GitHub] [airflow] mik-laj edited a comment on issue #12983: Add support selective docs/tests (provider-related) building in CI build-docs step

[GitBox <gi...@apache.org>]

mik-laj edited a comment on issue #12983:
URL: https://github.com/apache/airflow/issues/12983#issuecomment-762278361


   > I firmly believe we should optimize those things that have higher impact and bring more benefits. I hate doing micro-optimisations, I always think "long-term"/"high impact" when I am doing it.
   
   Any optimization that is not just a syntax change has a cost. Sometimes it is just a matter of dedicating time to implementation and reviews.  However, optimizations are very often associated with higher costs. In this case, it seems to me that we have several factors that we must take into account:
   
    - Hardware resources 
    - User experience
    - Reliability
    - Feedback time
   
   We can modify each of these factors independently but each influences the others.  If we try to optimize the feedback time very aggressively, it may affect its reliability. We will have to analyze and solve problems related to documentation, but we will not focus on the contribution itself.  We don't have too many experts who know the documentation process, so any such problem will be quite a pain to invest both for us and for new contributors who will not be aware that they have to overcome certain limitations of our optimization. 
   
   When it comes to feedback, we have a solution that is not overly burdensome for the contributor and is much faster than our CI. It is just building documentation locally where you can check documentation in less than 1 minute for most packages.  Encouraging the use of building documentation locally will also improve the user experience as the user will be able to quickly preview this change locally, but we need to encourage users to do so first.
   
    >  Looking at your example, this should be as easy as finding all ~airflow.providers references and we can build such a graph. 
    
    This is just one example, but it does not cover all possible ways to reference other packages. For example, the user can also reference using ````:ref:`howto/operator:BigtableCreateInstanceOperator` ```` or ```` :doc:`apache-airflow-providers-google:operators/cloud/bigtable.rst` ````. The number of combinations is almost unlimited, and these references can appear in both .rst and docstring files.  You are only sure of this when all these references are resolved, but this is done by Sphinx.
   


----------------------------------------------------------------
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.

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