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.
