fenics team mailing list archive

[Anders Logg <logg@xxxxxxxxx>]

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