README.md
1Documentation
2=============
3
4Most readers love documentation, its creators hate it.
5
6Unfortunately, nobody can look inside your head and have the same ingenious
7thoughts as you do. To ensure your thoughts also reach the afterworld, please
8document your stuff reasonably!
9
10The documentation is split up in two parts: *static* and *dynamic* docs,
11
12
13Static Docs
14-----------
15
16Dedicated documentation files reside in the `doc/` directory, where this
17readme file lies in as well. You can find ideas, milestones, planning and
18workflow descriptions etc in here.
19
20A good entry point may be the file [doc/project_structure](/doc/project_structure.md).
21it roughly explains where to find what code in the project.
22
23If **you** made any relevant discoveries or gained insights that help others
24understand any part of the project:
25
26* Create a file and write down your thoughts
27* Ideally, use markdown syntax, alternatively plain text
28* Submit your contribution (pull request) so we can include it in the official
29 repository
30* This ensures newcomers can start developing easily
31
32
33Dynamic Docs
34------------
35
36This type of documentation is written inside code files:
37
38 - C++ methods and classes are documented in their header files
39 - Python methods and classes are documented via docstrings
40
41Due to potential documentation laziness,
42the above statements might be out-right fabrications.
43
44
45### Doc Generation
46
47Dynamic documentation can be auto-generated from source documentation using **doxygen**.
48
49after calling `./configure`, you can invoke
50
51 make doc
52
53to create doxygen html and LaTeX files.
54
55
56After creation, view them in a browser by
57
58 $BROWSER bin/doc/html/index.html
59
60or, if you want to create LaTeX documents, run
61
62 make -C bin/doc/latex/ pdf
63 $PDFVIEWER bin/doc/latex/refman.pdf
64