Favoring Doxygen for documentation over independent wiki documentations


#21

Well, with hand-written documentation of course you can do more, but it’s lots of work. With doxygen you do nothing and you already get a full-featured comprehensive documentation, with HTML pages only one out of 12 (currently) options. For instance, it can also create a help file that is integrated for immediate lookup in eclipse or QT Creator. You don’t get what with a wiki. It can also produce a linear manual via LaTeX to create a PDF file from it, for those who prefer papers. And starting from this do-nothing approach, things can be customized and beautified to a certain extent, even including hand-written HTML code if needed. But it won’t necessarily be exactly the same as a hand-coded wiki page, unless you’d go even that far to modify the doxygen source or contact its developer to extent it (he’s ok, I had contact with him a couple of years ago and was quite open to include a suggestion).

What seems closest to your transclusion is doxygen’s \include{doc} special command:
https://www.doxygen.nl/manual/commands.html#cmdinclude
It allows to insert some documentation from one file in another place, and of course you can use that repeatedly and multiple places. That should be the same as the wiki’s transclusion; I wouldn’t do it though since it is additional work - like editing a wiki - and I personally prefer the documentation of types on another page anyway, like QT does it as well (as one of the documentation pages where I hang around lots).

For the git repo, sure, we can do that. I basically used the source from HDF5 1.12.0, edited two files there and created a doxygen configuration file. The layout with the side menu is the HTML output style option whether to generate a navigation panel or not (which is, like the two C++ websites, a matter of taste). There are more options, you’d need to explore which ones you like, and if users build their own documentation pages, they can use it up to their choice. The more effort is spent on the docu, the better it will become of course.

Would you want me to copy the entire hdf5 1.12 source in this demo repo or just those files that I modified?


#22

Just the files that you modified plus the Doxygen config file will do. I can make you a contributor or you can make a pull request against https://github.com/HDFGroup/doxygen-rm. Thanks, G.


#23

ok done. I also added a trivial makefile to ease running it under windows when it’s not in the path.


#24

Excellent. Thank you very much. I’ll try it and report back. I see there is hope for Fortran as well. :slightly_smiling_face:


#25

Following @werner’s example, I’ve mocked up the same examples as in MediaWiki. See H5F and H5L. I worked off the HDF5 development branch and the source file changes can be seen in H5F.c and H5L.c. The Doxygen transclusion and templating are rather primitive and brittle but might be good enough for the task at hand. G.


#26

Looks good! For classes and data structures, Doxygen produces a nice alphabetical listing. Unfortunately, not for functions. Such could probably be created semi-automatically as an extra doxygen page via a script.


#27

We’ve just begun the conversion in earnest. Progress can be tracked here. The underlying Bitbucket branch is this one. Comments welcome! G.