Frequently Asked Questions

A Python docstring is a string, and is interpreted like any other string. In particular, Python interprets "\n" as a newline, "\t" as a tab, etc. If you want to include backslashes in your docstring (e.g. because you want to talk about file paths, regular expressions, or escaped characters), you should use a raw string. E.g.:

>>> f(x):
...     r"""
...     Return true if x matches the regexp '\w+\s*\w+'.
...     """
    

Epydoc can extract documentation about objects from two different sources: inspection (importing the objects and examining them programmatically) and parsing(reading and extracting information from the objects' Python source code). Furthermore, epydoc can combine documentation information obtained from these two sources. This is important because each source has its own advantages and disadvantages with respect to the other. In particular:

• Introspection gives epydoc an accurate picture of what modules will look like programmatically. In particular, some modules actively modify the namespace they define, or use various "magic" techniques to alter their public interface. Using introspection gives epydoc an accurate picture of what these modified interfaces look like.
• If a module has dependencies that are not met on the current system, then it may not be possible to import and introspect it; but the parser can still examine its contents.
• If importing a module has significant side effects, then introspecting it might not be desirable; but the parser can still examine its contents.
• If a module is not trusted, then it might not be desirable to import it; but the parser can still examine its contents.
• By parsing a module, we can find "pseudo-docstrings" and "docstring comments," which are unavailable via introspection. In particular, this makes it possible to associate API documentation with variables.
• Introspection can give information about builtin and extension modules, which would be unavailable to a python source code parser. This includes builtin or extension bases for pure Python classes.
• By parsing a module, we can easily determine which values were imported, and where they were imported from. This information is not available via introspection.

The --parse-only option instructs epydoc to only get documentation information from parsing (and not from introspection.) You should use this option if:

• The project you are documenting contains untrusted source code.
• The project you are documenting has dependencies which are not met (e.g., documenting windows-specific code on a non-windows machine).
• You wish to document a module where importing the module would have undesired side effects.

The CSS stylesheet can be used to modify the colors, fonts, and styles that are used by epydoc. You can specify your own CSS stylesheet using the --css option. (To generate the default stylesheet, simply run epydoc on a small module.)

If your objections have to do with the actual layout of the pages, then I'd be happy to hear your suggestions for improving it; but I'm fairly happy with the layout, and probably won't make changes unless I agree that they improve the appearance significantly.

Currently, the LaTeX output, and derived output formats, are not very customizable. If you have suggestions for improving the appearance of the generated output, please let me know.

Try the following options:

Also, note that including graphs in the output can slow epydoc down significantly.