I'd like to revisit this, since we gain a lot by exposing our docs in more places (http://docs.cloudstack.apache.org/ is wonderful, we should replicate that). If this can indeed be automated, it seems like a huge win. I had not heard of pandoc before, it looks awesome!
*Sebastien* - a few questions for you, so we can learn from cloudstack: - What is the motivation behind cloudstack's docs being in a separate repository? - I noticed the cloudstack repo uses .md and cloudstack-docs uses .rst, any specific reasons for the difference? - Is the .md -> .rst a requirement, or just preferable? I'm not married to .md, just curious what's at play. -=Bill On Tue, Feb 18, 2014 at 1:05 PM, Sebastien Goasguen <run...@gmail.com>wrote: > > On Feb 18, 2014, at 9:42 AM, Jake Farrell <jfarr...@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 <d...@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 <run...@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 > >> > >
