On 22 March 2010 14:50, Anders Logg <[email protected]> wrote:
On Thu, Mar 18, 2010 at 09:22:24AM -0500, Andy Ray Terrel wrote:I've never heard of doconce. Is there a link somewhere? Just to throw this out there you might check out the way Numpy and Scipy does theirs (I believe with sphinx [0] which has that nice feature of publishing to pdf or html). If there was some style guide set up and the key areas pointed out, it might be good to have a documentation marathon for FEniCS'10. [0] http://sphinx.pocoo.org/I looked a bit more on Sphinx, and it looks really good. The documentation for Sphinx states the following: The focus is on hand-written documentation, rather than auto-generated API docs.
So we will abandon Doxygen and similar tools? Sounds good to me, but I guess it will make it slightly more difficult to ensure that all functions are documented and not forgotten. But maybe there are tools for this?
This seems to fit very well with our discussion regarding whether or not to put the documentation as part of the code.
So we only put short comments in the code like we do now, and then put documentation in sphinx source files.
So Sphinx would be a tool we could use to produce good looking, cross-referenced, indexed documentation from a set of simple input files (in reST or doconce format), but we would not extract anything from the code. With this approach, I wonder where the limitations are for documenting the C++ interface. Are there any? If we don't use Doxygen, we would just write the documentation in the same way as for the Python interface. And I just thought of another reason for splitting the documentation from the code which is that it makes it possible to separate write access for the code and the documentation.
Good point. Kristian
-- Anders -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.4.9 (GNU/Linux) iEYEARECAAYFAkundcIACgkQTuwUCDsYZdGbegCgkvje5skw8pkEHWWKRgW4CrFh zjMAn15eImocRibmFiLQExZkClQ8oTdg =p16A -----END PGP SIGNATURE----- _______________________________________________ Mailing list: https://launchpad.net/~fenics Post to : [email protected] Unsubscribe : https://launchpad.net/~fenics More help : https://help.launchpad.net/ListHelp
signature.asc
Description: OpenPGP digital signature
_______________________________________________ Mailing list: https://launchpad.net/~fenics Post to : [email protected] Unsubscribe : https://launchpad.net/~fenics More help : https://help.launchpad.net/ListHelp
