generate API documentation

[anatoly techtonik <techtonik@…>]

​http://trac.edgewall.org/wiki/TracDev/PluginDevelopment lists available extension points, but doesn't describe parameters that are passed to extension point methods, such as req, env etc.

It should be possible to build API documentation automatically using ​Sphinx to extract docblocks. Additional specifiers can help limit/expand the scope of extracted information.

[Christian Boos]

Yep, I plan to do it at some point.

Unfortunately for you, that is going to be yet another make command ;-) (make apidoc).

[anatoly techtonik <techtonik@…>]

Maybe we can reach a consensus with some *.py command? =)

[Remy Blank]

I suggest we move this to 0.12.1.

[mondomhogynincs@…]

Maybe you could take a look at TracSphinx, wich aims to do something like this.

I can't link the project, becaouse trac says that is is possibly spam. You can find the package at the pypi database with the same name.

[Christian Boos]

Some work has been started in this area.

It's now possible to do one of the following:

make apidoc

To get the Sphinx HTML documentation built in build/doc/html (not much to see yet).

make apidoc sphinxformat=pdf

To get the same but in a PDF document (in build/doc/pdf/trac_dev.pdf).

Alternatively, one can also do:

make apiref

to generate the full API reference using epydoc. Nice to get a complete overview, but there are still a lot of oddly formatted content due to incorrect markup in our docstrings.

Both will gradually improve.

[Christian Boos]

See TracDev/ApiDocs for the detailed documentation about how to generate the doc yourself, as well as links to the automatically generated documentation on t.e.o.