In the last weeks I have been working on the project RiverNe3 commenting as much as possible because I was introducing many new programming concepts for me like Design Patterns and Java Concurrency.
Well, I chose Doxygen instead of Javadoc because it seems more complete and seems having more features…but anyhow, we can talk about in another post.
Once generated the documentation, I thought that anyone who wants to read the documentation doesn’t have to “build” its own documentation but the latter has to be always ready for who wants just take a look about what I did.
GitHub allows to have a web-page addressed to the repository in which it is hosts. So…why do not create only the html documentation and upload it as web site?
It’s pretty easy, because the idea behind is pretty easy: you just have to create a new branch named gh-pages and the most of the work is done.
The procedure I’m going to write has been taken from the very good guide written by richford on Put doxygen documentation on github using gh-pages.
In order to have a tidy repository on which you can go on working with different branches, the procedure is a bit tricky, but not very complicated.
Switch to the master
branch in the main folder:
and add the path on which the documentation is going to be generated to the .gitignore
file
and then commit the modify on the master
branch
Now, it’s time to go working on the repository of the documentation. First of all, move (create if not exist) into the directory of the documentation (in my case doc/html/
) and clean it removing each and every file already created
Clone your own repository inside that folder, that will create a new directory with the name of the repository. In this way, you can easily manage the branch of the web-page of the documentation without touching the branches of the development of the source code.
Then copy everything in the folder created by the git clone command in the documentation directory (doc/html/
in my case) and remove the directory
After having cloned the repo, create and switch the branch gh-pages
with the single command:
That branch is automatically recognized by GitHub as Web Page, so uploading the Doxygen documentation in html format allows you to have your on-line documentation.
But we need to follow some other steps, before having the documentation available on-line.
Remove the master branch from within the folder of the documentation (the repository just cloned)
and all the files and folders from the master branch, because cloning the remote repository you have just copied your repo inside a folder of your repo…is it clear? I hope so, not for me! 😀
Anyway you need to preserve only .git folder, for example
and the commit the changes
Now, come back to the main directory, and setup your doxygen.conf (if you don’t have already the doxygen.conf file, you can generate the default with doxygen -g doxygen.conf
command) to generate the documentation in the right directory. Just edit it setting the path of the variable OUTPUT_DIRECTORY.
So checkout the master branch and generate the Doxygen documentation
It’s time to push our documentation on the Word Wide Web!
Move into the documentation directory and checkout the gh-pages
branch
Add each and every file generated by Doxygen
commit and push the documentation!
Now, your documentation is on-line on the web-site http://username.github.io/repoName/, in my case:
http://sidereus3.github.io/RiverNe3/
And now…the most import is keeping the documentation updated! A suggested workflow would look something like
Enjoy!!! GWH!