fenics team mailing list archive

[Anders Logg <logg@xxxxxxxxx>]

On Thu, Apr 29, 2010 at 03:12:31PM +0100, Garth N. Wells wrote:
>
>
> On 29/04/10 15:06, Anders Logg wrote:
> >On Thu, Apr 29, 2010 at 04:02:05PM +0200, Kristian Oelgaard wrote:
> >>
> >>
> >>On 29 April 2010 15:55, Garth N. Wells<gnw20@xxxxxxxxx>  wrote:
> >>>
> >>>
> >>>On 29/04/10 14:54, Kristian Oelgaard wrote:
> >>>>
> >>>>
> >>>>On 29 April 2010 15:44, Anders Logg<logg@xxxxxxxxx>  wrote:
> >>>>>
> >>>>>On Thu, Apr 29, 2010 at 03:43:09PM +0200, Kristian Oelgaard wrote:
> >>>>>>
> >>>>>>
> >>>>>>On 29 April 2010 15:15, Garth N. Wells<gnw20@xxxxxxxxx>  wrote:
> >>>>>>>
> >>>>>>>
> >>>>>>>On 28/04/10 17:26, Anders Logg wrote:
> >>>>>>>>
> >>>>>>>>On Wed, Apr 28, 2010 at 12:05:19PM +0200, Kristian Oelgaard wrote:
> >>>>>>>>>
> >>>>>>>>>
> >>>>>>>>>On 28 April 2010 11:59, Garth N. Wells<gnw20@xxxxxxxxx>    wrote:
> >>>>>>>>>>
> >>>>>>>>>>
> >>>>>>>>>>On 27/04/10 13:52, Kristian Oelgaard wrote:
> >>>>>>>>>>>
> >>>>>>>>>>>
> >>>>>>>>>>>On 27 April 2010 14:18, Anders Logg<logg@xxxxxxxxx>    wrote:
> >>>>>>>>>>>>
> >>>>>>>>>>>>Any ideas on how to keep the code in the documentation and the
> >>>>>>actual
> >>>>>>>>>>>>demos in sync? Should we have a script that copies all the source
> >>>>>>>>>>>>files? Or should we do the opposite: extract the demos from the
> >>>>>>>>>>>>documentation?
> >>>>>>>>>>>
> >>>>>>>>>>>Good question, initially I thought copying from DOLFIN to
> >>>>>>documentation
> >>>>>>>>>>>was the way to go, but on second thought the other way around
> >>>>>>might be
> >>>>>>>>>>>better.
> >>>>>>>>>>>The reason is that if the demos break, then they will be fixed
> >>>>>>in the
> >>>>>>>>>>>documentation which makes is more likely that the accompanying text
> >>>>>>>>>>>(and
> >>>>>>>>>>>code snippets) will also be corrected.
> >>>>>>>>>>>
> >>>>>>>>>>
> >>>>>>>>>>We'll usually have the source code for a demo broken into pieces
> >>>>>>in the
> >>>>>>>>>>documentation with an explanation for each part of the code
> >>>>>>(rather than
> >>>>>>>>>>one
> >>>>>>>>>>big chunk), so how would this work with syncing to the actual
> >>>>>>demo code?
> >>>>>>>>>
> >>>>>>>>>I think the entire main.cpp file (and UFL ) should be available for
> >>>>>>>>>download as it is now.
> >>>>>>>>>Then, if a demo breaks one will have to manually modify the code
> >>>>>>snippets
> >>>>>>>>>and the text.
> >>>>>>>>>(and of course the code in main.cpp and the UFL file if appropriate)
> >>>>>>>>
> >>>>>>>>Shouldn't it be possible to write a script that extracts the pieces
> >>>>>>>>and patches them together?
> >>>>>>>>
> >>>>>>>
> >>>>>>>Possible, but someone needs to do it and figure out a syntax do
> >>>>>>indicate
> >>>>>>>what line to extract.
> >>>>>>
> >>>>>>How about this:
> >>>>>>
> >>>>>>All the code for a particular demo is in main.cpp as it is now, which
> >>>>>>we will use to test against DOLFIN and make available for download in
> >>>>>>the documentation.
> >>>>>>
> >>>>>>The script should then look for all .. code-block:: directives in
> >>>>>>the documentation and check if the code is present in main.cpp.
> >>>>>>
> >>>>>>The code block presented in the documentation then has to be an exact
> >>>>>>copy of what is in main.cpp and we don't need to worry about the
> >>>>>>order or if all pieces of code match up to the entire main.cpp file.
> >>>>>
> >>>>>Should main.cpp be in DOLFIN or should it be part of the
> >>>>>documentation?
> >>>>
> >>>>It is easier if we make it part of the documentation since Sphinx will
> >>>>copy files that are available for download to the build/_downloads
> >>>>directory when building the documentation. Then it is also more
> >>>>naturally to test the demos against DOLFIN before building the
> >>>>documentation.
> >>>>
> >>>
> >>>Agree.
> >>>
> >>>Should we wait until we flesh out the documentation for Poisson (and maybe
> >>>another demo) and then move the demos from dolfin-main to fenics-doc?
> >>
> >>Yes, let's stick to the two demos we have now (Cahn-Hilliard and
> >>Poisson) and get them running for both C++ and Python, set up the
> >>scripts to check code blocks, and test against DOLFIN. I think the
> >>two demos are different enough to expose most of the problems that
> >>we'll encounter.
> >
> >So we need two scripts?
> >
> >One script to extract demos from the documentation and into DOLFIN (or
> >should we at all bundle the demos with DOLFIN, maybe not). Then only
> >the buildbot needs this script.
> >
>
> I wouldn't bundle the demos with DOLFIN. We'll have a 'dolfin-lib'
> and a 'fenics-doc' package.

Yes, that sounds good.

> What about demos from other FEniCS packages?

Don't know. The other relevant demos are the demos for UFL and FFC and
that in itself is a bit strange, to have two sets of .ufl files with a
pretty large overlap between them.

--
Anders

Attachment: signature.asc
Description: Digital signature