twisted / pydoctor

This is pydoctor, an API documentation generator that works by static analysis.

pydoctor

This is pydoctor, an API documentation generator that works by static analysis.

It was written primarily to replace epydoc for the purposes of the Twisted project as epydoc has difficulties with zope.interface. If you are looking for a successor to epydoc after moving to Python 3, pydoctor might be the right tool for your project as well.

pydoctor puts a fair bit of effort into resolving imports and computing inheritance hierarchies and, as it aims at documenting Twisted, knows about zope.interface's declaration API and can present information about which classes implement which interface, and vice versa.

Contents:

Simple Usage

You can run pydoctor on your project like this:

$ pydoctor --make-html --html-output=docs/api src/mylib

For more info, Read The Docs.

Markup

pydoctor currently supports the following markup languages in docstrings:

epytext (default)

The markup language of epydoc. Simple and compact.

restructuredtext

The markup language used by Sphinx. More expressive than epytext, but also slightly more complex and verbose.

google

Docstrings formatted as specified by the Google Python Style Guide. (compatible with reStructuredText markup)

numpy

Docstrings formatted as specified by the Numpy Docstring Standard. (compatible with reStructuredText markup)

plaintext

Text without any markup.

You can select a different format using the --docformat option or the __docformat__ module variable.

What's New?

in development

pydoctor 24.3.3

• Fix release pipeline.

pydoctor 24.3.0

This is the last major release to support Python 3.7.

• Drop support for Python 3.6.
• Add support for Python 3.12.
• Astor is no longer a requirement starting at Python 3.9.
• ExtRegistrar.register_post_processor() now supports a priority argument that is an int. Highest priority callables will be called first during post-processing.
• Fix too noisy --verbose mode (suppres some ambiguous annotations warnings).
• Fix type processing inside restructuredtext consolidated fields.
• Add options --cls-member-order and --mod-member-order to customize the presentation order of class members and module/package members, the supported values are "alphabetical" or "source". The default behavior is to sort all members alphabetically.
• Make sure the line number coming from ast analysis has precedence over the line of a ivar field.
• Ensure that all docutils generated css classes have the rst- prefix, the base theme have been updated accordingly.
• Fix compatibility issue with docutils 0.21.x
• Transform annotations to use python 3.10 style: typing.Union[x, y] -> x | y; typing.Optional[x] -> x | None; typing.List[x] -> list[x].
• Do not output useless parenthesis when colourizing subscripts.

pydoctor 23.9.1

• Fix regression in link not found warnings' line numbers.

pydoctor 23.9.0

This is the last major release to support Python 3.6.

• Do not show **kwargs when keywords are specifically documented with the keyword field and no specific documentation is given for the **kwargs entry.
• Fix annotation resolution edge cases: names are resolved in the context of the module scope when possible, when impossible, the theoretical runtime scopes are used. A warning can be reported when an annotation name is ambiguous (can be resolved to different names depending on the scope context) with option -v.
• Ensure that explicit annotation are honored when there are multiple declarations of the same name.

• Use stricter verification before marking an attribute as constant:

  • instance variables are never marked as constant
  • a variable that has several definitions will not be marked as constant
  • a variable declaration under any kind of control flow block will not be marked as constant

• Do not trigger warnings when pydoctor cannot make sense of a potential constant attribute (pydoctor is not a static checker).
• Fix presentation of type aliases in string form.
• Improve the AST colorizer to output less parenthesis when it's not required.
• Fix colorization of dictionary unpacking.
• Improve the class hierarchy such that it links top level names with intersphinx when possible.
• Add highlighting when clicking on "View In Hierarchy" link from class page.
• Recognize variadic generics type variables (PEP 646).
• Fix support for introspection of cython3 generated modules.
• Instance variables are marked as such across subclasses.

pydoctor 23.4.1

• Pin urllib3 version to keep compatibility with cachecontrol and python3.6.

pydoctor 23.4.0

• Add support for Python 3.11
• Add support for the @overload decorator.
• Show type annotations in function's signatures.
• If none of a function's parameters have documentation, do not render the parameter table.
• Themes have been adjusted to render annotations more concisely.
• Fix a rare crash in the type inference. Invalid python code like a set of lists would raise a uncaught TypeError in the evaluation.
• Support when source path lies outside base directory (--project-base-dir). Since pydoctor support generating docs for multiple packages, it is not certain that all of the source is even viewable below a single URL. We now allow to add arbitrary paths to the system, but only the objects inside a module wich path is relative to the base directory can have a source control link generated.
• Cache the default docutils settings on docutils>=0.19 to improve performance.
• Improve the search bar user experience by automatically appending wildcard to each query terms when no terms already contain a wildcard.
• Link recognized constructors in class page.
• An invalid epytext docstring will be rederered as plaintext, just like invalid restructuredtext docstrings (finally).

pydoctor 22.9.1

• pydoctor --help works again.

pydoctor 22.9.0

• Add a special kind for exceptions (before, they were treated just like any other class).
• The ZopeInterface features now renders again. A regression was introduced in pydoctor 22.7.0.
• Python syntax errors are now logged as violations.
• Fixed rare crash in the rendering of parsed elements (i.e. docstrings and ASTs). This is because XHTML entities like non-breaking spaces are not supported by Twisted's XMLString at the moment.
• Show the value of type aliases and type variables.
• The --prepend-package now work as documented. A regression was introduced in pydoctor 22.7.0 and it was not nesting new packages under the "fake" package.
• self parameter is now removed only when the target is a method. In the previous version, it was always removed in any context.
• cls parameter is now removed only when the target is a class method. In the previous version, it was always removed in any context.
• Add anchors aside attributes and functions to ease the process of sharing links to these API docs.
• Fix a bug in the return clause of google-style docstrings where the return type would be treated as the description when there is no explicit description.
• Trigger warnings for unknown config options.
• Fix minor UX issues in the search bar.
• Fix deprecation in Docutils 0.19 frontend

pydoctor 22.7.0

• Add support for generics in class hierarchies.
• Fix long standing bugs in Class method resolution order.
• Improve the extensibility of pydoctor (more infos on extensions)
• Fix line numbers in reStructuredText xref warnings.
• Add support for twisted.python.deprecated (this was originally part of Twisted's customizations).
• Add support for re-exporting it names imported from a wildcard import.

pydoctor 22.5.1

• docutils>=0.17 is now the minimum supported version. This was done to fix crashing with AttributeError when processing type fields.

pydoctor 22.5.0

• Add Read The Docs theme, enable it with option --theme=readthedocs.
• Add a sidebar. Configure it with options --sidebar-expand-depth and --sidebar-toc-depth. Disable with --no-sidebar.
• Highlight the active function or attribute.
• Packages and modules are now listed together.
• Docstring summaries are now generated from docutils nodes:
  • fixes a bug in restructuredtext references in summary.
  • still display summary when the first paragraph is long instead of "No summary".
• The module index now uses a more compact presentation for modules with more than 50 submodules and no subsubmodules.
• Fix source links for code hosted on Bitbucket or SourceForge.
• The --html-viewsource-template option was added to allow for custom URL scheme when linking to the source code pages and lines.

pydoctor 22.4.0

• Add option --privacy to set the privacy of specific objects when default rules doesn't fit the use case.
• Option --docformat=plaintext overrides any assignments to __docformat__ module variable in order to focus on potential python code parsing errors.
• Switch to configargparse to handle argument and configuration file parsing (more infos).
• Improved performances with caching of docstring summaries.

pydoctor 22.3.0

• Add client side search system based on lunr.js.
• Fix broken links in docstring summaries.
• Add cache for the xref linker, reduces the number of identical warnings.
• Fix crash when reparenting objects with duplicate names.

pydoctor 22.2.2

• Fix resolving names re-exported in __all__ variable.

pydoctor 22.2.1

• Fix crash of pydoctor when processing a reparented module.

pydoctor 22.2.0

• Improve the name resolving algo such that it checks in super classes for inherited attributes.
• C-modules wins over regular modules when there is a name clash.
• Packages wins over modules when there is a name clash.
• Fixed that modules were processed in a random order leading to several hard to reproduce bugs.
• Intersphinx links have now dedicated markup. With the default theme, this allows to have the external intershinx links blue while the internal links are red.
• Smarter line wrapping in summary and parameters tables.
• Any code inside of if __name__ == '__main__' is now excluded from the documentation.
• Fix variables named like the current module not being documented.
• The Module Index now only shows module names instead of their full name. You can hover over a module link to see the full name.
• If there is only a single root module, index.html now documents that module (previously it only linked the module page).
• Fix introspection of functions comming from C-extensions.
• Fix that the colorizer might make Twisted's flatten function crash with surrogates unicode strings.

pydoctor 21.12.1

• Include module sre_parse36.py within pydoctor.epydoc to avoid an extra PyPi dependency.

pydoctor 21.12.0

• Add support for reStructuredText directives .. deprecated::, .. versionchanged:: and .. versionadded::.
• Add syntax highlight for constant values, decorators and parameter defaults.
• Embedded documentation links inside the value of constants, decorators and parameter defaults.
• Provide option --pyval-repr-maxlines and --pyval-repr-linelen to control the size of a constant value representation.
• Provide option --process-types to automatically link types in docstring fields (more info).
• Forked Napoleon Sphinx extension to provide google-style and numpy-style docstring parsing.
• Introduced fields warns, yields and yieldtype.
• Following google style guide, *args and **kwargs are now rendered with asterisks in the parameters table.
• Mark variables as constants when their names is all caps or if using Final annotation.

pydoctor 21.9.2

• Fix AttributeError raised when parsing reStructuredText consolidated fields, caused by a change in docutils 0.18.
• Fix DeprecationWarning, use newer APIs of importlib_resources module.

pydoctor 21.9.1

• Fix deprecation warning and officially support Python 3.10.
• Fix the literals style (use same style as before).

pydoctor 21.9.0

• Add support for multiple themes, selectable with --theme option.
• Support selecting a different docstring format for a module using the __docformat__ variable.
• HTML templates are now customizable with --template-dir option.
• Change the fields layout to display the arguments type right after their name. Same goes for variables.

pydoctor 21.2.2

• Fix positioning of anchors, such that following a link to a member of a module or class will scroll its documentation to a visible spot at the top of the page.

pydoctor 21.2.1

• Fix presentation of the project name and URL in the navigation bars, such that it works as expected on all generated HTML pages.

pydoctor 21.2.0

• Removed the --html-write-function-pages option. As a replacement, you can use the generated Intersphinx inventory (objects.inv) for deep-linking your documentation.
• Fixed project version in the generated Intersphinx inventory. This used to be hardcoded to 2.0 (we mistook it for a format version), now it is unversioned by default and a version can be specified using the new --project-version option.
• Fixed multiple bugs in Python name resolution, which could lead to for example missing "implemented by" links.
• Fixed bug where class docstring fields such as cvar and ivar are ignored when they override inherited attribute docstrings.
• Property decorators containing one or more dots (such as @abc.abstractproperty) are now recognized by the custom properties support.
• Improvements to attrs support:
  • Attributes are now marked as instance variables.
  • Type comments are given precedence over types inferred from attr.ib.
  • Support positional arguments in attr.ib definitions. Please use keyword arguments instead though, both for clarity and to be compatible with future attrs releases.
• Improvements in the treatment of the __all__ module variable:
  • Assigning an empty sequence is interpreted as exporting nothing instead of being ignored.
  • Better error reporting when the value assigned is either invalid or pydoctor cannot make sense of it.
• Added except field as a synonym of raises, to be compatible with epydoc and to fix handling of the :Exceptions: consolidated field in reStructuredText.
• Exception types and external base classes are hyperlinked to their class documentation.
• Formatting of def func(): and class Class: lines was made consistent with code blocks.
• Changes to the "Show/hide Private API" button:
  • The button was moved to the right hand side of the navigation bar, to avoid overlapping the content on narrow displays.
  • The show/hide state is now synced with a query argument in the location bar. This way, if you bookmark the page or send a link to someone else, the show/hide state will be preserved.
  • A deep link to a private API item will now automatically enable "show private API" mode.
• Improvements to the build_apidocs Sphinx extension:
  • API docs are now built before Sphinx docs, such that the rest of the documentation can link to it via Intersphinx.
  • New configuration variable pydoctor_url_path that will automatically update the intersphinx_mapping variable so that it uses the latest API inventory.
  • The extension can be configured to build API docs for more than one package.
• pydoctor.__version__ is now a plain str instead of an incremental.Version object.

pydoctor 20.12.1

• Reject source directories outside the project base directory (if given), instead of crashing.
• Fixed bug where source directories containing symbolic links could appear to be outside of the project base directory, leading to a crash.
• Bring back source link on package pages.

pydoctor 20.12.0

• Python 3.6 or higher is required.
• There is now a user manual that can be built with Sphinx or read online on Read the Docs. This is a work in progress and the online version will be updated between releases.
• Added support for Python language features:
  • Type annotations of function parameters and return value are used when the docstring does not document a type.
  • Functions decorated with @property or any other decorator with a name ending in "property" are now formatted similar to variables.
  • Coroutine functions (async def) are included in the output.
  • Keyword-only and position-only parameters are included in the output.
• Output improvements:
  • Type names in annotations are hyperlinked to the corresponding documentation.
  • Styling changes to make the generated documentation easier to read and navigate.
  • Private API is now hidden by default on the Module Index, Class Hierarchy and Index of Names pages.
  • The pydoctor version is included in the "generated by" line in the footer.
• All parents of the HTML output directory are now created by pydoctor; previously it would create only the deepest directory.
• The --add-package and --add-module options have been deprecated; pass the source paths as positional arguments instead.
• New option -W/--warnings-as-errors to fail your build on documentation errors.
• Linking to the standard library documentation is more accurate now, but does require the use of an Intersphinx inventory (--intersphinx=https://docs.python.org/3/objects.inv).
• Caching of Intersphinx inventories is now enabled by default.
• Added a Sphinx extension for embedding pydoctor's output in a project's Sphinx documentation.
• Added an extra named rst for the dependencies needed to process reStructuredText (pip install -U pydoctor[rst]).
• Improved error reporting:
  • More accurate source locations (file + line number) in error messages.
  • Warnings were added for common mistakes when documenting parameters.
  • Clearer error message when a link target is not found.
• Increased reliability:
  • Fixed crash when analyzing from package import *.
  • Fixed crash when the line number for a docstring error is unknown.
  • Better unit test coverage, more system tests, started adding type annotations to the code.
  • Unit tests are also run on Windows.

pydoctor 20.7.2

• Fix handling of external links in reStructuredText under Python 3.
• Fix reporting of errors in reStructuredText under Python 3.
• Restore syntax highlighting of Python code blocks.

pydoctor 20.7.1

• Fix cross-reference links to builtin types in standard library.
• Fix and improve error message printed for unknown fields.

pydoctor 20.7.0

• Python 3 support.
• Type annotations on attributes are supported when running on Python 3.
• Type comments on attributes are supported when running on Python 3.8+.
• Type annotations on function definitions are not supported yet.
• Undocumented attributes are now included in the output.
• Attribute docstrings: a module, class or instance variable can be documented by a following it up with a docstring.
• Improved error reporting: more errors are reported, error messages include file name and line number.
• Dropped support for implicit relative imports.
• Explicit relative imports (using from) no longer cause warnings.
• Dropped support for index terms in epytext (X{}). This was never supported in any meaningful capacity, but now the tag is gone.

This was the last major release to support Python 2.7 and 3.5.

pydoctor's Issues

two classes with the same name confuse pydoctor

If two classes are defined in a file with the same name (e.g. one defined in an 'except' block, and the other in an 'else' block), pydoctor appends a number to the end of the generated name which links to nothing.

Generated docs:
http://twistedmatrix.com/documents/10.2.0/api/twisted.web.client.html

Source:
http://twistedmatrix.com/trac/browser/tags/releases/twisted-10.2.0/twisted/web/client.py#L567

---

Imported from Launchpad using lp2gh.

• date created: 2011-03-15T06:00:21Z
• owner: habnabit
• the launchpad url was https://bugs.launchpad.net/bugs/735275

Support customization of all html templates

Originally reported as Twisted issue 3125:

Pydoctor has a directory full of templates it uses to generate html output. It would be nice if these templates could be customized somehow (other than directly editing them).

---

Imported from Launchpad using lp2gh.

• date created: 2009-08-06T18:51:47Z
• owner: exarkun
• the launchpad url was https://bugs.launchpad.net/bugs/410008

pydoctor's handling of duplicate names needs a rethink

Originally reported as Twisted issue 2621:

There are several cases, some of which get quite tricky. This is not an exhaustive list, but some examples are:

def foo(): pass
def foo(): pass

class B: pass
class B(B): pass

if quux:
def foo(): pass
else:
def foo(): pass

---

Imported from Launchpad using lp2gh.

• date created: 2009-08-06T18:48:42Z
• owner: exarkun
• the launchpad url was https://bugs.launchpad.net/bugs/410001

line-spanning epytext markup generates an error

If some epytext markup with curlies spans multiple lines, pydoctor causes an epytext error to be emitted. However, using epydoc directly does not result in the same error, and epytext documentation suggests that spanning multiple lines is okay.

---

Imported from Launchpad using lp2gh.

• date created: 2008-05-22T19:57:02Z
• owner: exarkun
• the launchpad url was https://bugs.launchpad.net/bugs/234120

methods inherited via more than one class are documented more than once

See for example http://twistedmatrix.com/documents/9.0.0/api/twisted.internet.interfaces.IReadWriteDescriptor.html

I have this vague memory that there is code that's supposed to suppress the repeated documentation, but it clearly isn't working.

---

Imported from Launchpad using lp2gh.

• date created: 2010-02-21T22:57:04Z
• owner: mwhudson
• the launchpad url was https://bugs.launchpad.net/bugs/525521

implemented interfaces are not shown in subclasses

Looking at http://twistedmatrix.com/documents/current/api/twisted.protocols.amp.AMP.html I expect to see IBoxSender, IProtocol, IResponderLocator, and IBoxReceiver. Instead I have to click around in the hierarchy to see everything. It'd be great to have one list, especially since private utility superclasses and mixins often do the implements() themselves.

---

Imported from Launchpad using lp2gh.

• date created: 2011-10-29T22:55:16Z
• owner: glyph
• the launchpad url was https://bugs.launchpad.net/bugs/883678

make a function's parameters actual system objects

This will make things more consistent and allow linking to them.

---

Imported from Launchpad using lp2gh.

• date created: 2012-03-20T23:19:44Z
• owner: mwhudson
• the launchpad url was https://bugs.launchpad.net/bugs/960709

an interface's attributes should be included in an implementations documentation

If an interface defines attributes and an implementation does not provide its own documentation, the interface's documentation should be included in the implementations page.

---

Imported from Launchpad using lp2gh.

• date created: 2012-03-20T23:18:45Z
• owner: mwhudson
• the launchpad url was https://bugs.launchpad.net/bugs/960708

epylint

I'd like a tool that I can run which will quickly validate as much epytext as possible. In the vein of pyflakes or pep8.py, it doesn't have to catch everything, as long as it can catch a few common things quickly. Thanks to those tools providing real-time feedback in the background of my editor, I pretty much never type NameErrors any more, and I rarely get spacing wrong, but I still make pydoctor syntax errors all the time.

Pretty much everybody's editor has a persistent python interpreter nowadays, so this could be a sidecar process that hangs out for a while and keeps some state around, if necessary, as long as it looks like it's just a command-line tool on the front end.

---

Imported from Launchpad using lp2gh.

• date created: 2012-03-23T04:13:53Z
• owner: glyph
• the launchpad url was https://bugs.launchpad.net/bugs/962767

__all__ no longer works

Something about http://bazaar.launchpad.net/~mwhudson/pydoctor/dev/revision/569 or http://bazaar.launchpad.net/~mwhudson/pydoctor/dev/revision/570 completely broke all aliasing for me. Rolling back fixes it. Do a basic

pydoctor --add-package .../twisted --make-html

and have a look at, e.g., twisted.internet.ssl.

This is what it should look like, for reference:

http://twistedmatrix.com/documents/10.2.0/api/twisted.internet.ssl.html

---

Imported from Launchpad using lp2gh.

• date created: 2011-03-21T08:42:31Z
• owner: glyph
• the launchpad url was https://bugs.launchpad.net/bugs/739223

document that properties are not supported

I've just spent the better part of a day figuring out why pydoctor refused to render my property in new twisted code while epydoc did so just fine, until I figured out that pydoctor doesn't know what properties are and prefers to document them like ivars (possibly read-only)

It'd be cool if the "how to use pydoctor" page mentioned this.

---

Imported from Launchpad using lp2gh.

• date created: 2009-09-07T20:54:38Z
• owner: lvh
• the launchpad url was https://bugs.launchpad.net/bugs/425939

nevowhtml needs tests

Originally reported as Twisted ticket 1642:

Really really really really.

---

Imported from Launchpad using lp2gh.

• date created: 2009-08-06T18:44:48Z
• owner: exarkun
• the launchpad url was https://bugs.launchpad.net/bugs/409996

unittest helpers(?) for verifying a package has valid docstrings

It would be neat if there was some way of having the testsuite verify that the syntax of all docstrings, etc is valid - without generating all the output.

I might have a look at this myself, though hints as how to do this would be much appreciated.

---

Imported from Launchpad using lp2gh.

• date created: 2011-03-26T15:49:20Z
• owner: jelmer
• the launchpad url was https://bugs.launchpad.net/bugs/743185

pydoctor should be able to ignore 'test' directories

One common layout for python source trees is to put unit tests in a 'test' subdirectory of the code being tested. It would be nice to have a way to ignore these subdirectories when generating documentation.

epydoc has an --exclude option that can be used for this.

---

Imported from Launchpad using lp2gh.

• date created: 2011-05-26T04:36:26Z
• owner: duncf
• the launchpad url was https://bugs.launchpad.net/bugs/788472

interface multiple inheritance results in some missing documentation

The documentation generated for an interface which subclasses two other interfaces seems only to include documentation for methods inherited from one of the subclassed interfaces. For example, see http://twistedmatrix.com/documents/current/api/twisted.internet.interfaces.IReadWriteDescriptor.html which includes doWrite but not doRead.

---

Imported from Launchpad using lp2gh.

• date created: 2008-12-11T22:19:00Z
• owner: exarkun
• the launchpad url was https://bugs.launchpad.net/bugs/307298

Does Not Work On PyPy

Appears that a recent change introduced a use of the magic builtins. Should be using the builtin module instead.

---

Imported from Launchpad using lp2gh.

• date created: 2012-03-27T13:57:00Z
• owner: exarkun
• the launchpad url was https://bugs.launchpad.net/bugs/966234

pydoctor setup enhancements

Originally reported as Twisted issue 3955:

This patch enables doing sdist, bdist_rpm on pydoctor

---

Imported from Launchpad using lp2gh.

• date created: 2009-08-06T18:57:15Z
• owner: exarkun
• the launchpad url was https://bugs.launchpad.net/bugs/410013

zope.interface.Attribute docstrings should be treated as @ivar declarations, or something similar.

Right now if you define a zope.interface.Attribute, its docstring seems to be ignored. Since this is the preferred way to actually document zope.interface.Interfaces, it would be nice if the documentation showed up as if you had placed it in an @ivar in the interface class's docstring.

---

Imported from Launchpad using lp2gh.

• date created: 2009-12-01T21:23:58Z
• owner: glyph
• the launchpad url was https://bugs.launchpad.net/bugs/491041

private stuff should be private-er

There is some visible indication that _-prefixed names are private when looking at the index, but when looking at the documentation for individual methods or functions, the text is on the same blue background.

Better would be a consistent style that always showed private stuff, in any context, as grey-on-grey so it's clear.

Also, the grey-on-grey doesn't ever have a textual explanation. There should be some text saying "This method is for maintainers only" and a link to a page that explains what it means to call a private method.

Finally, private methods should all be hidden by default, and shown via a "show private methods and bases" button (assuming the browser has JavaScript).

---

Imported from Launchpad using lp2gh.

• date created: 2012-05-09T19:50:53Z
• owner: glyph
• the launchpad url was https://bugs.launchpad.net/bugs/997295

references to builtins

There are lots of C{str} and C{int} littered all over @type and @param statements in Twisted. I'd really prefer these to be more properly expressed as L{str} and L{int}. Similarly, I'd like to express @raises statements with e.g. L{OSError}.

This doesn't need any fancy cross-reference stuff; I would like to be able to refer to arbitrary Python stdlib modules this way as well, but builtins and the standard exception hierarchy are important enough that I wouldn't mind if they all simply linked to a static 'python builtins' page included with the generated docs.

---

Imported from Launchpad using lp2gh.

• date created: 2011-01-02T21:56:34Z
• owner: glyph
• the launchpad url was https://bugs.launchpad.net/bugs/696633

pydoctor assumes all docs are in the same directory

Originally reported as Twisted issue 1886.

This has two bad effects:

it's hard for packagers to package pydoctor's output for the different bits of twisted because if (say) twisted web's docs are in /usr/share/doc/twisted-web/ they should link to twisted core's docs in /usr/share/doc/twisted-core/ and this isn't currently possible.

Similarly, the pydoctor output for nevow should link to the pydoctor output for twisted, if it knows where it is.

I think this can be addressed by loading a bunch of systems that know the base url of their documentation, and having the documentation generator look in more than just the system being generated when trying to link to something.

Having written all this out, I don't think it should be too hard...

---

Imported from Launchpad using lp2gh.

• date created: 2009-08-06T18:46:07Z
• owner: exarkun
• the launchpad url was https://bugs.launchpad.net/bugs/409998

release on pypi

Could you also put the releases on pypi?

---

Imported from Launchpad using lp2gh.

• date created: 2011-04-05T14:42:20Z
• owner: roland-micite
• the launchpad url was https://bugs.launchpad.net/bugs/751482

some invalid epytext markup is not reported as such

If a function's docstring includes epytext markup documenting a parameter which the function does not have, pydoctor doesn't seem to consider this an error. It generates output which includes the documentation for the parameter without emitting a warning or error.

eg

exarkun@charm:$ mkdir foo
exarkun@charm:$ touch foo/init.py
exarkun@charm:$ cat > foo/foo.py
def bar(baz):
"""
@param quux: foo
"""
exarkun@charm:$ pydoctor --make-html --add-package foo/
adding directory /home/exarkun/foo
2/2 modules processed 0 warnings
WARNING: guessing foo for project name
writing html to apidocs using pydoctor.nevowhtml.writer.NevowWriter
starting ModuleIndexPage ... took 0.038186s
starting ClassIndexPage ... took 0.002309s
starting IndexPage ... took 0.007698s
starting NameIndexPage ... took 0.007809s
starting UndocumentedSummaryPage ... took 0.003291s
3/3 pages written
exarkun@charm:~$

---

Imported from Launchpad using lp2gh.

• date created: 2008-10-23T15:11:37Z
• owner: exarkun
• the launchpad url was https://bugs.launchpad.net/bugs/288181

Only first value of multi-value parameter tilde-expanded

Originally reported as Twisted issue 2623:

This is due to the fact that the config file parsing code invokes os.expanduser before splitting on commas.

---

Imported from Launchpad using lp2gh.

• date created: 2009-08-06T18:50:01Z
• owner: exarkun
• the launchpad url was https://bugs.launchpad.net/bugs/410004

@vars and @ivars can't seem to be link targets

L{SOME_CONSTANT} and L{MyClass.myAttributeWithANiceSplatIVar} both fail. And they report as being invalid link targets. That sucks.

---

Imported from Launchpad using lp2gh.

• date created: 2011-02-04T06:34:32Z
• owner: glyph
• assignee: mwhudson
• the launchpad url was https://bugs.launchpad.net/bugs/712919

need a saner way to declare the mapping between filesystem paths and Python module/package names

As it stands, it's a real pain to get pydoctor to document, e.g., bzr plugins, due to it's strong preconcieved notions about how to go from realpath() to Python package/module name, with the "prependedpackage" thing sorta tacked on...

---

Imported from Launchpad using lp2gh.

• date created: 2009-08-04T20:56:13Z
• owner: naesten
• the launchpad url was https://bugs.launchpad.net/bugs/409048

pydoctor only seems to work on subversion checkouts

pydoctor discovers some portion of a path to use to use when computing source hrefs. It does this by looking for the base of a subversion working copy and assuming the path segments from the base up to the package directory are required as part of the links it generates.

I'd like to use pydoctor on an export or an unpacked release tarball. One way to do this is to make the package root explicit as an option.

---

Imported from Launchpad using lp2gh.

• date created: 2008-04-01T19:03:51Z
• owner: exarkun
• assignee: mwhudson
• the launchpad url was https://bugs.launchpad.net/bugs/210410

Analyze class assignments outside of their class scope

Pydoctor does not generate documentation for classes wrapped by SWIG (www.swig.org). SWIG creates classes like this:

class event(object):
    thisown = _swig_property(lambda x: x.this.own(), lambda x, v: x.this.own(v), doc='The membership flag')
    __repr__ = _swig_repr
    def __init__(self, _args, *_kwargs):
        _events.event_swiginit(self,_events.new_event(_args, *_kwargs))
    __swig_destroy__ = _events.delete_event
event.loop_once = new_instancemethod(_events.event_loop_once,None,event)
event.loop_wait = new_instancemethod(_events.event_loop_wait,None,event)
event_swigregister = _events.event_swigregister
event_swigregister(event)

pydoctor will in this case only document event.__init__(). It would be nice if it would also document event.loop_once and event.loop_wait.

Jelmer Vernooij - http://samba.org/~jelmer/
Jabber:

---

Imported from Launchpad using lp2gh.

• date created: 2007-12-29T18:27:10Z
• owner: jelmer
• assignee: mwhudson
• the launchpad url was https://bugs.launchpad.net/bugs/179253

Add support for rendering @since

epytext has a @since field which indicates when an API was first introduced. It'd be great to have pydoctor render this information somehow (at least without saying "unhandled field").

---

Imported from Launchpad using lp2gh.

• date created: 2008-09-08T22:23:33Z
• owner: exarkun
• assignee: mwhudson
• the launchpad url was https://bugs.launchpad.net/bugs/267943

pydoctor page should point people to Launchpad

http://codespeak.net/~mwh/pydoctor/ has no reference to launchpad, and says:

Where do I report bugs?
There is a pydoctor component in the trac instance on twistedmatrix.com. Assign to mwh.
This should be updated to point to launchpad, since any bugs in trac on twistedmatrix.com are being manually closed and redirected here.

---

Imported from Launchpad using lp2gh.

• date created: 2009-08-10T20:29:24Z
• owner: davidf
• the launchpad url was https://bugs.launchpad.net/bugs/411628

doesn't support constants

integer and string contents are ignored at the moment, it'd be nice if they were documented. This would help with bug 410000 and with C inspection (though it's also possible to ignore explicitly constants of course).

Does this seem like a reasonable feature, and would implementing it this just be a matter of adding another subclass of pydoctor.model.Documentable?

---

Imported from Launchpad using lp2gh.

• date created: 2010-12-05T03:40:14Z
• owner: jelmer
• the launchpad url was https://bugs.launchpad.net/bugs/685376

pydoctor doesn't try to import the doc parser until after reading all the input modules

For example, if I tried to generate bzrlib API docs using this bzr.cfg:

projectname: bzrlib
packages: bzrlib
htmloutput: bzrlibapi
docformat: reStructuredText

... I wouldn't get an error message about not being able to import reStructuredText until after pydoctor had already looked at all the modules in bzrlib, which can take a bit. It's very frustrating to have it look like something is working only to fail for such an easy-to-check reason >10s in.

(Incidentally, what configuration do you use to generate the bzrlib API docs? I didn't find a .cfg file in either the bzr or pydoctor source trees.)

---

Imported from Launchpad using lp2gh.

• date created: 2009-04-10T19:32:25Z
• owner: naesten
• the launchpad url was https://bugs.launchpad.net/bugs/359242

pydoctor throws AttributeError

pydoctor -c doc/pydoctor.cfg
/usr/lib/pymodules/python2.6/pydoctor/model.py:6: DeprecationWarning: the sets module is deprecated
import sets
adding directory otfbot
findImportStars
74 / 74 modules parsed
extractDocstrings
74 / 74 modules parsed 13 warnings
finalStateComputations
Traceback (most recent call last):
File "/usr/bin/pydoctor", line 5, in
main(sys.argv[1:])
File "/usr/lib/pymodules/python2.6/pydoctor/driver.py", line 247, in main
f()
File "/usr/lib/pymodules/python2.6/pydoctor/astbuilder.py", line 352, in finalStateComputations
self._finalStateComputations()
File "/usr/lib/pymodules/python2.6/pydoctor/twisted.py", line 165, in _finalStateComputations
super(TwistedASTBuilder, self)._finalStateComputations()
File "/usr/lib/pymodules/python2.6/pydoctor/astbuilder.py", line 235, in _finalStateComputations
self.recordBasesAndSubclasses()
File "/usr/lib/pymodules/python2.6/pydoctor/astbuilder.py", line 243, in recordBasesAndSubclasses
o.subclasses.append(cls)
AttributeError: 'Module' object has no attribute 'subclasses'

---

Imported from Launchpad using lp2gh.

• date created: 2010-08-06T22:55:09Z
• owner: allo
• the launchpad url was https://bugs.launchpad.net/bugs/614605

port to the ast module

pydoctor should really use the now-standard ast module, not the old, crufy & deprecated compiler package.

No idea how much work this is.

---

Imported from Launchpad using lp2gh.

• date created: 2012-03-25T21:32:35Z
• owner: mwhudson
• the launchpad url was https://bugs.launchpad.net/bugs/964804

links to stdlib modules

L{socket.AF_INET} could link to http://docs.python.org/library/socket.html#socket.AF_INET.

L{os.path.join} could link to http://docs.python.org/library/os.path.html#os.path.join

This link scheme isn't always accurate, but it's pretty consistent and it's accurate often enough to be highly useful. pydoctor could find the 'os' and 'socket' modules programmatically, it doesn't need to have a builtin list, and all the stdlib stuff goes together, so by using one stdlib module's file as reference, it could be quickly determined which things could be linked to in this way.

---

Imported from Launchpad using lp2gh.

• date created: 2012-03-22T00:14:39Z
• owner: glyph
• the launchpad url was https://bugs.launchpad.net/bugs/961797

It'd be nice if private classes and methods were rendered in a different way

For example, with a color scheme that makes them stand out less, and keeping them at the bottom of the listing.

---

Imported from Launchpad using lp2gh.

• date created: 2008-03-30T03:53:27Z
• owner: radix
• assignee: mwhudson
• the launchpad url was https://bugs.launchpad.net/bugs/209077

--introspect-c-modules loads foreign extension modules

If I build Twisted's extension modules using PyPy and then run pydoctor using CPython, passing the --introspect-c-modules flag, pydoctor fails with this exception:

Traceback (most recent call last):
File "/home/exarkun/Projects/pydoctor/trunk/bin/pydoctor", line 12, in
sys.exit(main(sys.argv[1:]))
File "/home/exarkun/Projects/pydoctor/trunk/pydoctor/driver.py", line 318, in main
system.addPackage(path, prependedpackage)
File "/home/exarkun/Projects/pydoctor/trunk/pydoctor/model.py", line 618, in addPackage
self.addPackage(fullname, package)
File "/home/exarkun/Projects/pydoctor/trunk/pydoctor/model.py", line 620, in addPackage
self.addModuleFromPath(package, fullname)
File "/home/exarkun/Projects/pydoctor/trunk/pydoctor/model.py", line 637, in addModuleFromPath
(suffix, mode, type))
ImportError: /home/exarkun/Projects/Twisted/trunk/twisted/runner/portmap.pypy-14.so: undefined symbol: _Py_InitPyPyModule

It seems the logic for deciding whether a .so should be loaded as an extension or not needs a little more smarts.

---

Imported from Launchpad using lp2gh.

• date created: 2012-05-09T18:57:16Z
• owner: exarkun
• the launchpad url was https://bugs.launchpad.net/bugs/997272

pydoctor should hide all private names by default

https://bugs.launchpad.net/pydoctor/+bug/209077 was a step forward, but it was not consistently applied.

For example, the "instance variables" section on http://twistedmatrix.com/documents/10.1.0/api/twisted.internet.endpoints.TCP4ClientEndpoint.html still doesn't render the private instance variables differently.

While displaying private names is useful to maintainers, the main public documentation really shouldn't show the private names at all, and should instead have a link that says "show all private names".

---

Imported from Launchpad using lp2gh.

• date created: 2010-07-20T22:19:35Z
• owner: glyph
• the launchpad url was https://bugs.launchpad.net/bugs/607987

pydoctor.epydoc2stan.link escapes urlprefix

When using moresystems with a URL prefix that starts with 'http://', the colon gets escaped. This is because of the implementation of pydoctor.epydoc2stan.link, which escapes URL prefix.

---

Imported from Launchpad using lp2gh.

• date created: 2012-05-09T12:22:48Z
• owner: ralphmeijer
• assignee: mwhudson
• the launchpad url was https://bugs.launchpad.net/bugs/997079

@type fields render with trailing whitespace

@type fields in docstrings are rendered to HTML with trailing whitespace, which looks annoying in generated documentation when the value is placed in parentheses at the end of a paragraph. In the HTML source, it looks like this whitespace is a newline.

---

Imported from Launchpad using lp2gh.

• date created: 2012-01-05T09:26:05Z
• owner: jerith
• the launchpad url was https://bugs.launchpad.net/bugs/912168

introspection for C modules

affects pydoctor

It would be really nice if pydoctor could support introspection next to
parsing of Python code. I work with a lot of projects that have Python
code that is partially in C and partially in Python itself, and this is

the only thing blocking us from adopting pydoctor atm.

Jelmer Vernooij - http://samba.org/~jelmer/
Jabber:

---

Imported from Launchpad using lp2gh.

• date created: 2009-01-28T02:30:43Z
• owner: jelmer
• the launchpad url was https://bugs.launchpad.net/bugs/322159

how do you direct people's attention to the methods that count

Especially if the changes I recommended in https://bugs.launchpad.net/pydoctor/+bug/997295 are made, it should be a lot easier to see the public methods of private base classes, without having to be aware that the base class is there or private. It's a bit confusing to have to click into apparently private documentation to see important bits of functionality.

For example, on http://twistedmatrix.com/documents/current/api/twisted.python.filepath.FilePath.html, you can see lots of irrelevant methods (and you would see private methods, if there were any) on FilePath before seeing core functionality like walk() which happens to be defined on _PathHelper.

Maybe the thing to do here is just to emphasize the "implements interfaces" section a bit more and display the whole interface docstring on each method rather than just the somewhat ambiguous "from" link.

---

Imported from Launchpad using lp2gh.

• date created: 2012-05-09T20:03:05Z
• owner: glyph
• the launchpad url was https://bugs.launchpad.net/bugs/997302

--add-package . --make-html

affects /products/pydoctor

pydoctor will crash when it is run on a top-level directory that
contains python source code. For example, running 'pydoctor
--add-package . --make-html' in a directory with python source code will
cause mediumName() in nevowhtml.pages to crash because it is trying to
sanitize "..name"

(shown to Michael IRL yesterday, just reporting here so it isn't lost)

---

Imported from Launchpad using lp2gh.

• date created: 2007-05-27T14:33:10Z
• owner: jelmer
• assignee: mwhudson
• the launchpad url was https://bugs.launchpad.net/bugs/117194

port to twisted.web.template

Noone cares about nevow any more, and now twisted has its own templating library, based on what was in nevow.

Unfortunately t.w.template doesn't support patterns, which pydoctor makes excessive usage of, so this is not trivial.

---

Imported from Launchpad using lp2gh.

• date created: 2012-03-25T21:31:38Z
• owner: mwhudson
• the launchpad url was https://bugs.launchpad.net/bugs/964803

"from .module import foo" style imports not supported

Running "pydoctor foo" on the following structure gives "foo.quux:0 invalid ref to baz" and does not link "baz" in the generated HTML page for "foo.quux".

foo/init.py
1:# blank

foo/bar/init.py
1:from .other import baz

foo/bar/other.py
1:def baz():
2: pass

foo/quux.py
1:"L{baz}"
2:from .bar import baz

---

Imported from Launchpad using lp2gh.

• date created: 2010-11-18T01:52:29Z
• owner: mwhudson
• the launchpad url was https://bugs.launchpad.net/bugs/676784

pydoctor should have the equivalent of __docformat__ = "restructuredtext en"

Originally reported as Twisted issue 2187:

epydoc has a epytext variant that's valid restructured text. You can either set docformat = "restructuredtext en" in your module, or pass --docformat restructuredtext to epydoc to use it.

pydoctor should support these as well, so that it can be a better drop-in replacement for epydoc. For instance, bzr's source uses restructuredtext format epytext, so pydoctor isn't hugely useful with it.

---

Imported from Launchpad using lp2gh.

• date created: 2009-08-06T18:47:24Z
• owner: exarkun
• the launchpad url was https://bugs.launchpad.net/bugs/410000

"packages" .cfg field only seems able to hold one package

In the absense of examples which used more than one package in the packages .cfg field, I treid both:

packages: bzr bzrlib

and:

packages: bzr, bzrlib

and neither syntax worked.

---

Imported from Launchpad using lp2gh.

• date created: 2009-04-10T19:41:20Z
• owner: naesten
• the launchpad url was https://bugs.launchpad.net/bugs/359253

Use first paragraph instead of first line for method summary

There are cases where the summary doesn't fit in one line to be useful. An example would be

http://twistedmatrix.com/documents/11.0.0/api/twisted.application.service.ServiceMaker.html

The short summary in the green box for makeService().

I proposed a patch to mask the newline but exarkun refused it as he feels, it should be fixed inside of pydoctor so it works everywhere.

My idea would be to use the first paragraph instead of the first line for this summary and I'd also write a patch if others would support that idea.

---

Imported from Launchpad using lp2gh.

• date created: 2011-06-26T17:09:34Z
• owner: hyneks
• the launchpad url was https://bugs.launchpad.net/bugs/802223

pydoctor should put the module name at the beginning of the document title

Originally reported as Twisted issue 3343:

I've been working on Twisted-based code recently, and I've been consulting the online API references quite a bit. Right now, I have 18 tabs open, all next to each other, all displaying 'API docs for "twisted...', which makes it somewhat difficult to find the particular section of the documentation I'm looking for.

It would be convenient if pydoctor's HTML output mode formatted titles more like:

twisted.python.log API docs

...or even better, re-format the information in the

on every page:

t.p.log Module docs

---

Imported from Launchpad using lp2gh.

• date created: 2009-08-06T18:55:21Z
• owner: exarkun
• the launchpad url was https://bugs.launchpad.net/bugs/410012

Show aliases for functions and methods

If a function or method is assigned alternate names ("func2 = func1"), pydoctor should list those aliases in the function or method documentation.

---

Imported from Launchpad using lp2gh.

• date created: 2011-01-12T21:08:25Z
• owner: gxti
• the launchpad url was https://bugs.launchpad.net/bugs/702127