Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Add support for tabs (and other UX components) to docs #36041

Merged
merged 7 commits into from Dec 6, 2023
Merged

Add support for tabs (and other UX components) to docs #36041

merged 7 commits into from Dec 6, 2023

Conversation

josh-fell
Copy link
Contributor

@josh-fell josh-fell commented Dec 4, 2023 •
edited

This PR introduces the sphinx-design extension which provides numerous UX components such as tabs, cards, and dropdowns for documentation.

There are different ways or flavors of implementing or achieving the same result in Airflow whether that be in configuration, DAG authoring, etc. The current documentation explicitly lists these options as they appear which can lead to some lengthy doc pages as well as inconsistency in their presentation. Adding the ability to render these different options as tabs should combat both the verboseness and inconsistencies.

Closes: #29267

@boring-cyborg boring-cyborg bot added area:core-operators Operators, Sensors and hooks within Core Airflow kind:documentation labels Dec 4, 2023
@josh-fell
Copy link
Contributor Author

An example of using tabs to display both the TaskFlow API and operator-style in the Python how-to doc:

Screen.Recording.2023-12-03.at.10.51.52.PM.mov

@josh-fell josh-fell requested a review from BasPH December 4, 2023 03:53
@josh-fell josh-fell marked this pull request as ready for review December 4, 2023 03:59
BasPH
BasPH reviewed Dec 4, 2023
View reviewed changes
Copy link
Contributor

@BasPH BasPH left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This will be a great addition to the docs! One minor comment

setup.py Outdated Show resolved Hide resolved
@potiuk
Copy link
Member

potiuk commented Dec 4, 2023

Oh.. Fantastic ! :) . And you can also rebase now, after the pytest-asyncio test collection has been solved (0.23.2 relased with a fix after I raised an issue to them).

@eladkal
Copy link
Contributor

eladkal commented Dec 4, 2023

I noticed that when you change tab the URL stays fixed.
so is it not possible to send deep link that will view a specific tab?

@BasPH
Copy link
Contributor

BasPH commented Dec 4, 2023

I noticed that when you change tab the URL stays fixed. so is it not possible to send deep link that will view a specific tab?

Don't think it's currently possible. Found this PR: executablebooks/sphinx-design#104 but it's still open

@josh-fell
Copy link
Contributor Author

I noticed that when you change tab the URL stays fixed. so is it not possible to send deep link that will view a specific tab?

I agree with @BasPH. It's not entirely obvious, but maybe it's possible with the other attributes you can set on each item like class-container? I don't know CSS at all though.

@josh-fell
Copy link
Contributor Author

josh-fell commented Dec 5, 2023 •
edited

The latest and greatest version of the Python operators doc. I ended up splitting the example_python_operator DAG into the example_python_operator and example_python_decorator pattern with other operators that have TaskFlow equivalents. I also tried to make each chapter consistent, although not a total deep-dive.

Screen.Recording.2023-12-04.at.7.00.17.PM.mov

@josh-fell
Add support for tabs (and other UX components) to docs
ab09a4a 
This PR introduces the [`sphinx-design`](https://sphinx-design.readthedocs.io/en/alabaster-theme/index.html) extension which provides numerous UX components such as tabs, cards, and dropdowns for documentation.

There are different ways or flavors of implementing or achieving the same result in Airflow whether that be in configuration, DAG authoring, etc. The current documentation explicitly lists these options as they appear which can lead to some lengthy doc pages as well as inconsistency in their presentation. Any the ability to render these different options for as tabs should combat both the verboseness and inconsistencies.
@josh-fell
Set lower bound for sphinx-design
735aa59
@josh-fell
Split example DAGs and add doc consistency
132c7be
@josh-fell
fixup! Split example DAGs and add doc consistency
7e8f087
@josh-fell
Fix test_task_instance_endpoint tests
5e4292b
@josh-fell
Fix :sync: key for PythonOperator tab
1712a51
@josh-fell
Move function creation outside of loop in example DAGs
ff1eb7a
@uranusjr uranusjr merged commit 58e264c into apache:main Dec 6, 2023
72 checks passed
@ephraimbuddy ephraimbuddy added the type:doc-only Changelog: Doc Only label Dec 6, 2023
@ephraimbuddy ephraimbuddy added this to the Airflow 2.8.0 milestone Dec 6, 2023
ephraimbuddy pushed a commit that referenced this pull request Dec 6, 2023
@josh-fell @ephraimbuddy
Add support for tabs (and other UX components) to docs (#36041)
37519bf 
(cherry picked from commit 58e264c)
@josh-fell josh-fell deleted the code-example-tab-docs branch December 6, 2023 16:20
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@potiuk potiuk potiuk approved these changes

@uranusjr uranusjr uranusjr left review comments

@BasPH BasPH BasPH approved these changes

@kaxil kaxil Awaiting requested review from kaxil kaxil is a code owner

Assignees
No one assigned
Labels
area:core-operators Operators, Sensors and hooks within Core Airflow kind:documentation type:doc-only Changelog: Doc Only
Projects
None yet
Milestone
Airflow 2.8.0
Development

Successfully merging this pull request may close these issues.

Support tabs in docs
6 participants
@josh-fell @potiuk @eladkal @BasPH @uranusjr @ephraimbuddy