Hi list,
as some of you probably noticed, I've recently fixed a couple of minor documentation issues as well as upgraded the doxygen configuration files to the 1.8.1 version. At the same time, I also took the liberty to removed the 800px width limit of the <body>, and rather limited the paragraph widths.
Those are just minor tweaks, but I'd like to go much further by restructuring the documentation. I think this is necessary to be able to properly document the recently added new modules, and future modules as well. The recent doxygen versions offer many novel features to do so. Also, the current generated documentation contains many confuse pages that sounds useless to me.
So regarding the second point, I propose the following:
- remove the "related pages" page
- remove the "namespaces" page
- remove the "files" page
- remove the "class hierarchy" and "class members" pages, and keep only the "class list"
(Eigen's inheritance mechanisms are too complex to be understood by any documentation tool, so the presented hierarchy is meaningless)
Too ease the navigation trough the documentation I also propose to enable the "tree view" and the "search engine".
I also propose to automatically generate a table of content from the header tags (<h1>, <h2>) of the current page, and to put it within the side-bar containing the tree-view (I have proof of concept code for that).
Now regarding the organisation of the documentation itself, I propose to introduce the notion of "chapters" representing a group of coherent modules. Currently I imagine the 4 following chapters:
* Dense matrix and array manipulation
* Dense linear problems and decompositions
* Sparse linear algebra
* Geometry
but maybe there is a better granularity.
Then, we also have the notion of "user manual" (i.e., the current tutorial pages, and basically all .dox pages), and "reference manual" (i.e., the automatically generated pages from the source code). My dilema, is whether to split each chapter into a user and reference manuals (CoM for Chapters of Manuals), or rather have a big user and a big reference manuals that are themselves organized into chapters (MoC for Manuals of Chapters). To better see how that would work in practice I started to experiment with doxygen and came up with four proof-of-concept variants, but I will only discuss the 2, 3, and 4 ones. Please do not pay attention to the visual bugs, and also only a few pages/modules/classes are properly sorted, they are only a proof-of-concepts!
This one implement a CoM variant using the custom xml layout configuration file of doxygen. It also includes a flat list of the modules. The main advantage of using this xml layout file to structure pages and modules is that it permits to use shorter names in the tree-view.
This variant overcome the limitation of the previous one by using the \defgroup \ingroup mechanism of doxygen, not only for modules, but also for the manual pages. For comparison, look at this page:
Here the main drawback is that the documentation pages are doxygen's modules, and so we cannot automatically produce a list of all Eigen's modules.
A general drawback of the CoM approach is that the actual user documentation pages are deeply nested in the hierarchy:
Eigen > Chapters > Chapter name > User Manual > Actual Page
Perhaps, we could tweak doxygen to remove the root (i.e., "Eigen"), but that still 4 levels.
This last variant implement a MoC approach using for the user manual the layout xml file, and for the reference part the \defgroup and \ingroup mechanism. By avoiding the User Manual/Reference duplications, this approach removes one level of nesting. To compensate for the fact that User Manual and Reference are not tightly coupled, I added cross references. See for instance:
http://eigen.tuxfamily.org/doc_test/4/TutorialMatrixClass.html (there is a -> Reference in the tree view).
Before going further I'd like to have your opinion on all of this, yes I know that's a lot of information...
cheers,
Gaël.