Subject: [Fenics] doc in source

From: "Garth N. Wells" <[email-masked]>
Date: Mon, 23 May 2011 14:26:44 +0100

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? 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? Should the doc be built in the CMake 'build' dir? The next question
is then how best to pull the docs together for the web page.

Garth

---

From: "Marie E. Rognes" <[email-masked]>
Date: Mon, 23 May 2011 15:57:51 +0200

On 05/23/2011 03:26 PM, Garth N. Wells wrote:
> this some thought?

Some :-)

> Is the idea to add a root file to dolfin/doc, and
> 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.

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?

> 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

---

From: "Garth N. Wells" <[email-masked]>
Date: Mon, 23 May 2011 15:10:48 +0100

> 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?

> 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.

Garth

> _______________________________________________
> Mailing list: https://launchpad.net/~fenics
> Post to     : [email-masked]
> Unsubscribe : https://launchpad.net/~fenics
> More help   : https://help.launchpad.net/ListHelp

---

From: "Marie E. Rognes" <[email-masked]>
Date: Mon, 23 May 2011 16:23:35 +0200

> 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.

> 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)?

--
Marie

---

From: "Garth N. Wells" <[email-masked]>
Date: Mon, 23 May 2011 15:28:39 +0100

> 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.

> 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.

Garth

---

From: "Marie E. Rognes" <[email-masked]>
Date: Mon, 23 May 2011 16:42:59 +0200

> 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?

> 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)

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.

--
Marie

---

From: "Garth N. Wells" <[email-masked]>
Date: Mon, 23 May 2011 15:50:39 +0100

> 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
      .
      .

> 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.

> 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.

Garth

---

From: "Marie E. Rognes" <[email-masked]>
Date: Mon, 23 May 2011 17:05:22 +0200

> dolfin/doc/documentation.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

> build system can test that Sphinx is available and is the correct version.

Ok!

> 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

---

From: Kristian Ølgaard <[email-masked]>
Date: Mon, 23 May 2011 17:24:22 +0200

> 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

---

From: Anders Logg <[email-masked]>
Date: Mon, 23 May 2011 19:41:48 +0200

On Mon, May 23, 2011 at 05:05:22PM +0200, Marie E. Rognes wrote:
> 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
>
> >
> >>>
> >>>>
> >>>>>
> 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