Changes between Version 18 and Version 19 of TracDev/ApiDocs
- Timestamp:
- Jul 28, 2015, 5:15:08 PM (9 years ago)
Legend:
- Unmodified
- Added
- Removed
- Modified
-
TracDev/ApiDocs
v18 v19 1 1 = Trac API Documentation 2 2 3 The code is the authoritative source of documentation, and most classes and methods have a corresponding Python "doc string". 3 The code is the authoritative source of documentation, and most classes and methods have a corresponding Python "doc string". How the documentation that has been added to the code can be viewed and generated is explained on this page. 4 4 5 5 == View the documentation … … 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.//38 37 39 For now, the two sets of documentations are complementary. Because epydoc is no longer maintained, the Sphinx documentation will take precedence. 38 In //italic//: corresponds to the latest revision on the branch. 39 40 The Sphinx documentation will take precedence, because epydoc is no longer maintained. For now, the two sets of documentation are complementary. 40 41 41 42 apidoc :: Semi-automatic API documentation, generated using [http://sphinx.pocoo.org Sphinx]. \\ 42 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)//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 there is no full coverage of the API yet. Apidoc has been introduced in Trac 1.0. 43 44 44 45 apiref :: Full API reference, generated using [http://epydoc.sourceforge.net/ epydoc]. \\ … … 50 51 51 52 Once you have installed `sphinx`, go to your Trac 1.0-stable or trunk checkout and do: 52 {{{ 53 {{{#!sh 53 54 $ make apidoc-html 54 55 }}} … … 56 57 57 58 You can also generate a PDF document using [http://rst2pdf.googlecode.com rst2pdf]: 58 {{{ 59 {{{#!sh 59 60 $ make apidoc-pdf 60 61 }}} … … 72 73 73 74 For example: 74 {{{ 75 {{{#!sh 75 76 $ PYTHONPATH=. python doc/utils/checkapidoc.py trac_wiki_api 76 77 }}} 77 78 will check if all public and documented symbols from source:trunk/trac/wiki/api.py are referenced in source:trunk/doc/api/trac_wiki_api.rst. 78 79 79 {{{ 80 {{{#!sh 80 81 $ PYTHONPATH=. python doc/utils/checkapidoc.py trac_wiki_api 81 82 Warning: trac.wiki.api doesn't define __all__, using exported symbols. 82 83 * .. autofunction :: validate_page_name 83 84 }}} 85 84 86 Explaining the output: 85 87 86 `Warning: trac.wiki.api doesn't define __all__, using exported symbols.` means that in the absence of an explicit list of public symbols, we try to guess what needs to be documented by looking at the globals of that module which have a docstring.88 * `Warning: trac.wiki.api doesn't define __all__, using exported symbols.` means that in the absence of an explicit list of public symbols, we try to guess what needs to be documented by looking at the globals of that module which have a docstring. 87 89 88 ` * .. 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].90 * ` * .. 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]. 89 91 90 Note that when `__all__` is specified, we also consider that listed symbols which //don't// have yet a docstringshould also be documented.92 Note that when `__all__` is specified, we also consider that listed symbols which //don't// have a docstring yet should also be documented. 91 93 92 94 A symbol can be explicitly declared to be unwanted in the Sphinx documentation by listing it in the global `__no_apidoc__` property of its defining module. 93 95 94 96 There's also a verbose mode `-v` for showing all the symbols found: 95 {{{ 97 {{{#!sh 96 98 $ PYTHONPATH=. python doc/utils/checkapidoc.py trac_wiki_api -v 97 99 == Checking trac_wiki_api.rst ... … … 109 111 110 112 Once you have installed `epydoc`, go to your Trac trunk checkout and do: 111 {{{ 113 {{{#!sh 112 114 $ make apiref 113 115 }}} … … 115 117 116 118 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. 117
