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