fenics team mailing list archive

[Kristian Ølgaard <k.b.oelgaard@xxxxxxxxx>]

On 16 May 2011 20:52, Garth N. Wells <gnw20@xxxxxxxxx> wrote:
>
>
> On 16/05/11 19:46, Kristian Ølgaard wrote:
>> On 16 May 2011 20:10, Garth N. Wells <gnw20@xxxxxxxxx> wrote:
>>>
>>>
>>> On 16/05/11 18:58, Kristian Ølgaard wrote:
>>>> On 16 May 2011 14:33, Marie E. Rognes <meg@xxxxxxxxx> wrote:
>>>>>
>>>>> On 16. mai 2011, at 14:17, Kristian Ølgaard <k.b.oelgaard@xxxxxxxxx> wrote:
>>>>>
>>>>>> On 16 May 2011 13:49, Marie E. Rognes <meg@xxxxxxxxx> wrote:
>>>>>>>
>>>>>>>
>>>>>>> On 16. mai 2011, at 12:13, "Garth N. Wells" <gnw20@xxxxxxxxx> wrote:
>>>>>>>
>>>>>>>> I suggest now would be a good point to make new releases of UFL, FFC and
>>>>>>>> DOLFIN. There have been a number of improvements to UFL, FFC caching,
>>>>>>>> and there have been a good number of DOLFIN bugs fixes. New version
>>>>>>>> numbers would be:
>>>>>>>>
>>>>>>>> UFL: 0.9.1
>>>>>>>> FFC: 0.9.1
>>>>>>>> DOLFIN: 0.9.12
>>>>>>>>
>>>>>>>> Jump in quick if there is anything that you would like do before a release.
>>>>>>>>
>>>>>>>
>>>>>>> I have one thing relating to the documentation, and the demo documentation in particular.
>>>>>>>
>>>>>>> In order to more easily keep the demo documentation in sync with the demos, I think we should move the .rst files from the separate fenics-doc repo to the corresponding dolfin demo directories. Any objections?
>>>>>>
>>>>>> Yes, the whole point of fenics-docs was to collect the documentation
>>>>>> in one place, thus separating the documentation from the packages
>>>>>> containing the code.
>>>>>>
>>>>>
>>>>> I understand that point, but I don't see it working that well.
>>>>
>>>> I was more objecting to changing the documentation
>>>> design/philosophy.... again. :(
>>>>
>>>
>>> I'd say we're learning as we go along.
>>>
>>>>> Having the demo .rst files with the dolfin demos would (a) make it more obvious to update them when updating the code and (b) make it easier to ensure valid documentation for stable releases.
>>>>
>>>> I bet that the .rst files for the demos will not get updated just by
>>>> moving them to dolfin/demo (perhaps only the first week), unless you
>>>> change (a) to:
>>>> (a) run the script test/verify_demo_code_snippets.py as part of 'make
>>>> test' in dolfin.
>>>> I agree on (b)
>>>>
>>>>> Wasn't the API documentation for the DOLFIN library moved in with the code for some of the same reasons?
>>>>
>>>> Possibly, again, this has changed so many times that I forgot why.
>>>>
>>>>> Writing documentation isn't that fun, so I would like to aim for a system that is maintainable.
>>>>
>>>> We'll never disagree on this one.
>>>>
>>>> We're currently copying the demo files (.py, .cpp, .ufl) anyway, it
>>>> should be just as easy to copy any .rst files.
>>>>
>>>> Perhaps the documentation of the demos could be self contained?
>>>> Such that we have an index.rst file in dolfin/demo which includes the rest?
>>>> Then it will be easy for dolfin developers to run a 'make html'
>>>> locally in the dolfin/demo directory to test that it works.
>>>> We can just use the Sphinx default styles.
>>>>
>>>
>>> I was thinking that the docs should be self-contained. I moved the UFL
>>> doc to .rst in the doc repository, and it seemed strange removing the
>>> doc from a stand-alone document in the UFL repository.
>>
>> But then at least it will be easy to just copy the .rst files back into UFL.
>>
>
> Yes, and I think that the natural place for them to go is with UFL. That
> way, a UFL tarball has the docs included (likewise for other projects).
>
>>> I suggest:
>>>
>>> 1. That each project has its own doc files.
>>
>> And DOLFIN will need the scripts that generate the cpp and python
>> docs, then there's no need for fenics-doc to
>> worry about the local version numbers etc.
>>
>>> 2. Each project have a 'make doc' target to build the basic docs as html
>>> and PDF from the .rst files.
>>
>> OK.
>>
>>> 3. fenics-doc copies the docs from each project to build the web page
>>> with online docs for each project.
>>
>> OK, that would simplify things a lot on the fenics-doc side.
>>
>
> Is that an implicit agreement that the docs should go with the projects?

Yes, let's try it out for a couple of months, we can always think of
new ways to do things.

Kristian

> Garth
>
>
>> Kristian
>>
>>> (I'm sending this to the fenics list only.)
>>>
>>> Garth
>>>
>>>> Kristian
>>>>
>>>>> --
>>>>> Marie
>>>>>
>>>>>
>>>>>> Kristian
>>>>>>
>>>>>>> (I'm on very flaky wifi until Wednesday morning and at the moment slightly unable to do anything but occasionally retrieve email...)
>>>>>>>
>>>>>>> --
>>>>>>> Marie
>>>>>>>
>>>>>>>
>>>>>>>> Garth
>>>>>>>>
>>>>>>>> _______________________________________________
>>>>>>>> Mailing list: https://launchpad.net/~ffc
>>>>>>>> Post to     : ffc@xxxxxxxxxxxxxxxxxxx
>>>>>>>> Unsubscribe : https://launchpad.net/~ffc
>>>>>>>> More help   : https://help.launchpad.net/ListHelp
>>>>>>>
>>>>>>> _______________________________________________
>>>>>>> Mailing list: https://launchpad.net/~ffc
>>>>>>> Post to     : ffc@xxxxxxxxxxxxxxxxxxx
>>>>>>> Unsubscribe : https://launchpad.net/~ffc
>>>>>>> More help   : https://help.launchpad.net/ListHelp
>>>>>>>
>>>>>
>>>
>