1..
2    Copyright (C) 2018 Mikael Simberg
3
4    Distributed under the Boost Software License, Version 1.0. (See accompanying
5    file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
6
7.. _documentation:
8
9=============
10Documentation
11=============
12
13This documentation is built using |sphinx|_, and an automatically generated API
14reference using |doxygen|_ and |breathe|_.
15
16We always welcome suggestions on how to improve our documentation, as well as
17pull requests with corrections and additions.
18
19Building documentation
20======================
21
22Please see the :ref:`documentation prerequisites <documentation_prerequisites>`
23section for details on what you need in order to build the |hpx| documentation.
24Enable building of the documentation by setting ``HPX_WITH_DOCUMENTATION=ON``
25during |cmake|_ configuration. To build the documentation build the ``docs``
26target using your build tool.
27
28.. note::
29
30   If you add new source files to the Sphinx documentation you have to run
31   |cmake| again to have the files included in the build.
32
33
34Style guide
35===========
36
37The documentation is written using reStructuredText. These are the conventions
38used for formatting the documentation:
39
40* Use at most 80 characters per line.
41* Top-level headings use over- and underlines with ``=``.
42* Sub-headings use only underlines with characters in decreasing level of
43  importance: ``=``, ``-`` and ``.``.
44* Use sentence case in headings.
45* Refer to common terminology using ``:term:`Component```.
46* Indent content of directives (``.. directive::``) by three spaces.
47* For C++ code samples at the end of paragraphs, use ``::`` and indent the code
48  sample by 4 spaces.
49
50  * For other languages (or if you don't want a colon at the end of the
51    paragraph) use ``.. code-block:: language`` and indent by three spaces as
52    with other directives.
53* Use ``.. list-table::`` to wrap tables with a lot of text in cells.
54
55API documentation
56=================
57
58The source code is documented using |doxygen|_. If you add new API documentation
59either to existing or new source files, make sure that you add the documented
60source files to the ``doxygen_dependencies`` variable in
61``docs/CMakeLists.txt``.
62