On 16/05/11 19:46, Kristian Ølgaard wrote: > 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. >
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? 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 : [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
