fenics team mailing list archive

[Johan Hake <johan.hake@xxxxxxxxx>]

On Monday 22 March 2010 13:15:31 Anders Logg wrote:
> 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... ;-)

Ok, slowly seeing your point :)

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

Getting there!

Johan

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