dolfin team mailing list archive

[Anders Logg <logg@xxxxxxxxx>]

On Wed, May 18, 2011 at 07:16:03PM +0200, Marie E. Rognes wrote:
> On 05/16/2011 08:13 PM, Marie E. Rognes wrote:
> >
> >
> >On 16. mai 2011, at 19:58, Kristian Ølgaard<k.b.oelgaard@xxxxxxxxx>  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. :(
> >>
> >>>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),
> >
> >
> >It will make a difference for me, but maybe that's just me.
> >
> >
> >>unless you
> >>change (a) to:
> >>(a) run the script test/verify_demo_code_snippets.py as part of 'make
> >>test' in dolfin.
> >
> >
> >I think this sounds like a good idea.
> >
> >
> >>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.
> >>
> >
> >Maybe, I'm not quite sure what it entails. I'll open up a new blueprint when I get back on Wednesday, unless someone beats me to it.
>
>
> I've opened up a new blueprint (containing the last part of this
> discussion) on fenics-doc, added some milestones to fenics-doc and
> targeted some more blueprints. I've only subscribed the fenics core
> team to these, so anyone else wanting to follow the launchpad
> discussion, subscribe.
>
> However, blueprints relating to dolfin/documentation/web seem to be
> partly in lp:dolfin, partly in lp:fenics-doc and partly in
> lp:fenics-web. Perhaps some consolidation could be beneficial?

The blueprints should be in fenics-doc. But it's practical to have one
blueprint tied to DOLFIN 1.0 to emphasize that the web should be ready
in time for the release.

--
Anders