fenics team mailing list archive

[Kristian Oelgaard <k.b.oelgaard@xxxxxxxxx>]

On 22 March 2010 15:16, Anders Logg <logg@xxxxxxxxx> wrote:
> 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.

Sure, I was just wondering if someone out there on the big Internet had already done this job for us.

> > >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.

OK.

Kristian

> --
> 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
>
>
>
> -----BEGIN PGP SIGNATURE-----
> Version: GnuPG v1.4.9 (GNU/Linux)
>
> iEYEARECAAYFAkune68ACgkQTuwUCDsYZdG2AACgioXxnxrq1eKeU6pPWOin8Yg6
> /yIAniukS2aro5GY1WxufNObgjC2zlBK
> =nHn8
> -----END PGP SIGNATURE-----

Attachment: signature.asc
Description: OpenPGP digital signature