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.
