= Trac API Documentation 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: 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. apidoc :: Semi-automatic API documentation using [http://sphinx.pocoo.org Sphinx]. \\ This contrasts with Sphinx, were we have fine-grained control over the 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; padding: 1em; margin: 2em; border: outset #eec 2px" - **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]) - Trac 0.12 (''apiref'' for [http://www.edgewall.org/docs/tags-trac-0.12/epydoc/ 0.12] | [http://www.edgewall.org/docs/tags-trac-0.12.1/epydoc/ 0.12.1] | [http://www.edgewall.org/docs/branches-0.12-stable/epydoc/ 0.12-stable]) - Trac 0.11 (''apiref'' for [http://www.edgewall.org/docs/tags-trac-0.11.7/epydoc/ 0.11.7]) }}} 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 [http://rst2pdf.googlecode.com 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`. ---- See also: #8695