Mailing-List: contact dev-help@aurora.incubator.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@aurora.incubator.apache.org
MIME-Version: 1.0
Reply-To: jfarrell@apache.org
In-Reply-To: 
 <CA+40=G1F6jw2Z+k7nSHjDyWHnDkhSB+mmqY-3FuofYehRtYEkA@mail.gmail.com>
References: <68C7BB52-68A7-4222-8549-E9E7C57E0534@gmail.com>
	<CA+40=G1F6jw2Z+k7nSHjDyWHnDkhSB+mmqY-3FuofYehRtYEkA@mail.gmail.com>
Date: Tue, 18 Feb 2014 09:42:45 -0500
Message-ID: 
 <CANyrgveKUtVtxb4_G51Y2X+7wVg2W-ZUSBbjgbWDiX=ogeV8jQ@mail.gmail.com>
Subject: Re: Docs
From: Jake Farrell <jfarrell@apache.org>
To: dev@aurora.incubator.apache.org,
	"dave@ischool.berkeley.edu" <dave@ischool.berkeley.edu>
Content-Type: multipart/alternative; boundary=089e01493c0e0d88f604f2af49db

--089e01493c0e0d88f604f2af49db
Content-Type: text/plain; charset=ISO-8859-1

Based on what i've seen in other projects around the ASF I would say that
we should keep the docs on the core website and not external. This will
help the main websites seo and docs that are pushed externally tend to not
get updated as much as they are forgotten about.

-Jake


On Mon, Feb 17, 2014 at 3:04 PM, Dave Lester <dave@ischool.berkeley.edu>wrote:

> Sebastien,
>
> This is great, thank you!
>
> There were a few bugs in our existing tooling for rendering docs on the
> site which has prevented rendering the docs as-is (delayed on part;
> although JakeF offered to help). I am inclined to switch entirely to what
> you've contributed here seeing -- what do others think?
>
> A few questions this
>
> * Are folks ok with a switch from markdown to rst?
> * Can this handle translated docs as well? Long-term we may want that.
> * Can we automate the generation of these docs? The solution we were close
> to going live with was a simple rake command.
>
> Thanks again,
>
> Dave
>
> On Monday, February 17, 2014, sebgoa <runseb@gmail.com> wrote:
>
> > Hi,
> >
> > Since I was testing aurora today I noticed there was no documentation
> site
> > that I could see, other than the markdown files in the repo.
> >
> > So I went ahead and did a little prototype for you:
> >
> > http://apache-aurora-incubating.readthedocs.org/en/latest/index.html
> >
> > I am using this for CloudStack and it's also used for Apache libcloud.
> > It uses sphinx to organize docs, it's based on restructured text which is
> > fairly close to markdown.
> > It can be built on the fly thanks to a service hook on the github mirror
> > It's hosted by readthedocs.
> > It generates epub, pdf and can manage releases.
> >
> > You can see how I reorganize the tree at:
> >
> > https://github.com/runseb/incubator-aurora/tree/master/docs
> >
> > I took the existing markdown files and converted everything to .rst using
> > pandoc. There are a few gotchas here and there that need to be fixed.
> >
> > Let me know if that's something that would be of interest, I would be
> > happy to clean it up and organize the content to have a proper TOC and
> then
> > submit a patch.
> >
> > Cheers,
> >
> > -Sebastien
>

--089e01493c0e0d88f604f2af49db--