Making more of Doxygen

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
4 messages Options
Reply | Threaded
Open this post in threaded view
|

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

Reply | Threaded
Open this post in threaded view
|

Re: Making more of Doxygen

John W. Eaton
Administrator
On 10/20/2017 11:11 AM, siko1056 wrote:
> 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

This change seems good to me.

> In addition to that tree view, I want to include some "developer pages"
> explaining some C++ internals I have figured out so far.

OK.

> 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? ;-) ).
Nope, but the syntax used by outline mode is kind of like markdown, I guess.

> Any objections?

It seems OK to me.  If no one else objects, I propose the attached
changeset to rename README and etc/HACKING.  I'll leave it to you to
actually make the files use markdown syntax correctly.

jwe

diffs.txt (3K) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: Making more of Doxygen

siko1056
John W. Eaton wrote
> It seems OK to me.  If no one else objects, I propose the attached
> changeset to rename README and etc/HACKING.  I'll leave it to you to
> actually make the files use markdown syntax correctly.

Thank you for the patch jwe.  I applied it [1] alongside with my other
suggestions [2].

Kai.

[1]: https://hg.savannah.gnu.org/hgweb/octave/rev/312c00dd723a
[2]: https://hg.savannah.gnu.org/hgweb/octave/rev/7ff6daa6b558



--
Sent from: http://octave.1599824.n4.nabble.com/Octave-Maintainers-f1638794.html

Reply | Threaded
Open this post in threaded view
|

Re: Making more of Doxygen

siko1056
Some update about the definition of builtin functions by marcos.  A preview
is available here [1].  Did I get the situation right? (I am still learning
a lot while writing ;-) )

Best,
Kai

[1]: https://octave.space/doxygen/dev/Macros.html



--
Sent from: http://octave.1599824.n4.nabble.com/Octave-Maintainers-f1638794.html