[jira] [Resolved] (AIRFLOW-3812) API Reference - Ambiguity of integration.rst and code.rst files

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

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

Kamil Bregula resolved AIRFLOW-3812.
------------------------------------
    Resolution: Fixed

> API Reference - Ambiguity of integration.rst and code.rst files
> ---------------------------------------------------------------
>
>                 Key: AIRFLOW-3812
>                 URL: https://issues.apache.org/jira/browse/AIRFLOW-3812
>             Project: Apache Airflow
>          Issue Type: Bug
>          Components: docs
>            Reporter: Kamil Bregula
>            Assignee: Kamil Bregula
>            Priority: Minor
>             Fix For: 2.0.0
>
>
> 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 rewrite the `integration.rst` file so that it does not contain duplicates from `code.rst ' (API Reference). In the next step, 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 delete information from the file `integration.rst` as short term solution and start working on creating another form of documentation as a long term solution. This is the best option in our opinion.
> Greetings
> Kamil Breguła



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