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

[peter-gergely-horvath]

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

• I agree to follow this project's Code of Conduct

[kaxil]

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]

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

[potiuk]

Assigned you

[peter-gergely-horvath]

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]

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]

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]

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

[ferruzzi]

@geraj1010 Are you still working on this one?

[geraj1010]

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

[omkar-foss]

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]

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.

[geraj1010]

Greetings, I have been dragging my feet on this issue, but I am starting to look into it now. I think the attention or warning directive fits for this, as mentioned by @omkar-foss.

[geraj1010]

@peter-gergely-horvath I was able to add some additional highlighting to show that the operator is deprecated. It's not exactly like your mockup, but at least it stands out more than just plain text.

Thoughts?

[potiuk]

Looks good to me.

[geraj1010]

Thank you @potiuk.

[ferruzzi]

I like it too. Definitely an improvement.

[peter-gergely-horvath]

I would love to see title colour change and strike-through, but if that is difficult to implement, I think this is quite fine. :)

[kaxil]

And it can be iterative too: this is already a good improvement :)

[geraj1010]

I would love to see title colour change and strike-through, but if that is difficult to implement, I think this is quite fine. :)

Unfortunately, I think that would be difficult to implement. From what I understand, the documentation for the operators (and sensors) in the Python API section are gathered via Sphinx's AutoAPI extension at document generation runtime. This means that all styling is done on-the-fly and the index.rst files are not directly accessible until after rendering (in a phantom folder called _api).

I was thinking maybe we could achieve the original desired styling, by customizing the AutoAPI extension to look for any classes with the @deprecated decorator and apply a special custom ..py:class directive instead of the normal one. I think that would be very neat, but also a lot more work.

Thank you for the comment :)

[omkar-foss]

@geraj1010 it's looking nice & catchy! The user will definitely notice it while going through the doc I suppose, great work :)

[github-actions]

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.

[omkar-foss]

PR #43909 for this issue is active and approved, but just needs a rebase (this issue isn't necessarily stale as such).