projects / ceph.git / blame
| Commit | Line | Data |
|---|---|---|
| 7c673cae FG |
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 |