fenics team mailing list archive

[Anders Logg <logg@xxxxxxxxx>]

I've thought some more on how to organize/synchronize the FEniCS
documentation (in fenics-doc) with the documentation we have in the
code.

I think it is important that

(1) the strings we have in the code are the same as those that appear
on in the HTML documentation (which we write in Sphinx).

(2) the strings we have in the code are short (so they don't clutter
up the code)

If we look at these two, it seems that (1) implies that we should
write the documentation as part of the code and then extract it using
some tool.

But (2) prevents that since we don't want to constrain the
documentation for all functions to be very short.

How about the following solution.

* Write short docstrings in the code

* Auto-generate all the .rst input files for the Programmer's
  Reference using a simple Python script that looks for '///'

* The script looks at the code to generate the signature of the
  function and the text that comes immediately after.

  But it also looks in a hand-written .rst file that contains any
  additional stuff we want to put below.

So for the code example in the style manual, the things that get
picked up from the code are

  // Return the cell which is closest to the given point
  uint closest_cell(const Point & point) const

which gets converted to

.. cpp:function:: uint closest_cell(const Point & point) const

    Return the cell which is closest to the given point

The script also looks in a file for "closest_cell" below which we have
written all the *Arguments* stuff that will be thrown in below.

Will that work?

Another solution would be to just write everything as part of the
code, and just add some settings to our editors that will fold the
extra stuff away so we don't need to see it. Maybe that is the most
robust solution?

--
Anders