Epydoc: API Documentation Extraction in Python
Epydoc: API Documentation Extraction in Python Edward Loper Department of Computer and Information Science University of Pennsylvania, Philadelphia, PA 19104-6389, USA Abstract • All API documentation must be written (and read) in plaintext. Epydoc is a tool for generating API documentation for Python modules, based on their docstrings. It • There is no easy way to navigate through the supports several output formats (including HTML API documentation. and PDF), and understands four different markup • The API documentation is not searchable. languages (Epytext, Javadoc, reStructuredText, and plaintext). A wide variety of fields can be used to • A library's API documentation cannot be viewed supply specific information about individual objects, until that library is installed. such as descriptions of function parameters, type sig- natures, and groupings of related objects. • There is no mechanism for documenting vari- ables. 1 Introduction • There is no mechanism for \inheriting" docu- mentation (e.g. in a method that overrides its Documentation is a critical contributor to a library's base class method). This can lead to dupli- usability. Thorough documentation shows new users cation of documentation, which can often get how to use a library; and details the library's specific out-of-sync. behavior for advanced users. Most libraries can ben- efit from three different types of documentation: tu- Epydoc is a tool that automatically extracts a li- torial documentation, which introduces new users to brary's docstrings, and uses them to create API doc- the library by showing them how to perform typical umentation for the library in a variety of formats. tasks; reference documentation, which explains the li- Epydoc addresses all of these limitations: brary's overall design, and describes how the different • pieces of the library fit together; and API documenta- Docstrings can be written in a variety of markup tion, which describes the individual objects (classes, languages, including reStructuredText and Javadoc.
[Show full text]