Frequently Asked Questions

Contents

Docstrings & Docstring Markup

Extracting Documentation

Generated Output

Development of Epydoc

Ask a new question...

Docstrings & Docstring Markup

Q: Why does epydoc get confused when I include a backslash in a docstring?

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+'.
...     """
    

Q: Which markup language do you recommend?

For many modules, epytext works well: it is very lightweight, so it won't get in the way; but it lets you mark important information about objects. If you would like to use a more expressive markup language, then we recommend using reStructuredText, which is easy to write, easy to read, and has support for a very wide array of constructs.

Q: reStructuredText is capitalized weirdly; Javadoc has too much caffeine; and Epydoc just isn't cool enough. Will you add support for my favorite markup language xyz?

No, but you can! See the documentation for the function register_markup_language(), which can be used to register new markup languages. If you add support for a new markup language, and believe that others might like to use it, please contribute it back to epydoc!

Q: Is there a way to define a new field?

You can add new fields that describe simple metadata using the @newfield field. See the documentation for fields for more information.

Q: Why does epydoc render one of my epytext-formatted docstrings as plaintext?

Since epytext is used as the default markup language for epydoc, it needs to be very conservative -- it will be used to display many docstrings that are not explicitly written using epytext, and it needs to display those docstrings in a readable way. Therefore, whenever epytext encounters a docstring that doesn't strictly conform to the epytext markup language, it renders it as plaintext.

If you expect one of your docstrings to be processed using epytext, but it gets rendered as plaintext, then the docstring most likely contains one or more markup errors. Run epydoc with the -v option to see markup errors, and check for an error in the docstring in question. Once you fix the markup errors, the docstring will be processed as expected.

Extracting Documentation

Q: Why does epydoc use both introspection and parsing? Wouldn't one or the other be sufficient?

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.

Q: When should I use --parse-only?

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.

Q: How can I test whether my program is being documented by epydoc?

Some programs or libraries need to take special actions when being documented by epydoc. E.g., you might want your code to skip certain set-up actions if it's just being imported to be documented. You can test whether epydoc is currently running by testing whether 'epydoc' is in sys.modules:

  >>> import sys.modules
  >>> if 'epydoc' in sys.modules:
  ...     print 'Epydoc is running'

Q: I'm documenting a large project. How can I make epydoc go faster?

Try the following options:

−−no-sourcecode Don't generate pages containing source code with syntax highlighting.
−−no−private Don't generate documentation for private objects.
−−introspect−only or −−parse−only Extract information about objects using introspection or parsing (but not both). This may decrease the amount of information that epydoc can extract from your project.
−−docformat=plaintext Format docstrings as plaintext, instead of epytext. (Docstrings will be rendered verbatim).

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

Generated Output

Q: How can I change the appearance of the HTML output?

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.

Q: How can I change the appearance of the LaTeX, Postscript, or PDF output?

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.

Q: How can I include graphs in the generated output?

Epydoc can automatically generate a variety of graphs, including class tress, package trees, uml class graphs, and import graphs. These graphs can be included in one of two ways:

Graph generation requires the Graphviz package. If the dot executable is not on the path, then its location should be specified using the --dotptah option.

Q: How can I exclude a specific object from the generated documentation?

Use the @undocumented field. See the documentation for fields for more information.

Q: Why does epydoc add "-module" and "-class" to the names of the HTML pages it generates?

There are two reasons. First, this ensures that the names of module and class pages do not conflict with the names of existing special pages. For example, if a module were named "index", then naming its documentation page "index.html" would interfere with the use of that name for the documentation's main page. Second, it is possible to define a package where a module and a class share the same name. In those cases, this naming scheme ensures that the two object's pages do not conflict.

Q: Is there a way to link to the API documentation for objects using a simple URL based on the object's dotted name?

Epydoc creates a page named "redirect.html" that uses javascript to automatically convert dotted names to the corresponding URLs. In particular, loading the page "redirect.html#dotted.name" will automatically redirect the user's browser to the URL for the object whose dotted name is dotted.name. For example, a link to <redirect.html#epydoc.cli.HELP_TOPICS> automatically redirects the browser to <epydoc.cli-module.html#HELP_TOPICS>. The redirect page can be used for any object documented by epydoc, including modules, classes, functions, varaibles, properties, etc.

Q: Why are some values listed in the details section, but not others?

By default, epydoc will only list a value in the details section if there's additional information beyond what's listed in the summary section. For example, if you define a function but don't give it a docstring, then all API information about that function can be shown in the summary table, so no details entry will be created for it. This helps keep the generated documentation consise, and the information density high. However if you prefer, the command-line option "--redundant-details" can be used to tell epydoc to display all values in the details lists, even if all info about them is already provided by the summary table. The corresponding config file option is redundant-details. This option was added in svn revision 1613, and is not yet available in the most recent release.

Development of Epydoc

Q: I've found a bug in epydoc! Where should I report it?

Use the Sourceforge bug tracker to report bugs. If you want to hear back when we fix it, be sure to either log in to Sourceforge, or include your email address in the bug report.

Q: I'd like to help! What can I do?

If there are any features that you want to add to Epydoc, we'd be happy to accept patches. Patches should be submitted with the Sourceforge patch tracker (be sure to describe what your patch does!). If you plan to make several changes, we could also add you as a developer on Sourceforge. Email me if you're interested.

For a list of additions that we'd like to make to Epydoc, see the todo list in the Epydoc reference documentation; or the SourceForge feature request tracker and bug tracker