fenics team mailing list archive

[Johan Hake <johan.hake@xxxxxxxxx>]

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]

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

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
>