incubator-airflow/docs
Jarek Potiuk 7b48feecbb Describe which Python versions are supported. (#13259)
* Describe what Python versions are supported.

As the result of vote: https://s.apache.org/8epvx - we agreed to
the rules of supporting Python versions. This PR adds it to
both README and official documentation.

* Update README.md

Co-authored-by: Xiaodong DENG <xd.deng.r@gmail.com>

Co-authored-by: Xiaodong DENG <xd.deng.r@gmail.com>
(cherry picked from commit a48bc837f8)
2021-01-21 18:14:46 +00:00
..
apache-airflow Describe which Python versions are supported. (#13259) 2021-01-21 18:14:46 +00:00
apache-airflow-providers Adds documentation about custom providers. (#12921) 2020-12-09 11:35:54 +01:00
apache-airflow-providers-amazon Add link to PyPI Repository to provider docs (#13064) 2021-01-21 17:36:57 +00:00
apache-airflow-providers-apache-cassandra Add link to PyPI Repository to provider docs (#13064) 2021-01-21 17:36:57 +00:00
apache-airflow-providers-apache-druid Add link to PyPI Repository to provider docs (#13064) 2021-01-21 17:36:57 +00:00
apache-airflow-providers-apache-hdfs Add link to PyPI Repository to provider docs (#13064) 2021-01-21 17:36:57 +00:00
apache-airflow-providers-apache-hive Add link to PyPI Repository to provider docs (#13064) 2021-01-21 17:36:57 +00:00
apache-airflow-providers-apache-kylin Add link to PyPI Repository to provider docs (#13064) 2021-01-21 17:36:57 +00:00
apache-airflow-providers-apache-livy Add link to PyPI Repository to provider docs (#13064) 2021-01-21 17:36:57 +00:00
apache-airflow-providers-apache-pig Add link to PyPI Repository to provider docs (#13064) 2021-01-21 17:36:57 +00:00
apache-airflow-providers-apache-pinot Add link to PyPI Repository to provider docs (#13064) 2021-01-21 17:36:57 +00:00
apache-airflow-providers-apache-spark Add link to PyPI Repository to provider docs (#13064) 2021-01-21 17:36:57 +00:00
apache-airflow-providers-apache-sqoop Add link to PyPI Repository to provider docs (#13064) 2021-01-21 17:36:57 +00:00
apache-airflow-providers-celery Add link to PyPI Repository to provider docs (#13064) 2021-01-21 17:36:57 +00:00
apache-airflow-providers-cloudant Add link to PyPI Repository to provider docs (#13064) 2021-01-21 17:36:57 +00:00
apache-airflow-providers-cncf-kubernetes Add link to PyPI Repository to provider docs (#13064) 2021-01-21 17:36:57 +00:00
apache-airflow-providers-databricks Add link to PyPI Repository to provider docs (#13064) 2021-01-21 17:36:57 +00:00
apache-airflow-providers-datadog Add link to PyPI Repository to provider docs (#13064) 2021-01-21 17:36:57 +00:00
apache-airflow-providers-dingding Add link to PyPI Repository to provider docs (#13064) 2021-01-21 17:36:57 +00:00
apache-airflow-providers-discord Add link to PyPI Repository to provider docs (#13064) 2021-01-21 17:36:57 +00:00
apache-airflow-providers-docker Add link to PyPI Repository to provider docs (#13064) 2021-01-21 17:36:57 +00:00
apache-airflow-providers-elasticsearch Add link to PyPI Repository to provider docs (#13064) 2021-01-21 17:36:57 +00:00
apache-airflow-providers-exasol Add link to PyPI Repository to provider docs (#13064) 2021-01-21 17:36:57 +00:00
apache-airflow-providers-facebook Add link to PyPI Repository to provider docs (#13064) 2021-01-21 17:36:57 +00:00
apache-airflow-providers-ftp Add link to PyPI Repository to provider docs (#13064) 2021-01-21 17:36:57 +00:00
apache-airflow-providers-google Add link to PyPI Repository to provider docs (#13064) 2021-01-21 17:36:57 +00:00
apache-airflow-providers-grpc Add link to PyPI Repository to provider docs (#13064) 2021-01-21 17:36:57 +00:00
apache-airflow-providers-hashicorp Add link to PyPI Repository to provider docs (#13064) 2021-01-21 17:36:57 +00:00
apache-airflow-providers-http Add link to PyPI Repository to provider docs (#13064) 2021-01-21 17:36:57 +00:00
apache-airflow-providers-imap Add link to PyPI Repository to provider docs (#13064) 2021-01-21 17:36:57 +00:00
apache-airflow-providers-jdbc Add link to PyPI Repository to provider docs (#13064) 2021-01-21 17:36:57 +00:00
apache-airflow-providers-jenkins Add link to PyPI Repository to provider docs (#13064) 2021-01-21 17:36:57 +00:00
apache-airflow-providers-jira Add link to PyPI Repository to provider docs (#13064) 2021-01-21 17:36:57 +00:00
apache-airflow-providers-microsoft-azure Add link to PyPI Repository to provider docs (#13064) 2021-01-21 17:36:57 +00:00
apache-airflow-providers-microsoft-mssql Add link to PyPI Repository to provider docs (#13064) 2021-01-21 17:36:57 +00:00
apache-airflow-providers-microsoft-winrm Add link to PyPI Repository to provider docs (#13064) 2021-01-21 17:36:57 +00:00
apache-airflow-providers-mongo Add link to PyPI Repository to provider docs (#13064) 2021-01-21 17:36:57 +00:00
apache-airflow-providers-mysql Add link to PyPI Repository to provider docs (#13064) 2021-01-21 17:36:57 +00:00
apache-airflow-providers-odbc Add link to PyPI Repository to provider docs (#13064) 2021-01-21 17:36:57 +00:00
apache-airflow-providers-openfaas Add link to PyPI Repository to provider docs (#13064) 2021-01-21 17:36:57 +00:00
apache-airflow-providers-opsgenie Add link to PyPI Repository to provider docs (#13064) 2021-01-21 17:36:57 +00:00
apache-airflow-providers-oracle Add link to PyPI Repository to provider docs (#13064) 2021-01-21 17:36:57 +00:00
apache-airflow-providers-pagerduty Add link to PyPI Repository to provider docs (#13064) 2021-01-21 17:36:57 +00:00
apache-airflow-providers-papermill Add link to PyPI Repository to provider docs (#13064) 2021-01-21 17:36:57 +00:00
apache-airflow-providers-plexus Add link to PyPI Repository to provider docs (#13064) 2021-01-21 17:36:57 +00:00
apache-airflow-providers-postgres Add link to PyPI Repository to provider docs (#13064) 2021-01-21 17:36:57 +00:00
apache-airflow-providers-presto Add link to PyPI Repository to provider docs (#13064) 2021-01-21 17:36:57 +00:00
apache-airflow-providers-qubole Add link to PyPI Repository to provider docs (#13064) 2021-01-21 17:36:57 +00:00
apache-airflow-providers-redis Add link to PyPI Repository to provider docs (#13064) 2021-01-21 17:36:57 +00:00
apache-airflow-providers-salesforce Add link to PyPI Repository to provider docs (#13064) 2021-01-21 17:36:57 +00:00
apache-airflow-providers-samba Add link to PyPI Repository to provider docs (#13064) 2021-01-21 17:36:57 +00:00
apache-airflow-providers-segment Add link to PyPI Repository to provider docs (#13064) 2021-01-21 17:36:57 +00:00
apache-airflow-providers-sendgrid Add link to PyPI Repository to provider docs (#13064) 2021-01-21 17:36:57 +00:00
apache-airflow-providers-sftp Add link to PyPI Repository to provider docs (#13064) 2021-01-21 17:36:57 +00:00
apache-airflow-providers-singularity Add link to PyPI Repository to provider docs (#13064) 2021-01-21 17:36:57 +00:00
apache-airflow-providers-slack Add link to PyPI Repository to provider docs (#13064) 2021-01-21 17:36:57 +00:00
apache-airflow-providers-snowflake Add link to PyPI Repository to provider docs (#13064) 2021-01-21 17:36:57 +00:00
apache-airflow-providers-sqlite Add link to PyPI Repository to provider docs (#13064) 2021-01-21 17:36:57 +00:00
apache-airflow-providers-ssh Add link to PyPI Repository to provider docs (#13064) 2021-01-21 17:36:57 +00:00
apache-airflow-providers-telegram Add link to PyPI Repository to provider docs (#13064) 2021-01-21 17:36:57 +00:00
apache-airflow-providers-vertica Add link to PyPI Repository to provider docs (#13064) 2021-01-21 17:36:57 +00:00
apache-airflow-providers-yandex Add link to PyPI Repository to provider docs (#13064) 2021-01-21 17:36:57 +00:00
apache-airflow-providers-zendesk Add link to PyPI Repository to provider docs (#13064) 2021-01-21 17:36:57 +00:00
exts Add link to PyPI Repository to provider docs (#13064) 2021-01-21 17:36:57 +00:00
rtd-deprecation Fix build on RTD (#12551) 2020-11-23 09:52:24 +01:00
README.rst Fix link to Airflow master branch documentation (#13179) 2021-01-21 18:14:26 +00:00
build_docs.py Add link to PyPI Repository to provider docs (#13064) 2021-01-21 17:36:57 +00:00
conf.py Fetch inventories for third-party services only once (#13068) 2021-01-21 17:30:19 +00:00
list-roles.sh Separate out documentation building per provider (#12444) 2020-11-20 15:35:56 +01:00
publish_docs.py Fix broken build of docs/ by removing unused import (#13007) 2020-12-11 09:03:46 +00:00
spelling_wordlist.txt Changes release image preparation to use PyPI packages (#12990) 2020-12-12 12:01:58 +01:00
start_doc_server.sh Separate out documentation building per provider (#12444) 2020-11-20 15:35:56 +01:00

README.rst

 .. 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/>`__.

For Helm Chart, see: `/chart/README.md <../chart/READMe.md>`__

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

Documentation from the ``master`` branch is built and automatically published: `s.apache.org/airflow-docs <https://s.apache.org/airflow-docs>`_

Documentation for your PRs is available as downloadable artifact in GitHub Actions after the CI builds your PR.

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

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