Re: [eigen] New Developer Documentation wiki page

[Benoit Jacob <jacob.benoit.1@xxxxxxxxx>]

2010/6/30 Manoj Rajagopalan <rmanoj@xxxxxxxxx>:
>
> "version to version": are you referring to 2.x -> 3.x (major)  or  say minor
> like 3.0 -> 3.1

Even just between 3.0 and 3.1, internal things are going to change.

>
> Will stuff like the class hierarchy change significantly throughout 3.x? In
> that case it could reside on the wiki also.

But if it resides on the wiki, we'll have to specify everywhere which
version of Eigen we're referring to. It's going to be a pain, and
inevitably the updating to new versions is going to worsen the
documentation of older versions.

We have none of these problems if instead we store the documentation
in hg, as it will then be branched along with the rest of stuff in hg.

> Most of the doxygen documentation
> now describes code usage but there is no description of design and rationale.

That's true. Let's fix that!

> Are you planning to include this too with the release documentation as a
> separate Developer page?

Yes!

> This page doesn't seem to exist now. If someone can
> suggest an outline (or point me to a previous email that contains one), I can
> nucleate this, populate it with what I put on the wiki page and then submit a
> patch.

Let's start with topic-specific pages. Just like we already have some
topic-specific pages in doxygen, prefixed Topic..., we could have
developer-oriented topic-specific pages there. So my mail on the class
hierarchy could become doc/TopicClassHierarchy.dox, Gael's becomes
doc/TopicExpressionNesting.dox, etc...

It will be time to write more generalist design documents later.

>
>   I generated the figures using GraphViz and we can check these files into
> Mercurial. The "make doc" can run graphviz. The drawback of this approach is
> that the user's system should have GraphViz installed. Doxygen also uses
> GraphViz but if it isn't present, it silently reverts to not running
> it. "make doc" on the other hand might fail so we must include a
> configure-time check for cmake.

OK, all that sounds interesting. When graphviz isn't present, rather
than erroring out, we can just continue with a warning message and
generate documentation with these images missing.

If you agree to move your pages to doxygen, check in the graphviz
files too, and we can then take care of the CMake side of things.

Benoit

>
> thanks,
> Manoj
>
>
>
> On Wednesday 30 June 2010 03:21:45 pm Benoit Jacob wrote:
>> Hi,
>>
>> Great initiative, two comments:
>>  - this is really something that needs to go into doxygen, for a few
>> reasons, the biggest reason being that such internal things can vary
>> from version to version, and the doxygen docs are specific to a given
>> revision of eigen, while the wiki isn't. So having this in doxygen is
>> much more long-term sustainable.
>>  - for the graphs, we need something better than storing PNGs, for
>> example I wanted to add "direct access case" in the Matrix column and
>> I couldn't. I don't know what to use. It might be that doxygen allows
>> us to do arbitrary graphs. I'd look at that first... A second choice
>> would be inline HTML: I don't know, but HTML might allow to do this
>> easily (without using HTML5 canvas ;-) ) a third choice would be
>> inline LaTeX but the result is a bitmap.
>>
>> Benoit
>>
>> 2010/6/30 Manoj Rajagopalan <rmanoj@xxxxxxxxx>:
>> > Hi eigen developers,
>> >
>> >  Based on detailed replies from Gael and Benoit, I've created a new
>> > developer documentation wiki page. The page itself is at:
>> >
>> > http://eigen.tuxfamily.org/index.php?title=Eigen3_Developer_Documentation
>> >
>> >  and a link to it is available from the Developer's corner page under the
>> > section "Eigen hacking":
>> >
>> > http://eigen.tuxfamily.org/index.php?title=Developer%27s_Corner#Developer
>> >_Documentation
>> >
>> >   Right now I thought it would be a good idea to save the explanations
>> > the developers provide and to organize it later on as and when more
>> > information accumulates.
>> >
>> > Thanks,
>> > Manoj
>
>
>
>