Thursday 7th May 2015 4.05pm

Thu, May 7, 2015

As part of publicising my C++ Now 2015 talk next week, here is part 1 of 20 from its accompanying Handbook of Examples of Best Practice for C++ ¹¹⁄₁₄ (Boost) libraries:

1. CONVENIENCE: Strongly consider using git and GitHub to host a copy of your library and its documentation

There are many source code control systems, with subversion and CVS being the two most recently popular of yesteryear. Probably the current most popular source code control system is Git, and despite its (Mingw i.e. non-native) port on Microsoft Windows being a bit flaky, it is very useful once mastered.

There is less widespread consensus about where to host your git repositories, with the most popular by far being github which is a proprietary service run by a profit making company. Nevertheless, one often hears strong arguments in favour of gitlab, bitbucket and many other alternatives.

All the Boost libraries are on github, as are all the libraries I reviewed. The huge advantage of github over all others is that the free tooling exampled below integrates easily with github. Choosing github therefore makes your life much easier. Note that as git is a distributed source code control system, you can keep a canonical master copy anywhere and write a script which autorefreshes the github copy, thus triggering any of the free tooling you have integrated there. In other words, don't necessarily place all your eggs in the github basket, and consider making github simply a medium for conveniently triggering the free tooling.

Github also provides free website hosting for HTML. Have a script automatically generate documentation and commit it to the gh-pages branch in your normal repo. This should present a copy of your HTML at http:// username.github.io/repository.

This is the script which generates the documentation for proposed Boost.AFIO, and indeed you can see the exact output generated by this script at http://boostgsoc13.github.io/boost.afio/. You may find it useful.

cd boost-local
rm -rf libs/afio/doc/doxy/doxygen_output/html
mkdir -p libs/afio/doc/doxy/doxygen_output/html
cd doc
../b2 -a ../libs/afio/doc
cd ../..
if [ ! -e publish ]; then
git clone -b gh-pages git@github.com:BoostGSoC13/boost.afio.git publish
fi
cd publish
git reset –hard b1414e11be50ff81124e2e1583f1bbb734ad9ead
cd ..
rm -rf publish/
mkdir -p publish/doc/html
cp -a boost-local/doc/html/afio publish/doc/html/
cp -a doc/src publish/doc/
cp -a doc/src/images/boost.png publish/
cp -af boost-local/doc/src publish/doc/
mkdir -p publish/libs/afio/doc
cp -a doc/* publish/libs/afio/doc/
cd boost-local/libs/afio/doc/doxy
doxygen
cd ../../../../../publish
cp -a ../boost-local/libs/afio/doc/doxy/doxygen_output/html .
cp -a ../Readme.md .
cp -a ../Readme.md Readme.html
echo '<html><head><title>Boost.AFIO documentation</title><meta http-equiv="refresh" content="300"/><body>
<h1>Boost.AFIO documentation</h1>
<p><a href="doc/html/afio.html">BoostBook format documentation</a></p>
<p><a href="html/index.html">Doxygen format documentation</a></p>
<p><a href="afio-stable.tar.bz2">Ready to go stable AFIO distribution with all git submodules (from master branch)</a></p>
<p></p>' > index.html
cat Readme.md | tail -n +4 >> index.html
echo '
</body></html>' >> index.html
git add .
git commit -a -m 'SHA stamp by Jenkins as building correctly' || true
git push -f

Some may wonder what the hard git reset to a SHA is for. This prevents the gh-pages branch continuously growing in storage by breaking history for the branch, and therefore making git clone times grow excessively. As the branch is purely for HTML publishing, breaking history like this is safe.

Other examples of libraries which use github for their documentation:

* https://olk.github.io/libs/fiber/doc/html/
* https://boostgsoc13.github.io/boost.afio/
* https://krzysztof-jusiak.github.io/di/boost/libs/di/doc/html/
* https://boostgsoc14.github.io/boost.http/