aurora-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Sebastien Goasguen <run...@gmail.com>
Subject Re: Docs
Date Tue, 18 Feb 2014 21:05:18 GMT

On Feb 18, 2014, at 9:42 AM, Jake Farrell <jfarrell@apache.org> wrote:

> 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.
> 

My experience has been as committer on cloudstack and libcloud. IMHO the ASF content management
system is a bit of a pain and still svn based.
So while I tend to agree that the docs should be local to the site itself, readthedocs.org
(RTD) provides some very interesting features, like github integration.
This helps in getting new folks to contribute documentation because a pull request is just
a click away.

To your concerns, RTD does provide canonical URLs that help with SEO.
Finally, the docs remain part of the same code repo and the doc site gets updated automatically
on each commit. So there is nothing getting out of date. You edit the .rst files, and it gets
published as soon as the github mirror sees the new commit.

I personally think it's cool and looks good, but that's you guys's call.

-sebastien

> -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
>> 


Mime
View raw message