I have made two major changes to the documentation of my code samples in repo cmake-boost-test at Bitbucket. First, I use the Python tool "Sphinx" to author the documentation and second, I use Bitbucket to publish the documentation.
Initially I used a single README located in the root of the repo to contain the documentation. Such a README often suffices to contain the first version of any documentation. Another advantage is that Bitbucket automatically shows you the README of a repo when you visit the repo at bitbucket.org. This makes for a very nice welcome for visitors.
However, as I added new code and documentation, the single README started to become a bit unwieldy. So I decided to use Sphinx, a Python tool developed to write all kinds of documentation. From the Sphinx website
It was originally created for the new Python documentation, and it has excellent facilities for the documentation of Python projects, but C/C++ is already supported as well.
Sphinx uses reStructuredText as its markup language and allows multiple inputs, multiple output formats, extensive cross-referencing, code highlighting and much more. I had already used Sphinx to write user documentation and to document Python and Django apps so I new my way around.
Sphinx works by processing a set or reStructuredText documents that contain the information and create the documentation in one or more of its output formats. This brings me to the second major change, you can find the HTML-formatted documentation that Sphinx generates of cmake-boost-test at http://swinkels.bitbucket.org/cmake-boost-test To do so I make use of the functionality to publish a static website of Bitbucket._
There are several things I could / should do next. For example, I have not changed the README so as it stands it is more or less a duplicate of the documentation written using Sphinx. Furthermore, that documentation is not ready yet. The contents of the CMake file list would benefit from a better description, as would the current unit tests, etc. Also the update of the documentation at Bitbucket is a manual affair which could be automated. But for now I am quite content with the current setup.