[GitHub] [airflow] mik-laj edited a comment on issue #11423: Separate out documentation building and publishing per provider

[GitBox <gi...@apache.org>]

mik-laj edited a comment on issue #11423:
URL: https://github.com/apache/airflow/issues/11423#issuecomment-722226813


   I worked on this ticket yesterday / today and managed to build documentation for providers package..
   https://wicked-army.surge.sh/
   I haven't migrated all the content yet, but the most difficult case - Google package have been successfully migrated fully, along with reference documentation for Python API and configuration.
   https://wicked-army.surge.sh/google/html/index.html
   
   There are two more serious issues that need to be discussed.
   1. **ReadtheDocs**:  Unfortunately, we will have to abandon ReadTheDocs to build the documentation. It doesn't allow you to run your own build scripts. and we can only have one documentation for the repository. Besides, it causes various problems over which we have little control. For example, now Python API reference documentation does not build properly - https://airflow.readthedocs.io/en/latest/_api/index.html
   We will probably be able to solve this problem quickly if we receive financial support for CI. Then we will be able to build the documentation ourselves and publish on S3/GCS or other.
   
   2. **Operators and hooks**: This page have information from all providers, so it is not possible to divide it.
   https://airflow.readthedocs.io/en/latest/operators-and-hooks-ref.html
   In its present form, it cannot remain if we want to have a separate docs per provider. I propose that we maintain the same information in the YAML file and then reuse them as needed.
   For development purposes, we can generate a markdown file which we will store in the repository.
   For production/website, we can also display this data as a markdown on website, or ... as build a complex interface similar to [Terraofmr Registry](https://registry.terraform.io/browse/providers?tier=official%2Cpartner).  It could be fairly simple if we have all data in YAML and we had a contributor with React experience.
   
   CC: @ryw @potiuk @iadi7ya @francescomucio @jward-bw @jhtimmins @kaxil @paolaperaza @pcandoalmeida @xinbinhuang
   
   Related issue: https://github.com/apache/airflow-site/issues/301


----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

For queries about this service, please contact Infrastructure at:
users@infra.apache.org