[jira] [Updated] (AIRFLOW-3811) Automatic generation of API Reference

["Kamil Bregula (JIRA)" <ji...@apache.org>]

     [ https://issues.apache.org/jira/browse/AIRFLOW-3811?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]

Kamil Bregula updated AIRFLOW-3811:
-----------------------------------
    Description: 
Hello community,

We want to introduce the reference API generation based on the source code that will replace the `code.rst` file.

Greetings

  was:
Hello community,

While working on the documentation for the GCP operators, my team at Polidea encountered some confusion related to the structure of the documentation.

Short story:

We want to introduce the reference API generation based on the source code that will replace the `code.rst` file.

Long story:

Currently, the documentation contains two places where the description of classes related to operators is included. They are `code.rst` and `integration.rst` files.

The `integration.rst` file contains information about integration, in particular for Azure: Microsoft Azure, AWS: Amazon Web Services, Databricks, GCP: Google Cloud Platform, Qubole. Other integrations, however, do not have descriptions.

The `code.rst` file contains “API Reference” which contains information about *all* classes including those included in the file `integration.rst`.

Such duplication, however, is problematic for several reasons:

Users may feel lost and may not know which section they should look into.

Changes must be made in many places which leads to desynchronization. Most often, changes are made only in the source code, so they do not appear in the generated documentation.

Linking to classes using the `class` directive for Sphinx is inconclusive - if the code is embedded both in `integration.rst` and `code.rst` using the `autoclass` directive, we’re not sure where the user will be navigated.

We should start working on creating another form of documentation as a long term solution.

Greetings


> Automatic generation of API Reference
> -------------------------------------
>
>                 Key: AIRFLOW-3811
>                 URL: https://issues.apache.org/jira/browse/AIRFLOW-3811
>             Project: Apache Airflow
>          Issue Type: Improvement
>          Components: docs
>            Reporter: Kamil Bregula
>            Assignee: Kamil Bregula
>            Priority: Minor
>
> Hello community,
> We want to introduce the reference API generation based on the source code that will replace the `code.rst` file.
> Greetings



--
This message was sent by Atlassian JIRA
(v7.6.3#76005)