Add redoc docs to sphinx

[mik-laj]

Hello,

Close: #8119

I added reference documentation to our documentation in Sphinx. I analyzed two Swagger UI and Redoc tools, but I decided to integrate Redoc for three reasons.

• First of all, it is possible to add code samples of using the client API in different languages thanks to the x-codesamples extension. This will facilitate the use of this API very much and will also provide ready documentation for these clients. Less duplicate documentation.
• Secondly, Redoc is just two files: 1 HTML and 1 JS, so its integration is very simple. :-D
• A great contributor, an excellent developer - @ad-m uses this in their projects. This is a great recommendation, which fully convinces me that this is a good choice.

Best regards,
Kamil Breguła

---

Make sure to mark the boxes below before creating PR: [x]

• Description above provides context of the change
• Unit tests coverage for changes (not needed for documentation changes)
• Target Github ISSUE in description if exists
• Commits follow "How to write a good git commit message"
• Relevant documentation is updated including usage instructions.
• I will engage committers as explained in Contribution Workflow Example.

---

In case of fundamental code change, Airflow Improvement Proposal (AIP) is needed.
In case of a new dependency, check compliance with the ASF 3rd Party License Policy.
In case of backwards incompatible changes please leave a note in UPDATING.md.
Read the Pull Request Guidelines for more information.

[ad-m]

Dear Sir Breguła,

Have you considered sphinxcontrib-redoc package? This extension does not require a stub page, because it hooks on html-collect-pages too (see https://github.com/sphinx-contrib/redoc/blob/master/sphinxcontrib/redoc.py#L155 ).

With great love and adoration,
Adam Dobrawy

[potiuk]

I like the idea, but I do not like having the huge js redoc file committed. Can we instead download it on demand from redoc github or install it using some standard mechanisms ? We can cache it locally instead after downloading so it will only need to be downloaded once (until we change the version). I think that's much better approach.

[mik-laj]

@ad-m This will generate a file, but Sphinx won't be aware of it, so you won't be able to reference it in any way.

/opt/airflowairflow/docs/index.rst:104: WARNING: toctree contains reference to nonexisting document 'redoc'

This is a known problem for many plugins e.g. sphinx-autoapi also generates rst files on the local disk so that Sphinx can read them.

How do I update this PS to use this plugin but it is not perfect. It doesn't allow you to easily specify the version of redoc library and copy JS code to output files.

[mik-laj]

I updated the PR: He used this plugin and added the JS library download on demand (with cache).
Demo: https://valuable-carpenter.surge.sh/

[potiuk]

LGTM now!