fenics team mailing list archive

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

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?

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

> 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

> --
> Anders
>
> -----BEGIN PGP SIGNATURE-----
> Version: GnuPG v1.4.9 (GNU/Linux)
>
> iEYEARECAAYFAkundcIACgkQTuwUCDsYZdGbegCgkvje5skw8pkEHWWKRgW4CrFh
> zjMAn15eImocRibmFiLQExZkClQ8oTdg
> =p16A
> -----END PGP SIGNATURE-----
>
> _______________________________________________
> Mailing list: https://launchpad.net/~fenics
> Post to     : fenics@xxxxxxxxxxxxxxxxxxx
> Unsubscribe : https://launchpad.net/~fenics
> More help   : https://help.launchpad.net/ListHelp

Attachment: signature.asc
Description: OpenPGP digital signature