TITLE OF PAPER: Epydoc, an API documentation generation tool URL OF PRESENTATION: _URL_of_powerpoint_presentation_ PRESENTED BY: Edward Loper REPRESENTING: _name_of_the_company_they_represent_ CONFERENCE: PyCON 2004 DATE: 20040325 LOCATION: _venue_and_room_in_venue_ -------------------------------------------------------------------------- REAL-TIME NOTES / ANNOTATIONS OF THE PAPER: {If you've contributed, add your name, e-mail & URL at the bottom} Epydoc extracts and organizes API documentation for a Python library Extracts docs from Docstrings introspection output HTML (and other stuff) API Documentation (in general) explains how a library works, how to use Writing API documentation API docs are tightly coupled with source (so it can be difficult to keep it in sync with the implementation Solution: Keep API documentation in docstrings a docstring is a string constant at the top of an object's definition, this is available via inspection Documentation Extraction It's convenient to write API docs in the source code But it's not convient to read them there. Solution: use a tool that: extracts API documentation from source code convert them to an easy to read format Avoiding Duplication multiple object can share the same documentation overriden methods interface implementations wrapper functions but duplicating their documentation is problematic it clutters the source code it's easy for different copies to get out of sync Epydoc provides two mechanisms to avoid duplication: documentation inheritance: a method without a docstring will inherit it's parent docstring @include directive (pulls in from other location) Epydoc's Output Epydoc currently supports two output formats webpage (*HTML) Document (LaTeX/DVI/PS/PDF) In the works: manpage left side is a TOC frame - top of frame is list of modules - bottom of frame is selected module top is navigation bar - left side is links to top level pages - includes breadcrumb trail - right side shows links to private view status and frames toggle single page for each module and class Docstring markup Why use markup in docstrings? More Expressive power display medium independence Epydoc supports 4 markup languages: Epytext reStructuredText Javadoc Plaintext Markup language declaration: __docformat__ == "restructuredtext" Docstring Markup: Epytext A lightweight markup language Easy to write Easy to read as plaintext Easy to understand A conservative markup language uses common conventions for basic formatting if encounters unknown formatting, it falls back to verbatim text Default mark up language Docstring markup: reStructuredText An easy-to-read, WYSIWYG markup language support a large and growing set of constructions Quickly becoming a standard markup language for python docs currently used for PEPs growing popularity (stdlib) Fields a tagged portion of a docstring that describes a specific property of an object descriptions of parameters and regurn values information about how objectgs are organized metadata about objects why use field specialized presentation specialized processing fields: Signature specification (see EpyDoc documentation for more) @param p: describes parameterp @return: describes the return value @returntype the return value's type @raise e: (conditions that cause an exception Fields: Variable documentation describe variables and speccfy their types variables can't define docstrings @var v: describes module variable v @ivar v: describes instance variable v @cvar v: describes class variable v @type v: variable v's type fields: Content Organization specify how objects are organized @group g: c1, ..., cn defines a named collection of related objects @sort: c1,..., cn @undocumented: c indicates that an object should not be listed in the docs fields: metadata and tagged information describe specific aspects of an object consistent presentation of information automatic processing (eg creating a bug index) @licence @precondition @copyright @depreciated @version @author @warning @todo @bugs ...etc... Fields: Create your own Epydoc provides two mechanisms for define new fields: a special field: @newfield tag: label [, plural-label] a module level variable: __extra_epydoc_fields__ = [(tag[, label[, plural-label]])] Extracting Documentation: (Two methods) Inspection importing library and using Python to parse file and then use python's introspection to figure stuff out source code parsing: parse the library's source code, and extgract relvant information Extgracting Documentation: Limitation of parsing Can't capture the efects of dynamic transformation Metaclasses Namespace manimpuation Can't document non-python modules Extension modules Javadoc modules Non-python base classes for python modules Extracting Documenation: limitations of Inspection Some information is unavailable via inspection: what module defines a given function? which objects are imported vs defined locally? e.g. integer constants psuedo-docstrings for variables. can't document 'insecure' code can't document modules that perform complex or interactive tasks when imported e.g. opening a tkinter window Extracting Documentation Epydoc's answer: use a hybrid approach Inspection froms the basis for documentation extraction Inspection gives a more accurate representation of the user-visible behaviour Source code parsing is used to overcome the limitation of inspection, where necessary Using hybrid approach, epydoc can generate comprehensive API docs for almost any library Q: How do you handle inherited methods? (Show them with the class, or show them with the base class and the "searcher" as to go there to look for the method?)? A: there are three different display styles for inherited items: display all, create group for each base class, or have a list of distinct inherited items at the bottom Q: large module built on windows but the export is done on linux - the import modules don't exist on linux - how to get around it without doing the build on the windows box A: he would like to use parsing as a fall-back method for when introspection during importing Q: what happens when you have doctext in your docstring A: depending on the markup language it will display it appropriately - if it's javadoc then it will have all kinds of > issues Q: have you considered using or generating xhtml - to separate out the style sheet A: style sheets are used for basic info - fonts, colors and the like - but nothing fancy -------------------------------------------------------------------------- REFERENCES: {as documents / sites are referenced add them below} PAPER: http://www.python.org/pycon/dc2004/papers/37/epydoc/epydoc.pdf -------------------------------------------------------------------------- QUOTES: "the E in epydoc standard for Ed" -------------------------------------------------------------------------- CONTRIBUTORS: {add your name, e-mail address and URL below} Ted Leung, twl@osafoundation.org, http://www.sauria.com/blog Ryan Wilcox, ryanwilcox@mac.com, http://radio.weblogs.com/0100544/ -------------------------------------------------------------------------- E-MAIL BOUNCEBACK: {add your e-mail address separated by commas } -------------------------------------------------------------------------- NOTES ON / KEY TO THIS TEMPLATE: A headline (like a field in a database) will be CAPITALISED This differentiates from the text that follows A variable that you can change will be surrounded by _underscores_ Spaces in variables are also replaced with under_scores This allows people to select the whole variable with a simple double-click A tool-tip is lower case and surrounded by {curly brackets / parentheses} These supply helpful contextual information. -------------------------------------------------------------------------- Copyright shared between all the participants unless otherwise stated...