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.
