Warning: Can't synchronize with repository "(default)" (Unsupported version control system "svn": No module named svn). Look in the Trac log for more information.

Ticket #104 (closed enhancement: fixed)

Opened 13 years ago

Last modified 9 years ago

Updated API reference toolchain

Reported by: grimmtooth@… Owned by: splee
Priority: high Milestone: 1.x
Component: Web site Version: 1.0.4.3
Severity: normal Keywords:
Cc:

Description (last modified by kevin) (diff)

I would like to generate API docs using either Epydoc or PythonDoc? (which both support attaching metadata about specific aspects of methods and source parsing, which allows documentation for object properties). I also really like having links to syntax highlighted source files, as Pudge provides or the current hacked epydoc provides.

PythonDoc? has the advantage in that it creates an infoset based on the data it collects. This makes it relatively easy to format things however we want. It currently has a limitation that it doesn't parse out the metadata tags from the docstrings, just from doc comments. I really want our docs in docstrings so that things like pydoc and help() work properly.

I'm not fond of Epydoc's multiframe appearance, and I don't think anyone else really is either. You can turn off the frames and adjust the CSS, and that may be enough customization.

So, the challenge here is to pick one of those two tools (Epydoc 3 or PythonDoc?) and then figure out the magic incantations/create templates and CSS to generate the API docs for TurboGears and everything in thirdparty except MochiKit?.

Change History

comment:1 Changed 13 years ago by kevin

  • Milestone set to 0.9

comment:2 Changed 13 years ago by kevin

  • Component changed from TurboGears to Docs

comment:3 Changed 13 years ago by kevin

  • Type changed from defect to enhancement
  • Description modified (diff)
  • Summary changed from Some functions missing from TG API reference to Updated API reference toolchain

comment:4 Changed 13 years ago by jorge.vargas

  • Version 0.8 deleted
  • Milestone changed from 0.9 to 1.0b1

I believe Kevin in the docs sprint made an update to this, was that final? does it fixes this bug?

comment:5 Changed 13 years ago by khorn

milestone passed, changing to 1.0

I really think this should be done before 1.0 is released.

comment:6 Changed 13 years ago by khorn

  • Milestone changed from 1.0b1 to 1.0

comment:7 Changed 13 years ago by steve@…

It would be nice if documentation of *any* kind was available for the API. Currently the "API Reference" link on  http://docs.turbogears.org/1.0 (which actually points to  http://www.turbogears.org/preview/api) redirects to  http://www.turbogears.org/previewdone.html, which tells me the preview is done and points me to the 1.0 docs, which don't appear to include API docs.

Help, I'm in a maze of twisty little passages all the same.

comment:8 Changed 13 years ago by steve@…

Further note:  http://www.turbogears.org/docs/ also contains an API docs link, this time pointing to  http://www.turbogears.org//api/index.html and (sorry) again broken.

comment:9 Changed 12 years ago by alberto

  • Milestone changed from 1.0 to 1.1

comment:10 Changed 12 years ago by jorge.vargas

got something working at

 http://tg.maetico.com/api/

comment:11 Changed 12 years ago by jorge.vargas

  • Priority changed from normal to high
  • Owner changed from anonymous to splee
  • Component changed from Docs to website

here is the command I used to generate the api epydoc --o api -n TurboGears -u  http://www.turbogears.org turbogears 2> error.log

eventually this could be replaced by the "apigen" package but we need to be sure this is the way we want to go.

comment:12 Changed 12 years ago by alberto

  • Milestone changed from 1.1 to __unclassified__

Batch moved into unclassified from 1.1 to properly track progress on the later

comment:13 in reply to: ↑ description Changed 11 years ago by lszyba1

  • Version set to 1.0.4.3

See  http://lucasmanual.com/tgdocs/turbogears-module.html for epydoc documentation from TurbogGears? source.

Lucas

comment:14 Changed 10 years ago by jorge.vargas

  • Status changed from new to closed
  • Resolution set to fixed

we have officially moved to sphinx. There is a ticket for moving 1.x to it, I consider this task finish.

comment:15 Changed 9 years ago by chrisz

  • Milestone changed from __unclassified__ to 1.x
Note: See TracTickets for help on using tickets.