Deprecation of operators should be prominently highlighted instead of the one line remark in the documentation

peter-gergely-horvath commented 2 months ago

What do you see as an issue?

While working with GCP BigQuery operators, I have noticed that some of the operators are deprecated. As the message was not prominent enough, first I failed to notice it, coded some of my DAGs with the old operators and then needed to re-write them so as to avoid deprecated functions. This is not great when it comes to documentation UX.

For example: https://airflow.apache.org/docs/apache-airflow-providers-google/stable/_api/airflow/providers/google/cloud/operators/bigquery/index.html#airflow.providers.google.cloud.operators.bigquery.BigQueryExecuteQueryOperator

Unless you explicitly double check or look for the deprecation notice, it is very easy to overlook it.

Solving the problem

I would propose adding the deprecation notice more prominently and changing the title background for additional highlighting. If we know the operator is deprecated, all it takes is a little bit of CSS magic to make it absolutely stand out, say

Striking the name through
Different background color
Explicit statement of deprecation in the header

I imagine something like this would be good (at least it is hard to miss the point 😊). Again, nothing more than a few lines of CSS should do the trick:

Anything else

No response

Are you willing to submit PR?

[ ] Yes I am willing to submit a PR!

Code of Conduct

[X] I agree to follow this project's Code of Conduct

kaxil commented 2 months ago

I like your proposed solution @peter-gergely-horvath , would you like to help out with the PR? Might just be a change in this file:

https://github.com/apache/airflow/blob/main/docs/sphinx_design/static/custom.css

geraj1010 commented 2 months ago

@kaxil I'd be happy to take this on, if the issue is still open.

potiuk commented 2 months ago

Assigned you

peter-gergely-horvath commented 2 months ago

I like your proposed solution @peter-gergely-horvath , would you like to help out with the PR? Might just be a change in this file:

https://github.com/apache/airflow/blob/main/docs/sphinx_design/static/custom.css

Sorry guys, I only hacked the rendered page DOM inside the browser's dev tools to show what I mean here on a screenshot. I don't think I understand how the doc pages are generated.

RNHTTR commented 1 month ago

I like your proposed solution @peter-gergely-horvath , would you like to help out with the PR? Might just be a change in this file: https://github.com/apache/airflow/blob/main/docs/sphinx_design/static/custom.css

Sorry guys, I only hacked the rendered page DOM inside the browser's dev tools to show what I mean here on a screenshot. I don't think I understand how the doc pages are generated.

Here's the README for building docs and editing docs

github-actions[bot] commented 1 month ago

This issue has been automatically marked as stale because it has been open for 14 days with no response from the author. It will be closed in next 7 days if no further activity occurs from the issue author.

peter-gergely-horvath commented 1 month ago

The task is now picked up by geraj1010. I look forward to seeing the new design. :)

ferruzzi commented 3 weeks ago

@geraj1010 Are you still working on this one?

geraj1010 commented 3 weeks ago

@ferruzzi Yes I am. I recently just regained access to my account, so I have been delayed. Happy to collaborate on this.

omkar-foss commented 3 weeks ago

Hi, as discussed on this slack thread, there are a few Sphinx directives that can be explored that help do this without direct CSS changes:

.. error:: - https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-error
.. note:: - https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-note
.. attention:: - https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-attention

I suppose any that looks fine and catches the user's attention should be good enough.

cc: @ashb (thanks for the suggestion)

github-actions[bot] commented 3 days ago

This issue has been automatically marked as stale because it has been open for 14 days with no response from the author. It will be closed in next 7 days if no further activity occurs from the issue author.

apache / airflow