 .. Licensed to the Apache Software Foundation (ASF) under one
    or more contributor license agreements.  See the NOTICE file
    distributed with this work for additional information
    regarding copyright ownership.  The ASF licenses this file
    to you under the Apache License, Version 2.0 (the
    "License"); you may not use this file except in compliance
    with the License.  You may obtain a copy of the License at

 ..   http://www.apache.org/licenses/LICENSE-2.0

 .. Unless required by applicable law or agreed to in writing,
    software distributed under the License is distributed on an
    "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
    KIND, either express or implied.  See the License for the
    specific language governing permissions and limitations
    under the License.

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 <https://www.sphinx-doc.org/>`__.

Development documentation preview
==================================

Documentation from the development version is built and automatically published: `s.apache.org/airflow-docs <https://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``.

.. code-block:: bash

    breeze build-docs

or just to run spell-check

.. code-block:: bash

     breeze build-docs --spellcheck-only

or just to run documentation building

.. code-block:: bash

     breeze build-docs --docs-only

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

.. code-block:: bash

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

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

.. code-block:: bash

    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:

.. code-block:: bash

    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.

Cross-referencing syntax
========================

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

.. code-block:: rst

    :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:

.. code-block:: rst

    :role:`title <target>`

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

Here are practical examples:

.. code-block:: rst

    :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:

.. code-block:: rst

    :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:

.. code-block:: bash

    ./list-roles.sh

For more information, see: `Cross-referencing syntax <https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html>`_ in Sphinx documentation

Support
=======

If you need help, write to `#documentation <https://apache-airflow.slack.com/archives/CJ1LVREHX>`__ channel on `Airflow's Slack <https://s.apache.org/airflow-slack>`__