Ajay9704 commented on PR #60203: URL: https://github.com/apache/airflow/pull/60203#issuecomment-3957636172
I wanted to share a clear summary of everything I’ve tried so far regarding the BaseSensorOperator cross-reference issue. I have been working on this continuously for the past two days, and I even used AI at a few points just to understand parts of the structure better and debug the issue. Still, I haven’t been able to get to the root cause. At this point, I’m stuck and need some guidance from maintainers or reviewers. Below is everything I have tested from my side. 1. Including task-sdk in autoapi_dirs Added the task-sdk modules directly into autoapi_dirs. This produced 140+ RST formatting errors due to non-Sphinx-compatible docstrings in modules like api/, datamodels/, execution_time/, etc. Result: Documentation build failed. 2. Selective task-sdk inclusion using autoapi_ignore Tried to include only bases/sensor.py and ignore everything else. autoapi_ignore patterns didn’t work as expected and other task-sdk modules were still processed. Result: Same RST formatting errors as before. 3. Using intersphinx mapping only Tried linking to task-sdk via intersphinx after building task-sdk separately. Provider docs don’t build task-sdk locally, so no inventory was available. Result: BaseSensorOperator still appeared as plain text. 4. Enabling autoapi_generate_api_docs = True inside task-sdk Enabled full AutoAPI generation for task-sdk. This exposed multiple BaseOperator definitions across different files, which caused cross-reference conflicts. Result: Build failed with “more than one target found” errors. 5. Adding intersphinx mapping for common-compat Added intersphinx mapping for apache-airflow-providers-common-compat. Provider docs still couldn’t resolve references to its inventory. Result: Link still not generated. 6. Creating a manual BaseSensorOperator.rst file Created a proxy RST file pointing to airflow.sdk.bases.sensor. Sphinx still couldn’t resolve the reference. Result: Still plain text. 7. Updating _IMPORT_MAP inside common-compat Updated import map to point to the actual class location. This led to several import and LSP errors in sdk.py because it can’t access multiple airflow.sdk modules. Result: Build succeeded, but link was still not clickable. 8. Rebuilding after removing all changes Removed all previous changes and rebuilt everything cleanly. Duplicate BaseOperator definitions appeared again across layers. Result: Issue unchanged. Current State The documentation for all packages builds successfully. Only one unrelated warning remains (field list indentation in triggers). BaseSensorOperator is still not clickable anywhere in provider documentation. Request for Guidance I’ve spent quite a bit of time on this and tried many different approaches, but I’m still unable to understand why the reference is not resolving. I may be missing something fundamental about how Airflow handles documentation, lazy imports, or cross-references. It would be really helpful if maintainers or reviewers could guide me on how this is expected to work or what direction I should take next. Any clarification or help here would allow me to move forward and resolve this issue properly. -- 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]
