Documentation

This directory contains documentation for the Apache Airflow project and other packages that are closely related to it ie. providers packages. Documentation is built using Sphinx.

Development documentation preview

Documentation from the development version is built and automatically published: s.apache.org/airflow-docs

Building documentation

To generate a local version you can use ../BREEZE.rst.

The documentation build consists of verifying consistency of documentation and two steps:

• spell checking
• building documentation

You can only run one of the steps via --spellcheck-only or --docs-only.

breeze build-docs

or just to run spell-check

breeze build-docs --spellcheck-only

or just to run documentation building

breeze build-docs --docs-only

Also, you can only build one documentation via --package-filter.

breeze build-docs --package-filter <PACKAGE-NAME>

You can also use shorthand names as arguments instead of using the full names for airflow providers. To find the short hand names, follow the instructions in :ref:`generating_short_form_names`.

You can also see all the available arguments via --help.

breeze build-docs --help

Running the Docs Locally

Once you have built the documentation run the following command from the root directory, You need to have Python installed to run the command:

docs/start_doc_server.sh

Then, view your docs at localhost:8000, if you are using a virtual machine e.g WSL2, you need to find the WSL2 machine IP address and in your browser replace "0.0.0.0" with it http://n.n.n.n:8000, where n.n.n.n will be the IP of the WSL2.

Troubleshooting

If you are creating example_dags directory, you need to create example_dags/__init__.py with Apache license or copy another __init__.py file that contains the necessary license.

Generating short form names for Providers

Skip the apache-airflow-providers- from the usual provider full names. Now with the remaining part, replace every dash("-") with a dot(".").

Example: If the provider name is apache-airflow-providers-cncf-kubernetes, it will be cncf.kubernetes.

Note: For building docs for apache-airflow-providers index, use providers-index as the short hand operator.

Cross-referencing syntax

Cross-references are generated by many semantic interpreted text roles. Basically, you only need to write:

:role:`target`

And a link will be created to the item named target of the type indicated by role. The link's text will be the same as target.

You may supply an explicit title and reference target, like in reST direct hyperlinks:

:role:`title <target>`

This will refer to target, but the link text will be title.

Here are practical examples:

:class:`airflow.models.dag.DAG` - link to Python API reference documentation
:doc:`/docs/operators` - link to other document
:ref:`handle` - link to section in current or another document

.. _handle:

Section title
----------------------------------

Role :class: works well with references between packages. If you want to use other roles, it is a good idea to specify a package:

:doc:`apache-airflow:installation/index`
:ref:`apache-airflow-providers-google:write-logs-stackdriver`

If you still feel confused then you can view more possible roles for our documentation:

./list-roles.sh

For more information, see: Cross-referencing syntax in Sphinx documentation

Support

If you need help, write to #documentation channel on Airflow's Slack