| Thread Previous • Date Previous • Date Next • Thread Next |
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 ...
-- Marie
Garth-- MarieGarth-- MarieGarthThe 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 : fenics@xxxxxxxxxxxxxxxxxxx Unsubscribe : https://launchpad.net/~fenics More help : https://help.launchpad.net/ListHelp_______________________________________________ Mailing list: https://launchpad.net/~fenics Post to : fenics@xxxxxxxxxxxxxxxxxxx Unsubscribe : https://launchpad.net/~fenics More help : https://help.launchpad.net/ListHelp_______________________________________________ Mailing list: https://launchpad.net/~fenics Post to : fenics@xxxxxxxxxxxxxxxxxxx Unsubscribe : https://launchpad.net/~fenics More help : https://help.launchpad.net/ListHelp_______________________________________________ Mailing list: https://launchpad.net/~fenics Post to : fenics@xxxxxxxxxxxxxxxxxxx Unsubscribe : https://launchpad.net/~fenics More help : https://help.launchpad.net/ListHelp_______________________________________________ Mailing list: https://launchpad.net/~fenics Post to : fenics@xxxxxxxxxxxxxxxxxxx Unsubscribe : https://launchpad.net/~fenics More help : https://help.launchpad.net/ListHelp_______________________________________________ Mailing list: https://launchpad.net/~fenics Post to : fenics@xxxxxxxxxxxxxxxxxxx Unsubscribe : https://launchpad.net/~fenics More help : https://help.launchpad.net/ListHelp
| Thread Previous • Date Previous • Date Next • Thread Next |
