Changes between Version 16 and Version 17 of TracDev/ApiDocs
- Timestamp:
- Jan 27, 2015, 9:45:09 PM (9 years ago)
Legend:
- Unmodified
- Added
- Removed
- Modified
-
TracDev/ApiDocs
v16 v17 1 1 = Trac API Documentation 2 2 3 The code is the authoritative source of 3 The code is the authoritative source of documentation, and most classes and methods have a corresponding Python "doc string". 4 4 5 5 == View the documentation 6 6 7 Besides the TracBrowser and looking directly at the code, you can also read the generated APIdocumentation, which shows the public API in a nicely organized and rendered way:7 Besides the TracBrowser and looking directly at the code, you can also read the generated [http://en.wikipedia.org/wiki/Application_programming_interface API] documentation, which shows the public API in a nicely organized and rendered way: 8 8 9 9 {{{#!table style="background: #ffd; margin: 2em;" … … 14 14 ||||= **Sphinx documentation** (`apidoc`) || \ 15 15 {{{#!th rowspan=2 16 Epydoc(`apiref`)16 **Epydoc** (`apiref`) 17 17 }}} 18 18 |- … … 35 35 || || || [http://www.edgewall.org/docs/tags-trac-0.11.7/epydoc/trac-module.html 0.11.7] || 36 36 }}} 37 // (in italic: corresponds to the latest revision on the branch)//37 //In italic: corresponds to the latest revision on the branch.// 38 38 39 39 apiref :: Full API reference, generated using [http://epydoc.sourceforge.net/ epydoc]. \\ 40 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.40 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. 41 41 42 42 apidoc :: Semi-automatic API documentation, generated using [http://sphinx.pocoo.org Sphinx]. \\ 43 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)//43 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)// 44 44 45 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).45 For now, the two sets of documentations are complementary. Because epydoc is no longer maintained, the Sphinx documentation will take precedence. 46 46 47 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 1.0 is, but starting from there, we're actively working on it.47 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. 48 48 49 49 == Generating the documentation … … 51 51 === Epydoc — `make apiref` 52 52 53 Once you have installed `epydoc`, all you need to do is togo to your Trac trunk checkout and do:53 Once you have installed `epydoc`, go to your Trac trunk checkout and do: 54 54 {{{ 55 55 $ make apiref 56 56 }}} 57 This will generate the `epydoc` documentation in `./build/doc/epydoc` (start with the `index.html` page).57 This will generate the `epydoc` documentation in `./build/doc/epydoc`, start with the `index.html` page. 58 58 59 59 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. … … 65 65 $ make apidoc-html 66 66 }}} 67 This will generate the `Sphinx` documentation in `./build/doc/html` (start with the `index.html` page).67 This will generate the `Sphinx` documentation in `./build/doc/html`, start with the `index.html` page. 68 68 69 69 You can also generate a PDF document using [http://rst2pdf.googlecode.com rst2pdf]: … … 75 75 Alternatively you can invoke `make apidoc` to get both. 76 76 77 Sphinx is a no brainer `easy_install sphinx` installation, which will get you the appropriate dependencies (docutils and jinja2).77 Sphinx is installed as `easy_install sphinx`, which will get you the appropriate dependencies, such as docutils and jinja2. 78 78 79 79 Same goes for `easy_install rst2pdf`. 80 80 81 81 ==== Verifying the completeness of the documentation -- `checkapidoc.py` #checkapidoc 82 82 83 Note that we also have a help script for checking whether a documented .rst module below source:trunk/doc/api contains all the symbols that need to be documented. 83 84 … … 99 100 ` * .. autofunction :: validate_page_name` corresponds to a function in [source:trunk/trac/wiki/api.py api.py] which has a docstring but is not yet present in [source:trunk/doc/api/trac_wiki_api.rst trac_wiki_api.rst]. 100 101 101 102 102 Note that when `__all__` is specified, we also consider that listed symbols which //don't// have yet a docstring should also be documented. 103 103
