On Mon, May 23, 2011 at 05:05:22PM +0200, Marie E. Rognes wrote: > On 05/23/2011 04:50 PM, Garth N. Wells wrote: > > > > > >On 23/05/11 15:42, Marie E. Rognes wrote: > >>On 05/23/2011 04:28 PM, Garth N. Wells wrote: > >>> > >>> > >>>On 23/05/11 15:23, Marie E. Rognes wrote: > >>>>On 05/23/2011 04:10 PM, Garth N. Wells wrote: > >>>>> > >>>>> > >>>>>On 23/05/11 14:57, Marie E. Rognes wrote: > >>>>>>On 05/23/2011 03:26 PM, Garth N. Wells wrote: > >>>>>>>I think we need figure out quickly how to build the doc now that it's > >>>>>>>been moved into the source tree (at least for DOLFIN). Has anyone > >>>>>>>given > >>>>>>>this some thought? > >>>>>> > >>>>>>Some :-) > >>>>>> > >>>>>>>Is the idea to add a root file to dolfin/doc, and > >>>>>>>just use paths relative to this to include demo doc, programmer ref, > >>>>>>>etc? > >>>>>> > >>>>>>I put the demo doc (.rst) together with the demos (common text in > >>>>>>common dir, cpp/python specific .rst in cpp/python dirs). This makes > >>>>>>it natural to update the doc when updating the demo code, and seemed > >>>>>>like the most intuitive to me. > >>>>>> > >>>>> > >>>>>Are you saying that we should include one .rst file in another .rst > >>>>>file > >>>>>using paths that follow the DOLFIN directory structure? > >>>> > >>>> > >>>>Not exactly. I'm saying that demo/foo/cpp/documentation.rst and > >>>>demo/foo/python documentation.rst includes demo/foo/common.txt (as > >>>>../common.txt). This is as it was in fenics-doc with the exception that > >>>>the code for the demos was copied from dolfin using a separate script. > >>>> > >>> > >>>That bit's easy, but the next level up needs to include the demo files. > >> > >>I don't understand. Next level up in what direction? > >> > > > >The top level, and from there down, e.g. > > > >dolfin/doc/documentation.rst > > > > .. toctree:: > > > > path/to-prog/ref > > ../demo/demos.rst > > . > > . > > In order to generate sensible navigation and in particular toctrees? > I still suggest "Generate small layer of .rst's integrating > these[the doc .rst files] with web page", for instance by generating > a suitable amount of index.rst files looking something like > > .. toctree:: > :glob: > > */.rst > > > > >>> > >>>> > >>>>> > >>>>>>Next planned step is to move the programmer's-reference-generating > >>>>>>scripts from fenics-doc, and let these generate the .rst-files under > >>>>>>for instance dolfin/doc. > >>>>>> > >>>>>>>Should the doc be built in the CMake 'build' dir? > >>>>>> > >>>>>>Is "the doc" the .rst or the .html? > >>>>>> > >>>>> > >>>>>I think we should let CMake do whatever it wants when it builds the > >>>>>files (which is create the html files in the build dir), and have CMake > >>>>>install the html/pdf files in share/dolfin/doc. > >>>> > >>>>Fine by me. > >>>> > >>>>Should the generation of the programmer's reference (from code to .rst) > >>>>also be a part of the build or should it be explicitely generated and > >>>>stored (like the swig-generated files)? > >>>> > >>> > >>>I would suggest that it be built by the user, and when making a release > >>>we can consider building and including it then. Otherwise we'll fill the > >>>repository with html files. > >> > >>To clarify, I'm thinking of a two-step pipeline > >> > >> (1) (2) > >> Code -> .rst -> .html > >> > >>Details to be sorted out: > >> > >>1. When and how should step (1) happen? > >>2. Should (if yes, where) .rst be stored in the repository? > >>3. When and how should step (2) happen? > >> > >>One way would be > >> > >>1. Explicitely by someone running a generate-script > >>2. Yes, under dolfin/doc > >>3. As you suggest above (with some basic default settings from sphinx) > >> > > > >It should run via the build system, with make targets for each step. The > >build system can test that Sphinx is available and is the correct version. > > > > Ok! > > > > >>Further: > >> > >>4. The official web page either has its own version of steps 1 -- 3 or > >>copies from dolfin/doc/.../.rst and generates its own html. > >> > > > >The above is a good reason to get the doc building for each project > >working - it's hard to think too many steps ahead. > > > Yep, I was planning on working my way through DOLFIN this week, > taking one step at a time ...
I've been caught up in some book editing today, but let me just make a couple of irrelevant comments: 1. I think Marie has this covered. 2. I suggest renaming documentation.rst to doc.rst (for the same reason that a price tag is usually 9.99 and not 10), looks easier to edit. :-) 3. I hope to have most elements in place for the new web page next week: new logo, newsfeed, platform sniff and will then get started on helping out with integrating the scattered docs into fenics-doc. -- Anders _______________________________________________ Mailing list: https://launchpad.net/~fenics Post to : [email protected] Unsubscribe : https://launchpad.net/~fenics More help : https://help.launchpad.net/ListHelp
