This is an automated email from the ASF dual-hosted git repository.
kaxilnaik pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/airflow.git
The following commit(s) were added to refs/heads/main by this push:
new b3dad0969e1 Fix left navigation and public interface docs in core docs
(#55967)
b3dad0969e1 is described below
commit b3dad0969e112a55be5f842c6bf21334fd5f2d35
Author: Jed Cunningham <[email protected]>
AuthorDate: Mon Sep 22 15:53:29 2025 -0600
Fix left navigation and public interface docs in core docs (#55967)
We've accidentally hidden all of the subpages in the left nav of the
core docs, meaning, you couldnt even navigate to the upgrading docs.
Oops.
This fixes that, and also fixes the public interface docs that led to
the mistake initially.
---
airflow-core/docs/index.rst | 3 --
airflow-core/docs/public-airflow-interface.rst | 69 +++++++++++---------------
2 files changed, 29 insertions(+), 43 deletions(-)
diff --git a/airflow-core/docs/index.rst b/airflow-core/docs/index.rst
index cf34b0da8ea..fc2d641d306 100644
--- a/airflow-core/docs/index.rst
+++ b/airflow-core/docs/index.rst
@@ -144,13 +144,10 @@ experience is continuously improving, but defining
workflows as code is central
.. toctree::
:hidden:
:caption: Content
- :titlesonly:
- :maxdepth: 1
Overview <self>
start
installation/index
- installation/upgrading_to_airflow3
security/index
tutorial/index
howto/index
diff --git a/airflow-core/docs/public-airflow-interface.rst
b/airflow-core/docs/public-airflow-interface.rst
index 9abe6cbd5cb..a4221e4c3fe 100644
--- a/airflow-core/docs/public-airflow-interface.rst
+++ b/airflow-core/docs/public-airflow-interface.rst
@@ -15,9 +15,8 @@
specific language governing permissions and limitations
under the License.
-=====================================
Public Interface for Airflow 3.0+
-=====================================
+=================================
.. warning::
@@ -27,9 +26,6 @@ Public Interface for Airflow 3.0+
`Airflow 2.11 Public Interface Documentation
<https://airflow.apache.org/docs/apache-airflow/2.11.0/public-airflow-interface.html>`_
for the legacy interface.
-Public Interface of Airflow
-...........................
-
The Public Interface of Apache Airflow is the collection of interfaces and
behaviors in Apache Airflow
whose changes are governed by semantic versioning. A user interacts with
Airflow's public interface
by creating and managing Dags, managing tasks and dependencies,
@@ -46,7 +42,7 @@ from task code is no longer allowed. Instead, use the
:doc:`Stable REST API <sta
For comprehensive Task SDK documentation, see the `Task SDK Reference
<https://airflow.apache.org/docs/task-sdk/stable/>`_.
Using Airflow Public Interfaces
-===============================
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. note::
@@ -89,7 +85,7 @@ way, the Stable REST API is recommended.
Using the Public Interface for Dag authors
-==========================================
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The primary interface for Dag authors is the :doc:`airflow.sdk namespace
<core-concepts/taskflow>`.
This provides a stable, well-defined interface for creating Dags and tasks
that is not subject to internal
@@ -142,7 +138,7 @@ Legacy import paths (e.g., ``airflow.models.dag.DAG``,
``airflow.decorator.task`
removed in a future Airflow version.
Dags
-====
+----
The Dag is Airflow's core entity that represents a recurring workflow. You can
create a Dag by
instantiating the :class:`~airflow.sdk.DAG` class in your Dag file. Dags can
also have parameters
@@ -156,7 +152,6 @@ Airflow has a set of example Dags that you can use to learn
how to write Dags
.. toctree::
:includehidden:
:glob:
- :hidden:
:maxdepth: 1
_api/airflow/example_dags/index
@@ -183,7 +178,7 @@ References for the modules used in Dags are here:
.. _pythonapi:operators:
Operators
-=========
+---------
The base classes :class:`~airflow.sdk.BaseOperator` and
:class:`~airflow.sdk.BaseSensorOperator` are public and may be extended to make
new operators.
@@ -193,7 +188,7 @@ from the airflow.sdk namespace.
Subclasses of BaseOperator which are published in Apache Airflow are public in
*behavior* but not in *structure*. That is to say, the Operator's parameters
and behavior is governed by semver but the methods are subject to change at any
time.
Task Instances
-==============
+--------------
Task instances are the individual runs of a single task in a Dag (in a Dag
Run). Task instances are accessed through
the Task Context via :func:`~airflow.sdk.get_current_context`. Direct database
access is not possible.
@@ -203,7 +198,7 @@ the Task Context via
:func:`~airflow.sdk.get_current_context`. Direct database a
For detailed API documentation, see the `Task SDK Reference
<https://airflow.apache.org/docs/task-sdk/stable/>`_.
Task Instance Keys
-==================
+------------------
Task instance keys are unique identifiers of task instances in a Dag (in a Dag
Run). A key is a tuple that consists of
``dag_id``, ``task_id``, ``run_id``, ``try_number``, and ``map_index``.
@@ -240,7 +235,7 @@ Example of accessing task instance information through Task
Context:
.. _pythonapi:hooks:
Hooks
-=====
+-----
Hooks are interfaces to external platforms and databases, implementing a common
interface when possible and acting as building blocks for operators. All hooks
@@ -252,13 +247,12 @@ by extending them:
.. toctree::
:includehidden:
:glob:
- :hidden:
:maxdepth: 1
_api/airflow/hooks/index
Public Airflow utilities
-========================
+^^^^^^^^^^^^^^^^^^^^^^^^
When writing or extending Hooks and Operators, Dag authors and developers can
use the following classes:
@@ -309,7 +303,7 @@ Reference for classes used for the utilities are here:
Public Exceptions
-=================
+^^^^^^^^^^^^^^^^^
When writing the custom Operators and Hooks, you can handle and raise public
Exceptions that Airflow
exposes:
@@ -317,25 +311,23 @@ exposes:
.. toctree::
:includehidden:
:glob:
- :hidden:
:maxdepth: 1
_api/airflow/exceptions/index
Public Utility classes
-======================
+^^^^^^^^^^^^^^^^^^^^^^
.. toctree::
:includehidden:
:glob:
- :hidden:
:maxdepth: 1
_api/airflow/utils/state/index
Using Public Interface to extend Airflow capabilities
-=====================================================
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Airflow uses Plugin mechanism to extend Airflow platform capabilities. They
allow to extend
Airflow UI but also they are the way to expose the below customizations
(Triggers, Timetables, Listeners, etc.).
@@ -348,7 +340,7 @@ that do not require plugins - you can read more about them
in :doc:`howto/custom
Here are the ways how Plugins can be used to extend Airflow:
Triggers
-========
+--------
Airflow uses Triggers to implement ``asyncio`` compatible Deferrable Operators.
All Triggers derive from :class:`~airflow.triggers.base.BaseTrigger`.
@@ -359,7 +351,6 @@ by extending them:
.. toctree::
:includehidden:
:glob:
- :hidden:
:maxdepth: 1
_api/airflow/triggers/index
@@ -367,7 +358,7 @@ by extending them:
You can read more about Triggers in :doc:`authoring-and-scheduling/deferring`.
Timetables
-==========
+----------
Custom timetable implementations provide Airflow's scheduler additional logic
to
schedule Dag runs in ways not possible with built-in schedule expressions.
@@ -378,7 +369,6 @@ by extending them:
.. toctree::
:includehidden:
- :hidden:
:maxdepth: 1
_api/airflow/timetables/index
@@ -386,7 +376,7 @@ by extending them:
You can read more about Timetables in :doc:`howto/timetable`.
Listeners
-=========
+---------
Listeners enable you to respond to Dag/Task lifecycle events.
@@ -400,7 +390,7 @@ can be implemented to respond to Dag/Task lifecycle events.
You can read more about Listeners in
:doc:`administration-and-deployment/listeners`.
Extra Links
-===========
+-----------
Extra links are dynamic links that could be added to Airflow independently
from custom Operators. Normally
they can be defined by the Operators, but plugins allow you to override the
links on a global level.
@@ -408,7 +398,7 @@ they can be defined by the Operators, but plugins allow you
to override the link
You can read more about the Extra Links in :doc:`/howto/define-extra-link`.
Using Public Interface to integrate with external services and applications
-===========================================================================
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Tasks in Airflow can orchestrate external services via Hooks and Operators.
The core functionality of
@@ -417,7 +407,7 @@ You can read more about providers :doc:`providers
<apache-airflow-providers:inde
extensions they can provide in :doc:`providers
<apache-airflow-providers:core-extensions/index>`.
Executors
-=========
+---------
Executors are the mechanism by which task instances get run. All executors are
derived from :class:`~airflow.executors.base_executor.BaseExecutor`. There are
several
@@ -437,7 +427,7 @@ You can read more about executors and how to write your own
in :doc:`core-concep
executors, and custom executors could not provide full functionality that
built-in executors had.
Secrets Backends
-================
+----------------
Airflow can be configured to rely on secrets backends to retrieve
:class:`~airflow.sdk.Connection` and :class:`~airflow.sdk.Variable`.
@@ -448,7 +438,6 @@ All Secrets Backend implementations are public. You can
extend their functionali
.. toctree::
:includehidden:
:glob:
- :hidden:
:maxdepth: 1
_api/airflow/secrets/index
@@ -458,7 +447,7 @@ You can also find all the available Secrets Backends
implemented in community pr
in :doc:`apache-airflow-providers:core-extensions/secrets-backends`.
Auth managers
-=============
+-------------
Auth managers are responsible of user authentication and user authorization in
Airflow. All auth managers are
derived from
:class:`~airflow.api_fastapi.auth.managers.base_auth_manager.BaseAuthManager`.
@@ -469,21 +458,21 @@ public, but the different implementations of auth
managers are not (i.e. FabAuth
You can read more about auth managers and how to write your own in
:doc:`core-concepts/auth-manager/index`.
Connections
-===========
+-----------
When creating Hooks, you can add custom Connections. You can read more
about connections in
:doc:`apache-airflow-providers:core-extensions/connections` for available
Connections implemented in the community providers.
Extra Links
-===========
+-----------
When creating Hooks, you can add custom Extra Links that are displayed when
the tasks are run.
You can find out more about extra links in
:doc:`apache-airflow-providers:core-extensions/extra-links`
that also shows available extra links implemented in the community providers.
Logging and Monitoring
-======================
+----------------------
You can extend the way how logs are written by Airflow. You can find out more
about log writing in
:doc:`administration-and-deployment/logging-monitoring/index`.
@@ -492,7 +481,7 @@ The :doc:`apache-airflow-providers:core-extensions/logging`
that also shows avai
implemented in the community providers.
Decorators
-==========
+----------
Dag authors can use decorators to author Dags using the :doc:`TaskFlow
<core-concepts/taskflow>` concept.
All Decorators derive from :class:`~airflow.sdk.bases.decorator.TaskDecorator`.
@@ -512,24 +501,24 @@ by extending them:
You can read more about creating custom Decorators in
:doc:`howto/create-custom-decorator`.
Email notifications
-===================
+-------------------
Airflow has a built-in way of sending email notifications and it allows to
extend it by adding custom
email notification classes. You can read more about email notifications in
:doc:`howto/email-config`.
Notifications
-=============
+-------------
Airflow has a built-in extensible way of sending notifications using the
various ``on_*_callback``. You can read more
about notifications in :doc:`howto/notifications`.
Cluster Policies
-================
+----------------
Cluster Policies are the way to dynamically apply cluster-wide policies to the
Dags being parsed or tasks
being executed. You can read more about Cluster Policies in
:doc:`administration-and-deployment/cluster-policies`.
Lineage
-=======
+-------
Airflow can help track origins of data, what happens to it and where it moves
over time. You can read more
about lineage in :doc:`administration-and-deployment/lineage`.
@@ -538,7 +527,7 @@ about lineage in
:doc:`administration-and-deployment/lineage`.
What is not part of the Public Interface of Apache Airflow?
-===========================================================
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Everything not mentioned in this document should be considered as non-Public
Interface.
