Version 15 (modified by 12 years ago) ( diff ) | ,
---|
Trac API Documentation
The code is the authoritative source of documentation, and most classes and methods have a corresponding Python "doc string".
View the documentation
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:
- Trac 1.0dev: apiref | apidoc HTML | apidoc PDF
- Trac 0.12: apiref for 0.12 | 0.12.1 | 0.12.2 | 0.12.3 | 0.12.4rc1 | 0.12-stable
- Trac 0.11: apiref for 0.11.7
- apiref
- Full API reference, generated using 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 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.
Generating the documentation
Epydoc — make apiref
Once you have installed epydoc
, all you need to do is to 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
Once you have installed sphinx
, go to your Trac trunk checkout and do:
$ make apidoc-html
This will generate the Sphinx
documentation in ./build/doc/html
(start with the index.html
page).
You can also generate a PDF document using rst2pdf:
$ make apidoc-pdf
This will generate the ./build/doc/pdf/trac_dev.pdf
file.
Alternatively you can invoke make apidoc
to get both.
Sphinx is a no brainer easy_install sphinx
installation, which will get you the appropriate dependencies (docutils and jinja2).
Same goes for easy_install rst2pdf
.
Verifying the completeness of the documentation — checkapidoc.py
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.
For example:
$ PYTHONPATH=. python doc/utils/checkapidoc.py trac_wiki_api
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.
$ PYTHONPATH=. python doc/utils/checkapidoc.py trac_wiki_api Warning: trac.wiki.api doesn't define __all__, using exported symbols. * .. autofunction :: validate_page_name
Explaining the output:
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.
* .. autofunction :: validate_page_name
corresponds to a function in api.py which has a docstring but is not yet present in trac_wiki_api.rst.
Note that when __all__
is specified, we also consider that listed symbols which don't have yet a docstring should also be documented.
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.
There's also a verbose mode -v
for showing all the symbols found:
$ PYTHONPATH=. python doc/utils/checkapidoc.py trac_wiki_api -v == Checking trac_wiki_api.rst ... Warning: trac.wiki.api doesn't define __all__, using exported symbols. - OK autoclass :: IWikiChangeListener - OK autoclass :: IWikiMacroProvider - OK autoclass :: IWikiPageManipulator - OK autoclass :: IWikiSyntaxProvider - OK autoclass :: WikiSystem - OK autofunction :: parse_args * .. autofunction :: validate_page_name