On 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? That's the question really. In cloudstack we started with docbook and it has been a real pain because writing xml is a pain.... I write a lot in basic markdown and pandoc utility has been very good in format conversion. Plus .rst renders well on github so you don't loose that part. http://johnmacfarlane.net/pandoc/installing.html > * Can this handle translated docs as well? Long-term we may want that. Yes, this is sphinx and it has capability for it: http://sphinx-doc.org/latest/intl.html You just need to use transifex.net and then build the translated docs. I have not set it up yet. > * Can we automate the generation of these docs? The solution we were close > to going live with was a simple rake command. > There is a Makefile :) But if you decide to host it on readthedocs.org you can turn on a commit hook so that the docs get build automatically on each commit to the docs directory. The only downside is that you can do this based on the github repo not the main apache repo. that said it also gives you the ability to accept pull request directly from github (notice the 'edit on github' button on the top left of my prototype). > 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
