wiki:PyDocPlugin

Version 26 (modified by figaro, 9 years ago) (diff)

Cosmetic changes, tagged with 'documentation'

Python documentation plugin

Notice: This plugin is unmaintained and available for adoption.

Description

This plugin allows the user to browse Python documentation through Trac's interface, using the pydoc documentation system.

It was originally written for Trac 0.9, but there's a fully 0.10 compatible version, as well as a Genshi version for Trac 0.11dev.

Alternatives to pydoc

Tools that use static code analysis would be preferable to those that compile the Python code and inspect the doc strings. Some tools that do this are Endo (promising), PythonDoc (promising), Happy Doc and PyDoctor (requires trunk version of some divmod modules, couldn't get it working).

Others are Pudge and EpyDoc (fully supported by the EpyDocPlugin).

Bugs/Feature Requests

Existing bugs and feature requests for PyDocPlugin are here.

If you have any issues, create a new ticket.

defect

4 / 7

enhancement

2 / 5

task

0 / 1

Download

Download the zipped source corresponding to your Trac version:

Trac 0.9 [download:pydocplugin/0.9 pydocplugin/0.9]
Trac 0.10 [download:pydocplugin/0.10 pydocplugin/0.10]
Trac 0.11 [download:pydocplugin/0.11 pydocplugin/0.11]

Source

You can check out PyDocPlugin from here using Subversion, or browse the source with Trac.

Usage

Use pydoc:object to link to the documentation for object.

Inline Expansion of Python Documentation

The [[pydoc(target[,visibility])]] macro will expand the documentation for object inline.

The option settings for visibility can be either public, private or left empty, in which case the visibility depends on the [pydoc] show_private setting.

Searching the Python Documentation

Documentation searches use the same mechansim as pydoc -k. Not ideal, but sufficient.

Configuration

All configuration occurs under the [pydoc] section of your trac.ini file.

Documentation Search Path

The Python documentation will only be displayed for builtin modules and for the modules listed in the sys.path configuration option. Use the os.pathsep character in order to separate the paths.

If the configuration key is not set, the sys.path variable value will be used.

In addition, the index can also be filtered through an include/exclude list. This is a glob, so you will need appropriate wildcards to match correctly. For example, to display all DBM modules except anydbm:

[pydoc]
include = *dbm*
exclude = anydbm

To display just the Trac documentation:

[pydoc]
include = trac trac.*

Note: You will need both trac and trac.* as browsing matches against the module name and searching matches against the full object name.

Display Private Documentation

Added show_private configuration setting for [pydoc]. The Python private documentation can now be displayed for the modules that are found in this space separated list of module patterns. For example, in order to show the private documentation for Trac and the WebAdmin plugin:

[pydoc]
show_private = trac.*  webadmin.*

Example

Use pydoc:trac to view the Python documentation for Trac.

Use [[pydoc(os.path.isdir)]] to inline the documentation for os.path.isdir().

Recent Changes

16773 by rjollos on 2017-08-26 03:37:27
TracPyDoc 0.11.2: Add license info
16525 by rjollos on 2017-04-16 02:00:00
Fix indentation
15875 by rjollos on 2016-09-07 21:53:13
Remove obsolete branch
(more)

Author/Contributors

Author: athomas
Contributors: none (needsadoption)
Authors: athomas cboos