Changes between Version 10 and Version 11 of TracDev/ApiDocs

Timestamp:

Feb 19, 2011, 10:42:32 PM (13 years ago)

Author:

Christian Boos

Comment:

move the links to the generated docs upward, and reformulate some paragraphs

TracDev/ApiDocs

@@ -3 +3 @@
 The code is the authoritative source of  documentation, and most classes and methods have a corresponding Python "doc string".
 
-We propose two ways for taking benefit from this embedded documentation in order to generate API documentation references:
+== View the documentation
 
- apiref :: Full API reference using [http://epydoc.sourceforge.net/ epydoc]. \\
-   With epydoc, the entirety of the API is covered, but we have less control over the     generated output and the documentation is a bit more "dry" and feels, well, ... auto-generated. 
+Besides the TracBrowser and looking directly at the code, you can also read the generated API documentation, which only shows the public API in a nicely organized and rendered way:
 
- apidoc :: Semi-automatic API documentation using [http://sphinx.pocoo.org Sphinx]. \\
-   This contrasts with the above, as in Sphinx we have fine-grained control over the generated  documentation and the order in which it appears. Therefore, this documentation "reads" better. The downside is that we don't have yet full coverage of the API. //(work in progress)//
-
-For now, the two sets of documentations are complementary. One day the Sphinx documentation will be complete and sufficient, at which point we'll probably drop the epydoc part (besides, epydoc itself doesn't seem to be maintained anymore).
-
-
-== View the documentation
 {{{#!div style="background: #ffd; margin: 2em; border: outset #eec 2px; line-height: 2em;"
  - **Trac 0.13dev** ([http://www.edgewall.org/docs/trac-trunk/epydoc/ apiref] | **[http://www.edgewall.org/docs/trac-trunk/html/ apidoc HTML]** | [http://www.edgewall.org/docs/trac-trunk/pdf/trac_dev.pdf apidoc PDF])
@@ -20 +12 @@
  - Trac 0.11 (''apiref'' for [http://www.edgewall.org/docs/tags-trac-0.11.7/epydoc/ 0.11.7])
 }}}
+
+
+ apiref :: Full API reference, generated using [http://epydoc.sourceforge.net/ epydoc]. \\
+   With epydoc, the entirety of the API is covered, but we have less control over the generated output, as it only shows what's present in the source code. The documentation is a bit more "dry" and feels, well, ... auto-generated. 
+
+ apidoc :: Semi-automatic API documentation, generated using [http://sphinx.pocoo.org Sphinx]. \\
+   This contrasts with the above, as in Sphinx we have fine-grained control over the generated  documentation and the order in which it appears. We've also written additional explanations and examples not present in the code. Therefore, this documentation "reads" better than the purely auto-generated manual. The downside is that we don't have yet full coverage of the API. //(work in progress)//
+
+For now, the two sets of documentations are complementary. One day the Sphinx documentation will be complete and sufficient, at which point we'll probably drop the epydoc part (besides, epydoc itself doesn't seem to be maintained anymore).
+
 Note that as Trac 0.11 and 0.12 were not really prepared for being processed, the quality of the generated documentation is all but perfect. It's not that the one for 0.13dev is, but there we're working on it. The 0.12-stable link and the 0.13dev links above should correspond to the latest version of the corresponding branch.