Airflow Docs - RTD vs Apache Site

[Kaxil Naik <ka...@gmail.com>]

Hi all,

Continuing discussion from Slack, many users have had the problem with
looking at a wrong version of the documentation. Currently, our docs on
apache.airflow.org don't properly state version. Although we have specified
this info on our Github readme and confluence, there has still been lots of
confusion among the new users who try to google for the docs and are
pointed to airflow.apache.org site which doesn't have version info.

The problem currently with a.a.o site is it needs to be manually built and
only has stable version docs. We can do 2 things if we don't want to
redirect a.a.o with RTD: (1) Maintain History on our static a.a.o site (2)
Point a.a.o site to RTD docs, so a.a.o would point to RTD docs i.e. add the
domain to RTD site

Ash has also suggested another approach:

> Apache Infra run a jenkins instance (or other build bot type things) that
> we might be able to use for autobuilding docs if we want?



Let's discuss this and decide on a single-approach that is user-friendly.

NB: I will be busy for a month, hence won't be able to actively help with
this, so please feel free to contribute/commit after an approach is
finalized.

Regards,
Kaxil

Re: Airflow Docs - RTD vs Apache Site

[Maxime Beauchemin <ma...@gmail.com>]

A few thoughts:
* we absolutely have to serve a project site off of `airflow.apache.org`,
that's an ASF requirement
* maybe `airflow.apache.org` could be setup as a proxy to
readthedocs-latest (?) [I'm on vacation and have very slow internet, so
didn't research whether that's a documented use-case, we could also ask
Apache-INFRA about it]
* we could (and really should) split the project site and the documentation
as two different sites, that assumes we'd have someone drive creating a
proper, professional looking project site that would link out to the docs
on "Read the Docs". Creating a project site is not that much work and could
be a rewarding project for someone in the community. Many static site
builder framework work off of "markdown" format, and it's possible to
auto-convert RST (the format we use) to markdown automatically. I'd be nice
to take fresh screenshots of the UI while at it!

Max


Max

On Wed, Oct 3, 2018 at 6:13 AM Kaxil Naik <ka...@gmail.com> wrote:

> Hi all,
>
> Continuing discussion from Slack, many users have had the problem with
> looking at a wrong version of the documentation. Currently, our docs on
> apache.airflow.org don't properly state version. Although we have
> specified
> this info on our Github readme and confluence, there has still been lots of
> confusion among the new users who try to google for the docs and are
> pointed to airflow.apache.org site which doesn't have version info.
>
> The problem currently with a.a.o site is it needs to be manually built and
> only has stable version docs. We can do 2 things if we don't want to
> redirect a.a.o with RTD: (1) Maintain History on our static a.a.o site (2)
> Point a.a.o site to RTD docs, so a.a.o would point to RTD docs i.e. add the
> domain to RTD site
>
> Ash has also suggested another approach:
>
> > Apache Infra run a jenkins instance (or other build bot type things) that
> > we might be able to use for autobuilding docs if we want?
>
>
>
> Let's discuss this and decide on a single-approach that is user-friendly.
>
> NB: I will be busy for a month, hence won't be able to actively help with
> this, so please feel free to contribute/commit after an approach is
> finalized.
>
> Regards,
> Kaxil
>