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

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.

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.

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'

Try the following options:

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

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.

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.

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.