Documentation With Help of Sphinx and Readthedocs

Sphinx is a tool that makes it easy to create intelligent and beautiful documentation, written by Georg Brandl and licensed under the BSD license. I was trying to help the Aura Project with some documentation . When it comes to gh-pages branch I find difficult to push, merge upstreams. I just was browsing some of the repos in github. From the Imagine I came to know about http://readthedocs.org/ which works with the help of sphinx project. We just want to create a doc folder and create the .rst files of the format http://sphinx.pocoo.org/rest.html and place in our repo and point it in http://readthedocs.org/. I feel its so easy to do, for people can just clone the docs repo and make the necessary changes in the .rst files and give a pull request than the gh-pages. Some times the gh-pages waste a huge amount of time with some unexpected errors :( . So I thought of trying the readthedocs. From the getting started page of readthedocs I went and installed sphinx . It was easy for me to run from synaptic package manager. Installed and run the command $ sphinx-quickstart . It asks a few questions I am keeping the gist over here Running $ make html , we get the html in the _build/html folder. We can just browse through it , make the necessary changes in the .rst files run and run until we love. No commits , no push and pull and check the errors in gh-pages as we did. As the html is generated we can host either directly in gh-pages branch of github.com or we can just push the .rst files and utilize the http://readthedocs.org/ I have asked my friends at http://auraphp.github.com for their suggestion about this. We are having a search coming , code high lighting etc. Sphinx is not new for me, but I never tried to use it until now. I have been seeing the name over the www.doctrine-project.org and some other. I hope this is one of the best tool to utilize for documentation of any projects . I welcome your thoughts :–)

documentation, readthedocs, sphinx