Re: [eigen] Re-structuring the documentation

[Gael Guennebaud <gael.guennebaud@xxxxxxxxx>]

I also don't have strong preference between 4 and 5. Since 5 was more
advanced, I continued with it, and came with:

http://eigen.tuxfamily.org/doc_test/5/

If we want to move to the variant #4 in the future, this won't be much work.

Now, all the relevant documentation files are included in the tree, I
removed the root node, automatically expand the current node, and
fixed some javascript bugs.

Now we can update the "overview" page, and work again on the content ;)


The changes are in the repo, and here is the commit that summarize all
the changes:

https://bitbucket.org/eigen/eigen/commits/ed2b9c0e8084/
changeset:   ed2b9c0e8084
user:        ggael
date:        2013-01-05 16:37:11
summary:     Big changes in Eigen documentation:
- Organize the documentation into "chapters".
  - Each chapter include many documentation pages, reference pages
organized as modules, and a quick reference page.
  - The "Chapters" tree is created using the defgroup/ingroup
mechanism, even for the documentation pages (i.e., .dox files for
which I added an \eigenManualPage macro that we can switch between
\page or \defgroup ).
  - Add a "General topics" entry for all pages that do not fit well in
the previous "chapters".
  - The highlevel struture is managed by a new eigendoxy_layout.xml file.
- remove the "index" and quite useless pages (namespace list, class
hierarchy, member list, file list, etc.)
- add the javascript search-engine.
- add the "treeview" panel.
- remove \tableofcontents (replace them by a custom \eigenAutoToc
macro to be able to easily re-enable if needed).
- add javascript to automatically generate a TOC from the h1/h2 tags
of the current page, and put the TOC in the left side panel.
- overload various javascript function generated by doxygen to:
  - remove the root of the treeview
  - remove links to section/subsection from the treeview
  - automatically expand the "Chapters" section
  - automatically expand the current section
  - adjust the height of the treeview to take into account the TOC
- always use the default .css file, eigendoxy.css now only includes
our modifications
- use Doxyfile to specify our logo
- remove cross references to unsupported modules (temporarily)
affected #:  49 files

cheers,
gael

On Fri, Jan 4, 2013 at 1:43 PM, Thomas Capricelli <orzel@xxxxxxxxxxxxxxx> wrote:
> Il 04/01/2013 11:21, Gael Guennebaud ha scritto:
>> Nevertheless, I made a last attempt that is in-between 3 and 4: it use
>> the grouping mechanism of 3, but a structure more like 4 where the "->
>> Reference" link has been replaced by the true reference block with
>> Modules and Classes:
>>
>> http://eigen.tuxfamily.org/doc_test/5/GettingStarted.html
>>
>> I also tweaked the javascript to enforce the "Chapters" section to be
>> expanded whatsoever. This is probably the most interesting thing about
>> this variant, and the same trick can be applied the #4 one to keep the
>> first level of the User Manual always visible.
>>
>> If you are only interested by the reference pages, then 4 remains better.
>
> The auto-expand is good indeed, keep it !
>
> Concerning the layout, i still kinda prefer the option 4, which makes it
> clear that there are a "User manual" part and a "reference" part. With
> option 5 it's less obvious.
>
> But it really is a "i find it slightly better". I'm perfectly happy with
> option 5 nonetheless.
>
> regards,
>
> --
> Thomas Capricelli <orzel@xxxxxxxxxxxxxxx>
> http://www.freehackers.org/thomas/
>
>
>