[
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)
