[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Making more of Doxygen
From: |
siko1056 |
Subject: |
Making more of Doxygen |
Date: |
Fri, 20 Oct 2017 08:11:43 -0700 (MST) |
Looking jealously at the Doxygen documentation of the Eigen [1] matrix
library, I figured out, that two options have to be changed to get that (in
my opinion) nice Doxygen tree view for Octave as well and for free, see [2].
These options are [3]:
DISABLE_INDEX = YES
GENERATE_TREEVIEW = YES
In addition to that tree view, I want to include some "developer pages"
explaining some C++ internals I have figured out so far. Those pages are
displayed automatically at an obvious position (see [2] for a proof of
concept). I really think Doxygen is the best place for this attempt:
+ It supports Markdown (thus syntax highlighting and formatting)
+ It makes heavy use of auto-linking, even in source code examples (in
Texinfo linking is very cumbersome, maybe a reason for those few
internal-links in the manual)
+ It is shipped directly with the source code (unlike the wiki, that has
nice syntax highlighting, but the auto-linking problem is also present
there)
+ Inclusion of existing source-code explaining documents "README" and
"etc/HACKING"
A "problem" (to me it is less a problem, but more a change, that I want to
discuss beforehand) for the last item is:
- "README" and "etc/HACKING" have to be Markdown files, e.g. "README.md"
and "etc/HACKING.md", that is often seen in other projects as well. Those
who know Markdown, this leaves the documents in a very readable state
without any processing. Unlike Texinfo, or LaTeX files, that really need
processing before being able to read them. The Doxygen landing page [5] is
actually this barely modified "README" file (maybe jwe knew Markdown before
it became mainstream? ;-) ).
Any objections?
Kai.
[1]: https://eigen.tuxfamily.org/dox/index.html
[2]:
https://octave.space/doxygen/dev/md_doc_doxyhtml_pages_matrix-overview.html
[3]: http://www.stack.nl/~dimitri/doxygen/manual/config.html#config_html
[4]: http://octave.org/doxygen/4.2/
[5]: https://octave.space/doxygen/dev/index.html
--
Sent from: http://octave.1599824.n4.nabble.com/Octave-Maintainers-f1638794.html
- Making more of Doxygen,
siko1056 <=