Making more of Doxygen

[siko1056]

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