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. I suggest: 1. That each project has its own doc files. 2. Each project have a 'make doc' target to build the basic docs as html and PDF from the .rst files. 3. fenics-doc copies the docs from each project to build the web page with online docs for each project. (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
