fenics team mailing list archive

[Anders Logg <logg@xxxxxxxxx>]

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.

This seems to fit very well with our discussion regarding whether or
not to put the documentation as part of the code.

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.

--
Anders

Attachment: signature.asc
Description: Digital signature