Kari Argillander
369da70f2a
* format: Strip trailing whitespaces
We want to get rid of trailing whitespaces completly as they make just git
noice. Much better to start using automated tools to get rid of them once and
not getting them back again. This way git history will be cleaner and review
easier.
Commit was generated with:
pre-commit run --all-files trailing-whitespace
* format: Files should have exactly one new line end of them
It is good practice that every file has one new line. It is not now days so
mandatory but it also is not nice if file has lot of newlines end of it. We will
use pre-commit which takes automatically care about this so let's fix all.
Commit was generated with:
pre-commit run --all-files end-of-file-fixer
* format: Convert tabs to spaces
Project mostly use spaces over tabs. When mixing tabs and spaces this usually
makes formatting issues and also when changing those in commits it will make lot
of git noise. We will force spaces most of the time and use pre-commit to fix.
Commit was generated with:
pre-commit run --all-files remove-tabs
---------
Co-authored-by: Kari Argillander <kari.argillander@fidelix.com>
57 lines
2.5 KiB
Plaintext
57 lines
2.5 KiB
Plaintext
To build the Doxygen documentation for the BACnet Stack:
|
|
- Install doxygen as described at
|
|
http://www.stack.nl/~dimitri/doxygen/install.html
|
|
- If you want to generate call graphs (recommended - very nice! - but takes
|
|
signficantly longer to build the documents), you must also have
|
|
graphviz installed.
|
|
- To build from the command line, just enter
|
|
doxygen BACnet-stack.doxyfile
|
|
- Output is built in doc/output/html, and there is a convenient
|
|
starting point at doc/output/BAC_stack.html.
|
|
- If you use Eclipse,
|
|
- install the eClox plugin to support doxygen within Eclipse
|
|
- Build the documents by right clicking on BACnet-stack.doxyfile,
|
|
and selecting "@ Build Documentation"
|
|
- Feel free to tweak the doxygen output to your tastes, interests, and
|
|
choice of output formats.
|
|
- The Latex output could be converted into a PDF (see doxygen manual,
|
|
and google for your issues).
|
|
- I have tried the PDF, man, and RTF outputs and not liked the results
|
|
for any of them (500+ pages). I recommend the HTML output, as it is
|
|
well organized and has an obvious flow, both of which the others lack.
|
|
|
|
The doxygen output is not checked into this project because it consists of
|
|
over 5,000 little files (for HTML with call graphs), and it is easily
|
|
regenerated.
|
|
|
|
For speed, the function call graphs are not enabled in the SVN version
|
|
of the doxyfile. To enable them, edit BACnet-stack.doxyfile (with a
|
|
text editor or with GUI-based editors in Eclipse or using the
|
|
doxywizard application) and change
|
|
HAVE_DOT = YES
|
|
CALLER_GRAPH = YES
|
|
|
|
|
|
Following the doxygen website's lead, I found the D-Bus project to be a good
|
|
example of the sort of documentation we needed to have here.
|
|
http://dbus.freedesktop.org/doc/dbus/api/html/index.html
|
|
|
|
|
|
Output Formats:
|
|
The default output is HTML, which works well and looks good, but as mentioned,
|
|
consists of 5000 files.
|
|
The compiled help format (*.chm) also looks pretty good, and is packed into a
|
|
single file. Just a big, single file.
|
|
|
|
I tried the latex-to-pdf route, but did not like the output (far too much
|
|
whitespace, like a function per page, ~600 pages, not usefully organized).
|
|
Ditto for RTF and man output.
|
|
|
|
I could not find a linux-based compiled help compiler, so I resorted to using
|
|
Microsoft's. They seem to be pushing some later generation tools, and
|
|
maybe someone knows if that's a good thing, but I opted for their now
|
|
fairly old HTML Help Workshop, version 4.74.
|
|
Doxygen nicely arranges the html input, so pretty much all you have to do
|
|
is point HTML Help Workshop at BACnet-stack\doc\output\html\index.hhp and
|
|
let the compiler run.
|