fenics team mailing list archive

[Anders Logg <logg@xxxxxxxxx>]

On Mon, Mar 22, 2010 at 03:08:32PM +0100, Kristian Oelgaard wrote:
>
>
> On 22 March 2010 14:50, Anders Logg <logg@xxxxxxxxx> wrote:
> >On Thu, Mar 18, 2010 at 09:22:24AM -0500, Andy Ray Terrel wrote:
> >>I've never heard of doconce.  Is there a link somewhere?  Just to
> >>throw this out there you might check out the way Numpy and Scipy does
> >>theirs (I believe with sphinx [0] which has that nice feature of
> >>publishing to pdf or html).  If there was some style guide set up and
> >>the key areas pointed out, it might be good to have a documentation
> >>marathon for FEniCS'10.
> >>
> >>[0] http://sphinx.pocoo.org/
> >
> >I looked a bit more on Sphinx, and it looks really good.
> >
> >The documentation for Sphinx states the following:
> >
> > The focus is on hand-written documentation, rather than
> > auto-generated API docs.
>
> So we will abandon Doxygen and similar tools? Sounds good to me, but
> I guess it will make it slightly more difficult to ensure that all
> functions are documented and not forgotten. But maybe there are
> tools for this?

I imagine we can write a script that checks for functions that need to
be documented. We could also have a script that checks that the
one-line compact comment in the code is the same as the summary/first
sentence in the hand-written documentation.

> >This seems to fit very well with our discussion regarding whether or
> >not to put the documentation as part of the code.
>
> So we only put short comments in the code like we do now, and then
> put documentation in sphinx source files.

That would be my suggestion. Let's hear what people think.

--
Anders


> >So Sphinx would be a tool we could use to produce good looking,
> >cross-referenced, indexed documentation from a set of simple input
> >files (in reST or doconce format), but we would not extract anything
> >from the code.
> >
> >With this approach, I wonder where the limitations are for documenting
> >the C++ interface. Are there any? If we don't use Doxygen, we would
> >just write the documentation in the same way as for the Python
> >interface.
> >
> >And I just thought of another reason for splitting the documentation
> >from the code which is that it makes it possible to separate write
> >access for the code and the documentation.
>
> Good point.
>
> Kristian
>
>

Attachment: signature.asc
Description: Digital signature