mirror of
https://github.com/stargieg/bacnet-stack
synced 2025-10-19 23:25:23 +08:00
57 lines
2.6 KiB
Plaintext
57 lines
2.6 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.
|