fenics team mailing list archive

[Anders Logg <logg@xxxxxxxxx>]

On Mon, Mar 22, 2010 at 01:04:49PM -0700, Johan Hake wrote:
> On Monday 22 March 2010 12:17:51 Hans Petter Langtangen wrote:
> > Mon, 22 Mar Anders Logg wrote:
> > > > 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.
> >
> > Sphinx is a great tool, standardized and well supported, so if it can
> > be used for the C++ code, it's probably a very good choice for
> > FEniCS. The documentation and the source code are then separated, but
> > the documentation does not go into doc strings (which is the purpose
> > of preprocessing source code files).
>
> Shouldn't it be possible to add doc strings to a library based on some
> external reference documentation? Something like:
>
> for names in dolfin.__dict__:
>    dolfin.__dict__[name].__doc__ = documentation[name]

Everything should be possible with Python. :-) I like that idea rather
than needing to run a preprocessor.

> BTW: I have to admit that I am not too keen on having the documentation and
> source code on two different places, yet...

I think it makes a lot of sense, especially for Python where the
declaration and implementation is mixed up in the same file. Consider
for example the important documentation of the Expression class. It is
currently buried deep in site-packages/dolfin/function/expression.py
on lines 332-470, just below class ExpressionMetaClass and def
expression__call__(self, *args, **kwargs) btw... ;-)

Having the documentation spread out and buried deep across multiple
files makes it difficult to edit. For example, it would be difficult
to ask someone to go through the documentation and check
grammar/spelling.

--
Anders



> Johan
>
> > Hans Petter
> >
> > > > >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
> > >
> > > _______________________________________________
> > > Mailing list: https://launchpad.net/~fenics
> > > Post to     : fenics@xxxxxxxxxxxxxxxxxxx
> > > Unsubscribe : https://launchpad.net/~fenics
> > > More help   : https://help.launchpad.net/ListHelp
> >
> > _______________________________________________
> > 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: Digital signature