git.net

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: Airflow Docs - RTD vs Apache Site


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 <kaxilnaik@xxxxxxxxx> 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
>