Edgewall Software

Opened 13 years ago

Closed 12 years ago

Last modified 10 years ago

#8695 closed enhancement (fixed)

generate API documentation

Reported by: anatoly techtonik <techtonik@…> Owned by: Christian Boos
Priority: normal Milestone: 1.0
Component: general Version: none
Severity: major Keywords: devguide api documentation
Cc: ryano@… Branch:
Release Notes:

Trac now comes with some API documentation.

API Changes:

make apiref for Epydoc documentation; make apidoc for Sphinx documentation

Internal Changes:


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.

Attachments (0)

Change History (10)

comment:1 by Christian Boos, 13 years ago

Keywords: api documentation added
Milestone: 0.12
Owner: set to 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).

comment:2 by anatoly techtonik <techtonik@…>, 13 years ago

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

comment:3 by Christian Boos, 13 years ago

Keywords: devguide added

comment:4 by Remy Blank, 13 years ago

Milestone: 0.12next-minor-0.12.x

I suggest we move this to 0.12.1.

comment:5 by mondomhogynincs@…, 13 years ago

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.

comment:6 by Christian Boos, 13 years ago

Milestone: next-minor-0.12.x0.13
Severity: normalmajor

comment:7 by Ryan J Ollos <ryano@…>, 12 years ago

Cc: ryano@… added

comment:8 by Christian Boos, 12 years ago

Status: newassigned

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.

comment:9 by Christian Boos, 12 years ago

Resolution: fixed
Status: assignedclosed

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.

comment:10 by Christian Boos, 10 years ago

API Changes: modified (diff)
Release Notes: modified (diff)

Modify Ticket

Change Properties
Set your email in Preferences
as closed The owner will remain Christian Boos.
The resolution will be deleted. Next status will be 'reopened'.
to The owner will be changed from Christian Boos to the specified user.

Add Comment

E-mail address and name can be saved in the Preferences .
Note: See TracTickets for help on using tickets.