ceph/src/boost/libs/test/doc/README.md

   1 This folder contains the documentation for the Boost.Test library.
   2 Any contribution or submission to the library should be accompanied by the corresponding documentation.
   3
   4 The format of the documentation uses [http://www.boost.org/tools/quickbook/index.html Quickbook].
   5
   6 How to build the documentation
   7 ==============================
   8
   9 In order to generate the documentation, the following is needed:
  10
  11 * Docbook
  12 * Doxygen
  13 * xsltproc
  14
  15 Doxygen
  16 -------
  17 Part of the documentation needs [Doxygen](http://www.doxygen.org). `doxygen` should be accessible from the ``PATH``.
  18
  19 Docbook
  20 -------
  21 Quickbook needs Docbook (XSL and XML) to be installed. Download and untar the docbook archives:
  22
  23 * Docbook XSL that can be found here: http://sourceforge.net/projects/docbook/files/docbook-xsl/
  24 * Docbook DTD that can be found here: http://www.docbook.org/schemas/
  25
  26 The directories `$docbook_xsl_directory` and `$docbook_dtd_directory`, respectively, will refer to the location
  27 of the deflated archive.
  28
  29 Download xsltproc
  30 -----------------
  31 This program is needed by Docbook, in order to be able to transform XMLs into HTMLs.
  32 `xsltproc` should be accessible from the ``PATH``.
  33
  34 Construct bjam
  35 --------------
  36
  37 Simply by typing in a console at the root of the Boost repository:
  38
  39 ```
  40 > ./bootstrap.[sh|bat]
  41 ```
  42
  43 Build the documentation
  44 -----------------------
  45
  46 Running the following commands will construct the documentation with `bjam` and
  47 all the needed dependencies:
  48
  49 ````
  50 > cd $boost_root/libs/test/doc
  51 > ../../../b2 -sDOCBOOK_XSL_DIR=$docbook_xsl_directory -sDOCBOOK_DTD_DIR=$docbook_dtd_directory
  52 ```
  53
  54 It is possible to run directly
  55 ```
  56 > ../../../b2
  57 ```
  58
  59 but this results in a download from the Internet of the Docbook XLS and DTD, which is much slower.
  60
  61 Recommendations
  62 ===============
  63
  64 - Documentation is part of the "definition of done". A feature does not exist until it is implemented, tested, documented and reviewed.
  65 - It is highly recommended that each of your pull request comes with an updated documentation. Not doing so put this work on the shoulders
  66   of the maintainers and as a result, it would be likely that the pull request is not addressed in a timely manner.
  67 - Please also update the changelog for referencing your contribution
  68 - Every file should come with a copyright notice on the very beginning