It is always good to have an online documentation of a project. Everyone can refer to it on web. Developers can easily direct to any piece (class, function etc) of the documentation by using the respective link in their communication.
The documentation and the project together should be hosted at the same location. Having two piece solution, one for project and other for documentation result in a poor usability experience for developers and users. One URL to the project and everything (Issue tracker, Wiki, Revision control, Downloads and Documentation) lying there sounds great!
Google Code doesn’t provide explicit hosting for the documentation. Using the method described in this article completes the project hosting on Google Code by providing a way to serve HTML from it.
- QXmpp-HEAD: http://qxmpp.googlecode.com/svn/doc/HEAD/html/index.html
- QXmpp-0.2.0: http://qxmpp.googlecode.com/svn/tags/qxmpp-0.2.0/doc/html/index.html
The key idea behind this solution is that Subversion (svn) can render the HTML/CSS files if proper mime-type of the files have been set. In Google Code when you view the raw file, SVN will use its mime-type to render it accordingly.
- URL to view raw files under svn: http://qxmpp.googlecode.com/svn/
- URL of the documentation: http://qxmpp.googlecode.com/svn/doc/HEAD/html/index.html
The mime-type should be set correctly. In my case, doxygen generates following type of files:
- *.css = svn:mime-type=text/css
- *.html = svn:mime-type=text/html
- *.gif = svn:mime-type=image/gif
- *.png = svn:mime-type=image/png
The auto-props feature of SVN can be used to set the mime-types automatically. Once auto-props things are defined in the SVN client config file, the client will automatically set the mime-types.
You can see that the documentation files are stored under SVN. Therefore the documentation inherently gets version control. The documentation gets versioned the way source code is tagged/versioned. You can host documentation for all the versions of your project. For example the documentation of 0.2.0 release and the bleeding-edge SVN HEAD QXmpp-0.2.0 and QXmpp-HEAD.
Steps to serve documentation from Google Code Subversion:
- Generate the documentation locally.
- Assign the correct svn:mime-type as per the file extension. This step is not required if you are using auto-props feature of SVN.
- Check in the documentation files at the desired path.
- Load the path to documentation in your browser to see the outcome. The path should be like http://[project-name].googlecode.com/svn/[svn-path]
- Create a script and add an entry of it in the crontab/scheduler to automate it.
- Use auto-props
- Choose the path of doc outside of trunk to keep your ohloh stats clean and other developers happy.
- Update the documentation daily for the HEAD version.
I will conclude and mention that it is good to have a documentation. The documentation should be served from the project hosting site itself to have a one piece solution and better user experience. This method of serving documentation can be used until Google comes up with an explicit solution. The versioning of the documentation is automatically done. You get documentation of all the versions of your software.