On 23 May 2011 16:28, Garth N. Wells <[email protected]> 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. > >> >>> >>>> 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.
I agree that we shouldn't include html files anywhere, but the .rst files for the programmer's reference should be re-generated by any developer who changes the interface. Just like we let the 'make test' check if the demo code in the documentation is correct. Kristian > Garth > >> -- >> Marie >> >>> >>> Garth >>> >>>>> The next question is then how best to pull the docs together for the >>>>> web page. >>>> >>>> My initial suggestion would be >>>> >>>> 1. Copy .rst from dolfin/doc and dolfin/demos >>>> 2. Generate small layer of .rst's integrating these with web page >>>> 3. Build. >>>> >>>> -- >>>> Marie >>>> >>>> _______________________________________________ >>>> Mailing list: https://launchpad.net/~fenics >>>> Post to : [email protected] >>>> Unsubscribe : https://launchpad.net/~fenics >>>> 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 >> >> >> _______________________________________________ >> Mailing list: https://launchpad.net/~fenics >> Post to : [email protected] >> Unsubscribe : https://launchpad.net/~fenics >> 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 > _______________________________________________ Mailing list: https://launchpad.net/~fenics Post to : [email protected] Unsubscribe : https://launchpad.net/~fenics More help : https://help.launchpad.net/ListHelp
