Changes between Version 17 and Version 18 of TracDev/ApiDocs

Timestamp:

Feb 16, 2015, 8:57:14 AM (9 years ago)

Author:

figaro

Comment:

Reordered paragraph to match with table structure and removed caveat.

TracDev/ApiDocs

@@ -37 +37 @@
     //In italic: corresponds to the latest revision on the branch.//
 
+For now, the two sets of documentations are complementary. Because epydoc is no longer maintained, the Sphinx documentation will take precedence.
+
+ apidoc :: Semi-automatic API documentation, generated using [http://sphinx.pocoo.org Sphinx]. \\
+   Sphinx offers 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. //(introduced in Trac 1.0, work in progress)//
+
  apiref :: Full API reference, generated using [http://epydoc.sourceforge.net/ epydoc]. \\
    With epydoc, the entirety of the API is covered, but there is less control over the generated output, as it only shows what is present in the source code. The documentation has a more auto-generated feel. 
 
- apidoc :: Semi-automatic API documentation, generated using [http://sphinx.pocoo.org Sphinx]. \\
-   Sphinx offers 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. Because epydoc is no longer maintained, the Sphinx documentation will take precedence.
-
-Note that starting from Trac 1.0, the quality of the generated documentation is gradually improved, because it was the release where this documentation method was introduced.
-
 == Generating the documentation
-
-=== Epydoc — `make apiref`
-
-Once you have installed `epydoc`, go to your Trac trunk checkout and do:
-{{{
-$ make apiref
-}}}
-This will generate the `epydoc` documentation in `./build/doc/epydoc`, start with the `index.html` page.
-
-Note that while installing epydoc with `easy_install` might work on Linux (not tested), on Windows you should rather download and execute the Windows installer.
 
 === Sphinx — `make apidoc`
@@ -117 +105 @@
  * ..   autofunction :: validate_page_name
 }}}
+
+=== Epydoc — `make apiref`
+
+Once you have installed `epydoc`, go to your Trac trunk checkout and do:
+{{{
+$ make apiref
+}}}
+This will generate the `epydoc` documentation in `./build/doc/epydoc`, start with the `index.html` page.
+
+Note that while installing epydoc with `easy_install` might work on Linux (not tested), on Windows you should rather download and execute the Windows installer.
+