On 16 May 2011 20:10, Garth N. Wells <[email protected]> wrote: > > > On 16/05/11 18:58, Kristian Ølgaard wrote: >> On 16 May 2011 14:33, Marie E. Rognes <[email protected]> wrote: >>> >>> On 16. mai 2011, at 14:17, Kristian Ølgaard <[email protected]> wrote: >>> >>>> On 16 May 2011 13:49, Marie E. Rognes <[email protected]> wrote: >>>>> >>>>> >>>>> On 16. mai 2011, at 12:13, "Garth N. Wells" <[email protected]> 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. > 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. 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 : [email protected] >>>>>> Unsubscribe : https://launchpad.net/~ffc >>>>>> More help : https://help.launchpad.net/ListHelp >>>>> >>>>> _______________________________________________ >>>>> Mailing list: https://launchpad.net/~ffc >>>>> Post to : [email protected] >>>>> Unsubscribe : https://launchpad.net/~ffc >>>>> More help : https://help.launchpad.net/ListHelp >>>>> >>> > _______________________________________________ Mailing list: https://launchpad.net/~fenics Post to : [email protected] Unsubscribe : https://launchpad.net/~fenics More help : https://help.launchpad.net/ListHelp
