| | 1 | = Links To Examples Of Best Practice For C++ 11/14 Boost Libraries = |
| | 2 | |
| | 3 | ''originally written by [http://www.nedprod.com/ Niall Douglas] May 2015'' |
| | 4 | |
| | 5 | As part of preparing my [http://cppnow.org/ C++ Now] 2015 presentation "[https://docs.google.com/presentation/d/1badtN7A4lMzDl5i098SHKvlWsQY-tsVcutpq_UlRmFI/pub?start=false&loop=false&delayms=3000 A review of C++ 11/14 only Boost libraries]" I examined ten C++ 11/14 mandatory libraries heading towards Boost. This wiki provides a shortlist of suggested best practices which Boost library authors may find useful when developing their own Boost libraries. To a large extent, this shortlist is mainly about achieving best practice in C++ 11/14 libraries of any kind and should be useful to anyone so interested. |
| | 6 | |
| | 7 | [[PageOutline]] |
| | 8 | |
| | 9 | == 1. Strongly consider using git and [https://github.com/ GitHub] to host a copy of your library and its documentation == |
| | 10 | |
| | 11 | All the Boost libraries are on github, and all the free tooling exampled below integrates easily with github. Choosing github 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. |
| | 12 | |
| | 13 | 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''. |
| | 14 | |
| | 15 | This is the script which generates the documentation for [http://boostgsoc13.github.io/boost.afio/ 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. |
| | 16 | |
| | 17 | {{{ |
| | 18 | cd boost-local |
| | 19 | rm -rf libs/afio/doc/doxy/doxygen_output/html |
| | 20 | mkdir -p libs/afio/doc/doxy/doxygen_output/html |
| | 21 | cd doc |
| | 22 | ../b2 -a ../libs/afio/doc |
| | 23 | cd ../.. |
| | 24 | if [ ! -e publish ]; then |
| | 25 | git clone -b gh-pages git@github.com:BoostGSoC13/boost.afio.git publish |
| | 26 | fi |
| | 27 | cd publish |
| | 28 | git reset --hard b1414e11be50ff81124e2e1583f1bbb734ad9ead |
| | 29 | cd .. |
| | 30 | rm -rf publish/* |
| | 31 | mkdir -p publish/doc/html |
| | 32 | cp -a boost-local/doc/html/afio* publish/doc/html/ |
| | 33 | cp -a doc/src publish/doc/ |
| | 34 | cp -a doc/src/images/boost.png publish/ |
| | 35 | cp -af boost-local/doc/src publish/doc/ |
| | 36 | mkdir -p publish/libs/afio/doc |
| | 37 | cp -a doc/* publish/libs/afio/doc/ |
| | 38 | cd boost-local/libs/afio/doc/doxy |
| | 39 | doxygen |
| | 40 | cd ../../../../../publish |
| | 41 | cp -a ../boost-local/libs/afio/doc/doxy/doxygen_output/html . |
| | 42 | cp -a ../Readme.md . |
| | 43 | cp -a ../Readme.md Readme.html |
| | 44 | echo '<html><head><title>Boost.AFIO documentation</title><meta http-equiv="refresh" content="300"/><body> |
| | 45 | <h1>Boost.AFIO documentation</h1> |
| | 46 | <p><a href="doc/html/afio.html">BoostBook format documentation</a></p> |
| | 47 | <p><a href="html/index.html">Doxygen format documentation</a></p> |
| | 48 | <p><a href="afio-stable.tar.bz2">Ready to go stable AFIO distribution with all git submodules (from master branch)</a></p> |
| | 49 | <p></p>' > index.html |
| | 50 | cat Readme.md | tail -n +4 >> index.html |
| | 51 | echo ' |
| | 52 | </body></html>' >> index.html |
| | 53 | git add . |
| | 54 | git commit -a -m 'SHA stamp by Jenkins as building correctly' || true |
| | 55 | git push -f |
| | 56 | }}} |
| | 57 | |
| | 58 | 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. |
| | 59 | |
| | 60 | Other examples of libraries which use github for their documentation: |
| | 61 | |
| | 62 | * https://olk.github.io/libs/fiber/doc/html/ |
| | 63 | * https://boostgsoc13.github.io/boost.afio/ |
| | 64 | * https://krzysztof-jusiak.github.io/di/boost/libs/di/doc/html/ |
| | 65 | * https://boostgsoc14.github.io/boost.http/ |
