[Epydoc-commits] SF.net SVN: epydoc: [1541] trunk/epydoc/doc
Brought to you by:
edloper
Menu
▾
▴
[Epydoc-commits] SF.net SVN: epydoc: [1541] trunk/epydoc/doc
|
From: <dva...@us...> - 2007-02-20 09:49:57
|
Revision: 1541
http://svn.sourceforge.net/epydoc/?rev=1541&view=rev
Author: dvarrazzo
Date: 2007-02-20 01:49:56 -0800 (Tue, 20 Feb 2007)
Log Message:
-----------
- Adding user manual.
A chapter on reST and Javadoc is required. To be done soon.
Added Paths:
-----------
trunk/epydoc/doc/manual-docstring.txt
trunk/epydoc/doc/manual-epytext.txt
trunk/epydoc/doc/manual-fields.txt
trunk/epydoc/doc/manual-install.txt
trunk/epydoc/doc/manual-reference.txt
trunk/epydoc/doc/manual-usage.txt
trunk/epydoc/doc/manual.txt
Added: trunk/epydoc/doc/manual-docstring.txt
===================================================================
--- trunk/epydoc/doc/manual-docstring.txt (rev 0)
+++ trunk/epydoc/doc/manual-docstring.txt 2007-02-20 09:49:56 UTC (rev 1541)
@@ -0,0 +1,125 @@
+Docstrings and coding issues
+============================
+
+.. $Id$
+
+..
+ This paragraph is introdictory: this chapter should explain advanced details.
+
+
+ Python docstrings
+ -----------------
+
+ Docstrings are a standard method that can be used by Python developers to
+ attach documentation pieces to most Python objects.
+
+ Here is an example module showing different docstrings:
+
+ .. python::
+
+ #!/usr/bin/python
+ # -*- coding: latin-1 -*-
+ """A Sample Module.
+
+ The first string in the module, starting after the *hashbang* and the
+ encoding definition comment, is the module docstring.
+ """
+
+ class Foo:
+ """
+ This is a testing class.
+
+ It doesn't do much stuff, but it's pretty documented. This, for
+ example, is the class docstring.
+ """
+
+ def getMagic(self):
+ """
+ A function returning a magic number.
+
+ This is the function documentation.
+ """
+ return 42
+
+ the_number = property(
+ fget=getMagic,
+ doc="""This is the property docstring.""")
+
+ Some guidelines for docstring standardization have been published, see for
+ example :PEP:`257` for some higl-level convention. No docstring structure
+ is enforced anyway by official documentation.
+
+
+Variable docstrings
+-------------------
+
+Python variables don't support docstrings. The variable can be described in the
+module or class where it is defined using the tags ``@var``, ``@ivar``,
+``@cvar``; but this only allows for a textual description: no further metadata
+can be added to the variable (except for the type, using the ``@type`` tag).
+
+Epydoc supports *variable docstrings*: if a variable assignment statement is
+immediately followed by a bare string literal, then that assignment is treated
+as a docstring for that variable. In classes, variable assignments at the class definition level are considered class variables; and assignments to instance
+variables in the constructor (``__init__``) are considered instance variables:
+
+.. python::
+
+ class A:
+ x = 22
+ """Docstring for class variable A.x"""
+
+ def __init__(self, a):
+ self.y = a
+ """Docstring for instance variable A.y
+
+Variables may also be documented using *comment docstrings*. If a variable
+assignment is immediately preceeded by a comment whose lines begin with the
+special marker '``#:``', or is followed on the same line by such a comment,
+then it is treated as a docstring for that variable:
+
+.. python::
+
+ #: docstring for x
+ x = 22
+ x = 22 #: docstring for x
+
+A common Python idiom is to create instance variables settings their default
+value in the class instead of the constructor (hopefully if the default is
+immutable...). To avoid Epydoc to interpret such variable as a class variable,
+you can describe it using the tag ``@ivar`` in the context of a variable
+docstring:
+
+.. python::
+
+ class B:
+ y = 42
+ """@ivar: This is an instance variable."""
+
+Notice that variable docstrings are only available for documentation when the
+source code is available for *parsing*: it is not possible to retrieve variable
+docstrings from introspection informations only.
+
+
+Items visibility
+----------------
+
+Any Python object (modules, classes, functions, variables...) can be *public*
+or *private*. Usually the object name decides the object visibility: objects
+whose name starts with an underscore and doesn't end with an underscore are
+considered private. All the other objects (including the "magic functions" such
+as ``__add__``) are public.
+
+For each module and class, Epydoc generates pages with both public and private
+methods. A Javascript snippet allows to toggle the visibility of private
+objects.
+
+If a module wants to hide some of the objects it contains (either defined in
+the module itself or imported from other modules), it can explicitly list the
+names if its `public names`_ in the ``__all__`` variable.
+
+.. _public names: http://www.python.org/doc/2.4.3/ref/import.html
+
+If a module defines the ``__all__`` variable, Epydoc uses its content to decide
+if the module objects are public or private.
+
Property changes on: trunk/epydoc/doc/manual-docstring.txt
___________________________________________________________________
Name: svn:keywords
+ Id
Name: svn:eol-style
+ native
Added: trunk/epydoc/doc/manual-epytext.txt
===================================================================
--- trunk/epydoc/doc/manual-epytext.txt (rev 0)
+++ trunk/epydoc/doc/manual-epytext.txt 2007-02-20 09:49:56 UTC (rev 1541)
@@ -0,0 +1,873 @@
+The Epytext Markup Language
+===========================
+
+.. $Id$
+
+Overview
+--------
+
+Epytext is a lightweight markup language for Python docstrings. The epytext
+markup language is used by epydoc to parse docstrings and create structured API
+documentation. Epytext markup is broken up into the following categories:
+
+* **Block Structure** divides the docstring into nested blocks of text, such
+ as *paragraphs* and *lists*.
+
+ o **Basic Blocks** are the basic unit of block structure.
+
+ o **Hierarchical blocks** represent the nesting structure of the docstring.
+
+* **Inline Markup** marks regions of text within a basic block with properties,
+ such as italics and hyperlinks.
+
+
+Block Structure
+---------------
+
+Block structure is encoded using indentation, blank lines, and a handful of
+special character sequences.
+
+* Indentation is used to encode the nesting structure of hierarchical blocks.
+ The indentation of a line is defined as the number of leading spaces on that
+ line; and the indentation of a block is typically the indentation of its
+ first line.
+* Blank lines are used to separate blocks. A blank line is a line that only
+ contains whitespace.
+* Special character sequences are used to mark the beginnings of some blocks.
+ For example, '``-``' is used as a bullet for unordered list items, and
+ '``>>>``' is used to mark `doctest blocks`_.
+
+The following sections describe how to use each type of block structure.
+
+
+Paragraphs
+''''''''''
+
+A paragraph is the simplest type of basic block. It consists of one or more
+lines of text. Paragraphs must be left justified (i.e., every line must have
+the same indentation). The following example illustrates how paragraphs can be
+used:
+
+.. list-table::
+ :header-rows: 1
+
+ * - Docstring Input
+ - Rendered Output
+
+ * - .. python::
+
+ def example():
+ """
+ This is a paragraph. Paragraphs can
+ span multiple lines, and can contain
+ I{inline markup}.
+
+ This is another paragraph. Paragraphs
+ are separated by blank lines.
+ """
+ *[...]*
+
+ - This is a paragraph. Paragraphs can span multiple lines,
+ and contain *inline markup*.
+
+ This is another paragraph. Paragraphs are separated from each
+ other by blank lines.
+
+Lists
+'''''
+
+Epytext supports both ordered and unordered lists. A list consists of one or
+more consecutive *list items* of the same type (ordered or unordered), with the
+same indentation. Each list item is marked by a *bullet*. The bullet for
+unordered list items is a single dash character (``-``). Bullets for ordered
+list items consist of a series of numbers followed by periods, such as
+``12.`` or ``1.2.8.``.
+
+List items typically consist of a bullet followed by a space and a single
+paragraph. The paragraph may be indented more than the list item's bullet;
+often, the paragraph is intended two or three characters, so that its left
+margin lines up with the right side of the bullet. The following example
+illustrates a simple ordered list.
+
+
+.. list-table::
+ :header-rows: 1
+
+ * - Docstring Input
+ - Rendered Output
+
+ * - .. python::
+
+ def example():
+ """
+ 1. This is an ordered list item.
+
+ 2. This is a another ordered list
+ item.
+
+ 3. This is a third list item. Note that
+ the paragraph may be indented more
+ than the bullet.
+ """
+ *[...]*
+
+ - 1. This is an ordered list item.
+ 2. This is another ordered list item.
+ 3. This is a third list item. Note that the paragraph may be
+ indented more than the bullet.
+
+List items can contain more than one paragraph; and they can also contain
+sublists, `literal blocks`, and `doctest blocks`. All of the blocks contained
+by a list item must all have equal indentation, and that indentation must be
+greater than or equal to the indentation of the list item's bullet. If the
+first contained block is a paragraph, it may appear on the same line as the
+bullet, separated from the bullet by one or more spaces, as shown in the
+previous example. All other block types must follow on separate lines.
+
+Every list must be separated from surrounding blocks by indentation:
+
+
+.. list-table::
+ :header-rows: 1
+
+ * - Docstring Input
+ - Rendered Output
+
+ * - .. python::
+
+ def example():
+ """
+ This is a paragraph.
+ 1. This is a list item.
+ 2. This a second list
+ item.
+ - This is a sublist
+ """
+ [...]
+
+ - This is a paragraph.
+
+ 1. This is a list item.
+ 2. This is a second list item.
+
+ * This is a sublist.
+
+Note that sublists must be separated from the blocks in their parent list
+item by indentation. In particular, the following docstring generates an error,
+since the sublist is not separated from the paragraph in its parent list item
+by indentation:
+
+.. list-table::
+ :header-rows: 1
+
+ * - Docstring Input
+ - Rendered Output
+
+ * - .. python::
+
+ def example():
+ """
+ 1. This is a list item. Its
+ paragraph is indented 7 spaces.
+ - This is a sublist. It is
+ indented 7 spaces.
+ """
+ #[...]
+
+ - **L5: Error: Lists must be indented.**
+
+The following example illustrates how lists can be used:
+
+.. list-table::
+ :header-rows: 1
+
+ * - Docstring Input
+ - Rendered Output
+
+ * - .. python::
+
+ def example():
+ """
+ This is a paragraph.
+ 1. This is a list item.
+ - This is a sublist.
+ - The sublist contains two
+ items.
+ - The second item of the
+ sublist has its own sublist.
+
+ 2. This list item contains two
+ paragraphs and a doctest block.
+
+ >>> print 'This is a doctest block'
+ This is a doctest block
+
+ This is the second paragraph.
+ """
+ #[...]
+
+ - This is a paragraph.
+
+ 1. This is a list item.
+
+ * This is a sublist.
+ * The sublist contains two items.
+
+ - The second item of the sublist has its own own sublist.
+
+ 2. This list item contains two paragraphs and a doctest block.
+
+ >>> print 'This is a doctest block'
+ This is a doctest block
+
+ This is the second paragraph.
+
+Epytext will treat any line that begins with a bullet as a list item. If you
+want to include bullet-like text in a paragraph, then you must either ensure
+that it is not at the beginning of the line, or use escaping_ to prevent
+epytext from treating it as markup:
+
+.. list-table::
+ :header-rows: 1
+
+ * - Docstring Input
+ - Rendered Output
+
+ * - .. python::
+
+ def example():
+ """
+ This sentence ends with the number
+ 1. Epytext can't tell if the "1."
+ is a bullet or part of the paragraph,
+ so it generates an error.
+ """
+ #[...]
+
+ - **L4: Error: Lists must be indented.**
+
+ * - .. python::
+
+ def example():
+ """
+ This sentence ends with the number 1.
+
+ This sentence ends with the number
+ E{1}.
+ """
+ #[...]
+
+ - This sentence ends with the number 1.
+
+ This sentence ends with the number 1.
+
+
+Sections
+''''''''
+
+A section consists of a heading followed by one or more child blocks.
+
+* The heading is a single underlined line of text. Top-level section headings
+ are underlined with the '``=``' character; subsection headings are
+ underlined with the '``-``' character; and subsubsection headings are
+ underlined with the '``~``' character. The length of the underline must
+ exactly match the length of the heading.
+* The child blocks can be paragraphs, lists, literal blocks, doctest blocks,
+ or sections. Each child must have equal indentation, and that indentation
+ must be greater than or equal to the heading's indentation.
+
+The following example illustrates how sections can be used:
+
+
+.. list-table::
+ :header-rows: 1
+
+ * - Docstring Input
+ - Rendered Output
+
+ * - .. python::
+
+ def example():
+ """
+ This paragraph is not in any section.
+
+ Section 1
+ =========
+ This is a paragraph in section 1.
+
+ Section 1.1
+ -----------
+ This is a paragraph in section 1.1.
+
+ Section 2
+ =========
+ This is a paragraph in section 2.
+ """
+ #[...]
+
+ -
+ .. class:: h1
+
+ Section 1
+
+ This is a paragraph in section 1.
+
+ .. class:: h2
+
+ Section 1.1
+
+ This is a paragraph in section 1.1.
+
+ .. class:: h1
+
+ Section 2
+
+ This is a paragraph in section 2.
+
+
+Literal Blocks
+''''''''''''''
+
+Literal blocks are used to represent "preformatted" text. Everything within a
+literal block should be displayed exactly as it appears in plaintext. In
+particular:
+
+* Spaces and newlines are preserved.
+* Text is shown in a monospaced font.
+* Inline markup is not detected.
+
+Literal blocks are introduced by paragraphs ending in the special sequence
+"``::``". Literal blocks end at the first line whose indentation is equal to
+or less than that of the paragraph that introduces them. The following example
+shows how literal blocks can be used:
+
+
+.. list-table::
+ :header-rows: 1
+
+ * - Docstring Input
+ - Rendered Output
+
+ * - .. python::
+
+ def example():
+ """
+ The following is a literal block::
+
+ Literal /
+ / Block
+
+ This is a paragraph following the
+ literal block.
+ """
+ #[...]
+
+ - The following is a literal block::
+
+ Literal /
+ / Block
+
+ This is a paragraph following the literal block.
+
+Literal blocks are indented relative to the paragraphs that introduce them;
+for example, in the previous example, the word "Literal" is displayed with four
+leading spaces, not eight. Also, note that the double colon ("``::``") that
+introduces the literal block is rendered as a single colon.
+
+
+Doctest Blocks
+''''''''''''''
+
+Doctest blocks contain examples consisting of Python expressions and their
+output. Doctest blocks can be used by the doctest module to test the
+documented object. Doctest blocks begin with the special sequence
+"``>>>``". Doctest blocks are delimited from surrounding blocks by blank lines.
+Doctest blocks may not contain blank lines. The following example shows how
+doctest blocks can be used:
+
+
+.. list-table::
+ :header-rows: 1
+
+ * - Docstring Input
+ - Rendered Output
+
+ * - .. python::
+
+ def example():
+ """
+ The following is a doctest block:
+
+ >>> print (1+3,
+ ... 3+5)
+ (4, 8)
+ >>> 'a-b-c-d-e'.split('-')
+ ['a', 'b', 'c', 'd', 'e']
+
+ This is a paragraph following the
+ doctest block.
+ """
+ #[...]
+
+ - The following is a doctest block:
+
+ >>> print (1+3,
+ ... 3+5)
+ (4, 8)
+ >>> 'a-b-c-d-e'.split('-')
+ ['a', 'b', 'c', 'd', 'e']
+
+ This is a paragraph following the doctest block.
+
+
+Fields
+''''''
+
+Fields are used to describe specific properties of a documented object. For
+example, fields can be used to define the parameters and return value of a
+function; the instance variables of a class; and the author of a module. Each
+field is marked by a *field tag*, which consist of an at sign ('``@``')
+followed by a *field name*, optionally followed by a space and a *field
+argument*, followed by a colon ('``:``'). For example, '``@return:``' and
+'``@param x:``' are field tags.
+
+Fields can contain paragraphs, lists, literal blocks, and doctest blocks.
+All of the blocks contained by a field must all have equal indentation, and
+that indentation must be greater than or equal to the indentation of the
+field's tag. If the first contained block is a paragraph, it may appear on the
+same line as the field tag, separated from the field tag by one or more spaces.
+All other block types must follow on separate lines.
+
+Fields must be placed at the end of the docstring, after the description of
+the object. Fields may be included in any order.
+
+Fields do not need to be separated from other blocks by a blank line. Any line
+that begins with a field tag followed by a space or newline is considered a
+field.
+
+The following example illustrates how fields can be used:
+
+.. list-table::
+ :header-rows: 1
+
+ * - Docstring Input
+ - Rendered Output
+
+ * - .. python::
+
+ def example():
+ """
+ @param x: This is a description of
+ the parameter x to a function.
+ Note that the description is
+ indented four spaces.
+ @type x: This is a description of
+ x's type.
+ @return: This is a description of
+ the function's return value.
+
+ It contains two paragraphs.
+ """
+ #[...]
+
+ - **Parameters:**
+ **x** - This is a description of the parameter x to a function.
+ Note that the description is indented four spaces.
+
+ *(type=This is a description of x's type.)*
+
+ **Returns:**
+ This is a description of the function's return value.
+
+ It contains two paragraphs.
+
+For a list of the fields that are supported by epydoc, see the `epydoc fields`
+chapter.
+
+
+Inline Markup
+-------------
+
+Inline markup has the form '``x{...}``', where ``x`` is a single capital letter
+that specifies how the text between the braces should be rendered. Inline
+markup is recognized within paragraphs and section headings. It is *not*
+recognized within literal and doctest blocks. Inline markup can contain
+multiple words, and can span multiple lines. Inline markup may be nested.
+
+A matching pair of curly braces is only interpreted as inline markup if the
+left brace is immediately preceeded by a capital letter. So in most cases, you
+can use curly braces in your text without any form of escaping. However, you do
+need to escape curly braces when:
+
+1. You want to include a single (un-matched) curly brace.
+2. You want to preceed a matched pair of curly braces with a capital letter.
+
+Note that there is no valid Python expression where a pair of matched curly
+braces is immediately preceeded by a capital letter (except within string
+literals). In particular, you never need to escape braces when writing Python
+dictionaries. See also escaping_.
+
+
+Basic Inline Markup
+'''''''''''''''''''
+
+ Epytext defines four types of inline markup that specify how text should be
+ displayed:
+
+* ``I{...}``: Italicized text.
+* ``B{...}``: Bold-faced text.
+* ``C{...}``: Source code or a Python identifier.
+* ``M{...}``: A mathematical expression.
+
+By default, source code is rendered in a fixed width font; and mathematical
+expressions are rendered in italics. But those defaults may be changed by
+modifying the CSS stylesheet. The following example illustrates how the four
+basic markup types can be used:
+
+.. list-table::
+ :header-rows: 1
+
+ * - Docstring Input
+ - Rendered Output
+
+ * - .. python::
+
+ def example():
+ """
+ I{B{Inline markup} may be nested; and
+ it may span} multiple lines.
+
+ - I{Italicized text}
+ - B{Bold-faced text}
+ - C{Source code}
+ - M{Math}
+
+ Without the capital letter, matching
+ braces are not interpreted as markup:
+ C{my_dict={1:2, 3:4}}.
+ """
+ #[...]
+
+ - **Inline markup** *may be nested*; and it may span multiple lines.
+
+ - *Italicized text*
+ - **Bold-faced text**
+ - ``Source code``
+ - Math: *m*x+b*
+
+ Without the capital letter, matching braces are not interpreted as
+ markup: ``my_dict={1:2, 3:4}``.
+
+
+URLs
+''''
+
+The inline markup construct ``U{``\ *text<url>*\ ``}`` is used to create links
+to external URLs and URIs. '*text*' is the text that should be displayed for
+the link, and '*url*' is the target of the link. If you wish to use the URL as
+the text for the link, you can simply write "``U{``\ *url*\ ``}``". Whitespace
+within URL targets is ignored. In particular, URL targets may be split over
+multiple lines. The following example illustrates how URLs can be used:
+
+.. list-table::
+ :header-rows: 1
+
+ * - Docstring Input
+ - Rendered Output
+
+ * - .. python::
+
+ def example():
+ """
+ - U{www.python.org}
+ - U{http://www.python.org}
+ - U{The epydoc homepage<http://
+ epydoc.sourceforge.net>}
+ - U{The B{Python} homepage
+ <www.python.org>}
+ - U{Edward Loper<mailto:edloper@
+ gradient.cis.upenn.edu>}
+ """
+ #[...]
+
+ - * `www.python.org`_
+ * http://www.python.org
+ * `The epydoc homepage`_
+ * |pyhome|__
+ * `Edward Loper <mailto:ed...@gr...>`__
+
+ .. __: http://www.python.org
+ .. _The epydoc homepage: http://epydoc.sourceforge.net
+ .. _www.python.org: http://www.python.org
+ .. |pyhome| replace:: The **Python** homepage
+
+
+Documentation Crossreference Links
+''''''''''''''''''''''''''''''''''
+
+The inline markup construct '``L{``\ *text<object>*\ ``}``' is used to create
+links to the documentation for other Python objects. '*text*' is the text that
+should be displayed for the link, and '*object*' is the name of the Python
+object that should be linked to. If you wish to use the name of the Python
+object as the text for the link, you can simply write ``L{``\ *object*\ }``.
+Whitespace within object names is ignored. In particular, object names may be
+split over multiple lines. The following example illustrates how documentation
+crossreference links can be used:
+
+.. list-table::
+ :header-rows: 1
+
+ * - Docstring Input
+ - Rendered Output
+
+ * - .. python::
+
+ def example():
+ """
+ - L{x_transform}
+ - L{search<re.search>}
+ - L{The I{x-transform} function
+ <x_transform>}
+ """
+ #[...]
+
+ - * `x_transform`_
+ * `search`_
+ * `The x-transform function`_
+
+ .. _x_transform: http://www.example.com
+ .. _search: http://www.example.com
+ .. _The x-transform function: http://www.example.com
+
+In order to find the object that corresponds to a given name, epydoc checks the
+following locations, in order:
+
+1. If the link is made from a class or method docstring, then epydoc checks for
+ a method, instance variable, or class variable with the given name.
+2. Next, epydoc looks for an object with the given name in the current module.
+3. Epydoc then tries to import the given name as a module. If the current
+ module is contained in a package, then epydoc will also try importing the
+ given name from all packages containing the current module.
+4. Epydoc then tries to divide the given name into a module name and an
+ object name, and to import the object from the module. If the current module
+ is contained in a package, then epydoc will also try importing the module
+ name from all packages containing the current module.
+5. Finally, epydoc looks for a class name in any module with the given name.
+ This is only returned if there is a single class with such name.
+
+If no object is found that corresponds with the given name, then epydoc
+issues a warning.
+
+
+Indexed Terms
+'''''''''''''
+
+Epydoc automatically creates an index of term definitions for the API
+documentation. The inline markup construct '``X{...}``' is used to mark terms
+for inclusion in the index. The term itself will be italicized; and a link will
+be created from the index page to the location of the term in the text. The
+following example illustrates how index terms can be used:
+
+.. list-table::
+ :header-rows: 1
+
+ * - Docstring Input
+ - Rendered Output
+
+ * - .. python::
+
+ def example():
+ """
+ An X{index term} is a term that
+ should be included in the index.
+ """
+ #[...]
+
+ - An *index term* is a term that should be included in the index.
+
+ ============ ==============
+ Index
+ ===========================
+ index term *example*
+ x intercept *x_intercept*
+ y intercept *x_intercept*
+ ============ ==============
+
+
+Symbols
+'''''''
+
+Symbols are used to insert special characters in your documentation. A symbol
+has the form '``S{code}``', where code is a symbol code that specifies what
+character should be produced. The following example illustrates how symbols can
+be used to generate special characters:
+
+.. include:: <xhtml1-symbol.txt>
+
+.. list-table::
+ :header-rows: 1
+
+ * - Docstring Input
+ - Rendered Output
+
+ * - .. python::
+
+ def example():
+ """
+ Symbols can be used in equations:
+
+ - S{sum}S{alpha}/x S{<=} S{beta}
+
+ S{<-} and S{larr} both give left
+ arrows. Some other arrows are
+ S{rarr}, S{uarr}, and S{darr}.
+ """
+ #[...]
+
+ - Symbols can be used in equations:
+
+ - |sum| |alpha|/\ *x* |le| |beta|
+
+ |larr| and |larr| both give left
+ arrows. Some other arrows are
+ |rarr|, |uarr|, and |darr|.
+
+Although symbols can be quite useful, you should keep in mind that they can
+make it harder to read your docstring in plaintext. In general, symbols should
+be used sparingly. For a complete list of the symbols that are currently
+supported, see the reference documentation for :epydoc:`epytext.SYMBOLS`.
+
+
+Escaping
+''''''''
+
+Escaping is used to write text that would otherwise be interpreted as epytext
+markup. Epytext was carefully constructed to minimize the need for this type
+of escaping; but sometimes, it is unavoidable. Escaped text has the form
+'``E{``\ *code*\ ``}``', where code is an escape code that specifies what
+character should be produced. If the escape code is a single character (other
+than '``{``' or '``}``'), then that character is produced. For example, to
+begin a paragraph with a dash (which would normally signal a list item), write
+'``E{-}``'. In addition, two special escape codes are defined: '``E{lb}``'
+produces a left curly brace ('``{``'); and '``E{rb}``' produces a right curly
+brace ('``}``'). The following example illustrates how escaping can be used:
+
+
+.. list-table::
+ :header-rows: 1
+
+ * - Docstring Input
+ - Rendered Output
+
+ * - .. python::
+
+ def example():
+ """
+ This paragraph ends with two
+ colons, but does not introduce
+ a literal blockE{:}E{:}
+
+ E{-} This is not a list item.
+
+ Escapes can be used to write
+ unmatched curly braces:
+ E{rb}E{lb}
+ """
+ #[...]
+
+ - This paragraph ends with two colons, but does not introduce a literal
+ block:\ :
+
+ \- This is not a list item.
+
+ Escapes can be used to write unmatched curly braces: }{
+
+
+Graphs
+''''''
+
+The inline markup construct '``G{``\ *graphtype args...*\ ``}``' is used to
+insert automatically generated graphs. The following graphs generation
+constructions are currently defines:
+
+======================================= =======================================
+Markup Description
+======================================= =======================================
+``G{classtree`` *classes...*\ ``}`` Display a class hierarchy for the given
+ class or classes (including all
+ superclasses & subclasses). If no class
+ is specified, and the directive is used
+ in a class's docstring, then that
+ class's class hierarchy will be
+ displayed.
+``G{packagetree`` *modules...*\ ``}`` Display a package hierarchy for the
+ given module or modules (including all
+ subpackages and submodules). If no
+ module is specified, and the directive
+ is used in a module's docstring, then
+ that module's package hierarchy will be
+ displayed.
+``G{importgraph`` *modules...*\ ``}`` Display an import graph for the given
+ module or modules. If no module is
+ specified, and the directive is used in
+ a module's docstring, then that
+ module's import graph will be
+ displayed.
+``G{callgraph`` *functions...*\ ``}`` Display a call graph for the given
+ function or functions. If no function
+ is specified, and the directive is used
+ in a function's docstring, then that
+ function's call graph will be
+ displayed.
+======================================= =======================================
+
+
+Characters
+----------
+
+Valid Characters
+''''''''''''''''
+
+Valid characters for an epytext docstring are space (``\040``); newline
+(``\012``); and any letter, digit, or punctuation, as defined by the current
+locale. Control characters (``\000``-``\010` and ``\013``-``\037``) are not
+valid content characters. Tabs (``\011``) are expanded to spaces, using the
+same algorithm used by the Python parser. Carridge-return/newline pairs
+(``\015\012``) are converted to newlines.
+
+
+Content Characters
+''''''''''''''''''
+
+Characters in a docstring that are not involved in markup are called *content characters*. Content characters are always displayed as-is. In particular, HTML
+codes are not passed through. For example, consider the following example:
+
+.. list-table::
+ :header-rows: 1
+
+ * - Docstring Input
+ - Rendered Output
+
+ * - .. python::
+
+ def example():
+ """
+ <B>test</B>
+ """
+ #[...]
+
+ - <B>test</B>
+
+The docstring is rendered as ``<B>test</B>``, and not as the word "test" in
+bold face.
+
+
+Spaces and Newlines
+'''''''''''''''''''
+
+In general, spaces and newlines within docstrings are treated as soft spaces.
+In other words, sequences of spaces and newlines (that do not contain a blank
+line) are rendered as a single space, and words may wrapped at spaces. However,
+within literal blocks and doctest blocks, spaces and newlines are preserved,
+and no word-wrapping occurs; and within URL targets and documentation link
+targets, whitespace is ignored.
Property changes on: trunk/epydoc/doc/manual-epytext.txt
___________________________________________________________________
Name: svn:keywords
+ Id
Name: svn:eol-style
+ native
Added: trunk/epydoc/doc/manual-fields.txt
===================================================================
--- trunk/epydoc/doc/manual-fields.txt (rev 0)
+++ trunk/epydoc/doc/manual-fields.txt 2007-02-20 09:49:56 UTC (rev 1541)
@@ -0,0 +1,522 @@
+Epydoc fields
+=============
+
+.. $Id$
+
+Fields are used to describe specific properties of a documented object. For
+example, fields can be used to define the parameters and return value of a
+function; the instance variables of a class; and the author of a module. Each
+field consists of a *tag*, an optional *argument*, and a *body*.
+
+* The *tag* is a case-insensitive word that indicates what kind of
+ documentation is given by the field.
+* The optional *argument* specifies what object, parameter, or group is
+ documented by the field.
+* The *body* contains the main contents of the field.
+
+
+Field Markup
+------------
+
+Each docstring markup langauge marks fields differently. The following table
+shows the basic fields syntax for each markup language. For more information,
+see the definition of field syntax for each markup language.
+
+
+.. list-table::
+ :header-rows: 1
+
+ * - Epytext
+ - reStructuredText
+ - Javadoc
+
+ * - .. parsed-literal::
+
+ @\ *tag*: *body*...
+ @\ *tag* *arg*: *body*...
+
+ - .. parsed-literal::
+
+ :\ *tag*: *body*...
+ :\ *tag* *arg*: *body*...
+
+ - .. parsed-literal::
+
+ @\ *tag* *body*...
+ @\ *tag* *arg* *body*...
+
+ * - `Definition of epytext fields`__
+ - `Definition of ReStructuredText fields`__
+ - `Definition of Javadoc fields`__
+
+.. __: Fields_
+.. __: http://docutils.sourceforge.net/spec/rst/reStructuredText.html
+ #field-lists
+.. __: http://java.sun.com/j2se/1.4.2/docs/tooldocs/solaris/javadoc.html
+ #javadoctags
+
+
+Supported Fields
+----------------
+
+The following table lists the fields that epydoc currently recognizes. Field
+tags are written using epytext markup; if you are using a different markup
+language, then you should adjust the markup accordingly.
+
+
+Functions and Methods parameters
+''''''''''''''''''''''''''''''''
+
+``@param`` *p*: ...
+ A description of the parameter *p* for a function or method.
+
+``@type`` *p*: ...
+ The expected type for the parameter *p*.
+
+``@return``: ...
+ The return value for a function or method.
+
+``@rtype``: ...
+ The type of the return value for a function or method.
+
+``@keyword`` *p*: ...
+ A description of the keyword parameter *p*.
+
+``@raise`` *e*: ...
+ A description of the circumstances under which a function or method
+ raises exception *e*.
+
+These tags can be used to specify attributes of parameters and return value
+of function and methods. These tags are usually put in the the docstring of the
+function to be documented.
+
+.. note:: constructor parameters
+
+ In C extension modules, extension classes cannot have a docstring attached
+ to the ``__init__`` function; consequently it is not possible to document
+ parameters and exceptions raised by the class constructor. To overcome this
+ shortcoming, the tags ``@param``, ``@keyword``, ``@type``, ``@exception``
+ are also allowed to appear in the class docstring. In this case they refer
+ to constructor parameters.
+
+``@param`` fields should be used to document any explicit parameter
+(including the keyword parameter). ``@keyword`` fields should only be used
+for non-explicit keyword parameters:
+
+.. python::
+
+ def plant(seed, *tools, **options):
+ """
+ @param seed: The seed that should be planted.
+ @param tools: Tools that should be used to plant the seed.
+ @param options: Any extra options for the planting.
+
+ @keyword dig_deep: Plant the seed deep under ground.
+ @keyword soak: Soak the seed before planting it.
+ """
+ #[...]
+
+Since the ``@type`` field allows for arbitrary text, it does not
+automatically create a crossreference link to the specified type, and is
+not written in fixed-width font by default. If you want to create a
+crossreference link to the type, or to write the type in a fixed-width
+font, then you must use inline markup:
+
+.. python::
+
+ def ponder(person, time):
+ """
+ @param person: Who should think.
+ @type person: L{Person} or L{Animal}
+ @param time: How long they should think.
+ @type time: C{int} or C{float}
+ """
+ #[...]
+
+
+Variables parameters
+''''''''''''''''''''
+
+``@ivar`` *v*: ...
+ A description of the class instance variable *v*.
+
+``@cvar`` *v*: ...
+ A description of the static class variable *v*.
+
+``@var`` *v*: ...
+ A description of the module variable *v*.
+
+``@type`` *v*: ...
+ The type of the variable *v*.
+
+These tags are usually put in a module or class docstring. If fthe sources can
+be parsed by Epydoc it is also possible to document the variable in their own
+docstrings: see `variable docstrings`_
+
+
+Properties parameters
+'''''''''''''''''''''
+
+``@type``: ...
+ The type of the property.
+
+The ``@type`` tag can be attached toa property docstring to specify its type.
+
+
+Grouping and Sorting
+'''''''''''''''''''''
+
+``@group`` *g*: *c1,...,cn*
+ Organizes a set of related children of a module or class into a group.
+ *g* is the name of the group; and *c1,...,cn* are the names of the
+ children in the group. To define multiple groups, use multiple group
+ fields.
+
+``@sort``: *c1,...,cn*
+ Specifies the sort order for the children of a module or class.
+ *c1,...,cn* are the names of the children, in the order in which they
+ should appear. Any children that are not included in this list will
+ appear after the children from this list, in alphabetical order.
+
+These tags can be used to present groups of related items in a logical way.
+They apply to modules and classes docstrings.
+
+For the ``@group`` and ``@sort`` tags, asterisks (``*``) can be used to
+specify multiple children at once. An asterisk in a child name will match
+any substring:
+
+.. python::
+
+ class widget(size, weight, age):
+ """
+ @group Tools: zip, zap, *_tool
+ @group Accessors: get_*
+ @sort: get_*, set_*, unpack_*, cut
+ """
+ #[...]
+
+.. note:: group markers
+
+ It is also possible to group set of related items enclosing them
+ into special comment starting with the *group markers* '``#{``' and '``#}``'
+ The group title can be specified after the opening group marker. Example:
+
+ .. python::
+
+ #{ Database access functions
+
+ def read(id):
+ #[...]
+
+ def store(item):
+ #[...]
+
+ def delete(id):
+ #[...]
+
+ # groups can't be nested, so a closing marker is not required here.
+
+ #{ Web publish functions
+
+ def get(request):
+ #[...]
+
+ def post(request):
+ #[...]
+
+ #}
+
+
+Notes and Warnings
+''''''''''''''''''
+
+``@note``: ...
+ A note about an object. Multiple note fields may be used to list
+ separate notes.
+
+``@attention``: ...
+ An important note about an object. Multiple attention fields may be
+ used to list separate notes.
+
+``@bug``: ...
+ A description of a bug in an object. Multiple bug fields may be used to
+ report separate bugs.
+
+ .. note::
+
+ If any ``@bug`` field is used, the HTML writer will generate a the page
+ ``bug-index.html``, containing links to all the items tagged with
+ the field.
+
+``@warning``: ...
+ A warning about an object. Multiple warning fields may be used to
+ report separate warnings.
+
+
+Status
+''''''
+
+``@version``: ...
+ The current version of an object.
+
+``@todo`` [*ver*]: ...
+ A planned change to an object. If the optional argument ver is given,
+ then it specifies the version for which the change will be made.
+ Multiple todo fields may be used if multiple changes are planned.
+
+ .. note::
+
+ If any ``@todo`` field is used, the HTML writer will generate a the
+ page ``todo-index.html``, containing links to all the items tagged
+ with the field.
+
+
+``@deprecated``: ...
+ Indicates that an object is deprecated. The body of the field describe
+ the reason why the object is deprecated.
+
+``@since``: ...
+ The date or version when an object was first introduced.
+
+``@status``: ...
+ The current status of an object.
+
+``@change``: ...
+ A change log entry for this object.
+
+``@permission``: ...
+ The object access permission, for systems such Zope/Plone supporting
+ this concept. It may be used more than once to specify multiple
+ permissions.
+
+
+Formal Conditions
+'''''''''''''''''
+
+``@requires``: ...
+ A requirement for using an object. Multiple requires fields may be
+ used if an object has multiple requirements.
+
+``@precondition``: ...
+ A condition that must be true before an object is used. Multiple
+ precondition fields may be used if an object has multiple preconditions.
+
+``@postcondition``: ...
+ A condition that is guaranteed to be true after an object is used.
+ Multiple postcondition fields may be used if an object has multiple
+ postconditions.
+
+``@invariant``: ...
+ A condition which should always be true for an object. Multiple
+ invariant fields may be used if an object has multiple invariants.
+
+
+Bibliographic Information
+'''''''''''''''''''''''''
+
+``@author``: ...
+ The author(s) of an object. Multiple author fields may be used if an
+ object has multiple authors.
+
+``@organization``: ...
+ The organization that created or maintains an object.
+
+``@copyright``: ...
+ The copyright information for an object.
+
+``@license``: ...
+ The licensing information for an object.
+
+``@contact``: ...
+ Contact information for the author or maintainer of a module, class,
+ function, or method. Multiple contact fields may be used if an object
+ has multiple contacts.
+
+
+Other fields
+''''''''''''
+
+``@summary``: ...
+ A summary description for an object. This description overrides the
+ default summary (which is constructed from the first sentence of the
+ object's description).
+
+``@see``: ...
+ A description of a related topic. see fields typically use
+ documentation crossreference links or external hyperlinks that link to
+ the related topic.
+
+
+Fields synonyms
+---------------
+
+Several fields have *synonyms*, or alternate tags. The following table lists
+all field synonyms. Field tags are written using epytext markup; if you are
+using a different markup language, then you should adjust the markup
+accordingly.
+
+
+.. list-table::
+ :header-rows: 1
+
+ * - Name
+ - Synonims
+
+ * - ``@param`` *p*: ...
+ - | ``@parameter`` *p*: ...
+ | ``@arg`` *p*: ...
+ | ``@argument`` *p*: ...
+
+ * - ``@return``: ...
+ - ``@returns``: ...
+
+ * - ``@rtype``: ...
+ - ``@returntype``: ...
+
+ * - ``@raise`` *e*: ...
+ - | ``@raises`` *e*: ...
+ | ``@except`` *e*: ...
+ | ``@exception`` *e*: ...
+
+ * - ``@keyword`` *p*: ...
+ - | ``@kwarg`` *p*: ...
+ | ``@kwparam`` *p*: ...
+
+ * - ``@ivar`` *v*: ...
+ - ``@ivariable`` *v*: ...
+
+ * - ``@cvar`` *v*: ...
+ - ``@cvariable`` *v*: ...
+
+ * - ``@var`` *v*: ...
+ - ``@variable`` *v*: ...
+
+ * - ``@see``: ...
+ - ``@seealso``: ...
+
+ * - ``@warning``: ...
+ - ``@warn``: ...
+
+ * - ``@requires``: ...
+ - | ``@require``: ...
+ | ``@requirement``: ...
+
+ * - ``@precondition``: ...
+ - ``@precond``: ...
+
+ * - ``@postcondition``: ...
+ - ``@postcond``: ...
+
+ * - ``@organization``: ...
+ - ``@org``: ...
+
+ * - ``@copyright``: ...
+ - ``@(c)``: ...
+
+ * - ``@change``: ...
+ - ``@changed``: ...
+
+
+Module metadata variables
+-------------------------
+
+Some module variables are commonly used as module metadata. Epydoc can use the
+value provided by these variables as alternate form for tags. The following
+table lists the recognized variables and the tag they replace. Customized
+metadata variables can be added using the method described in `Adding New
+Fields`_.
+
+.. list-table::
+ :header-rows: 1
+
+ * - Tag
+ - Variable
+
+ * - ``@author``
+ - ``__author__``
+
+ * - ``@authors``
+ - ``__authors__``
+
+ * - ``@contact``
+ - ``__contact__``
+
+ * - ``@copyright``
+ - ``__copyright__``
+
+ * - ``@license``
+ - ``__license__``
+
+ * - ``@deprecated``
+ - ``__deprecated__``
+
+ * - ``@date``
+ - ``__date__``
+
+ * - ``@version``
+ - ``__version__``
+
+
+Adding New Fields
+-----------------
+
+New fields can be defined for the docstrings in a module using the special
+``@newfield`` tag (or its synonym, ``@deffield``). This tag has the following
+syntax:
+
+ .. parsed-literal::
+
+ @newfield *tag*: *label* [, *plural* ]
+
+Where *tag* is the new tag that's being defined; *label* is a string that will
+be used to mark this field in the generated output; and plural is the plural form
+of label, if different.
+
+New fields can be defined in any Python module. If they are defined in a
+package, it will be possible to use the newly defined tag from every package
+submodule.
+
+Each new field will also define a `metadata variable`_ which can be used
+to set the field value instead of the tag. For example, if a *revision*
+tag has been defined with::
+
+ @newfield revision: Revision
+
+then it will be possible to set a value for the field using a module variable:
+
+.. python::
+
+ __revision__ = "1234"
+
+.. _metadata variable: `Module metadata variables`_
+
+The following example illustrates how the @newfield can be used:
+Docstring Input Rendered Output
+
+
+.. list-table::
+ :header-rows: 1
+
+ * - Docstring Input
+ - Rendered Output
+
+ * - .. python::
+
+ """
+ @newfield corpus: Corpus, Corpora
+ """
+
+ def example():
+ """
+ @corpus: Bob's wordlist.
+ @corpus: The British National Corpus.
+ """
+ [...]
+
+ - **Corpora:**
+
+ * Bob's wordlist.
+ * The British National Corpus.
+
+.. Note:: The module-level variable ``__extra_epydoc_fields__`` is deprecated;
+ use ``@newfield`` instead.
Property changes on: trunk/epydoc/doc/manual-fields.txt
___________________________________________________________________
Name: svn:keywords
+ Id
Name: svn:eol-style
+ native
Added: trunk/epydoc/doc/manual-install.txt
===================================================================
--- trunk/epydoc/doc/manual-install.txt (rev 0)
+++ trunk/epydoc/doc/manual-install.txt 2007-02-20 09:49:56 UTC (rev 1541)
@@ -0,0 +1,163 @@
+Installing Epydoc
+=================
+
+.. $Id$
+
+Downloading Epydoc
+------------------
+
+Epydoc can be downloaded from the `SourceForge download page`_. Epydoc is
+available in five formats:
+
+* RPM (``.noarch.rpm``)
+* Windows installer (``.win32.exe``)
+* Source install (``.tar.gz``)
+* Source install (``.zip``)
+* Source RPM (``.src.rpm``)
+
+.. _SourceForge download page:
+ http://sourceforge.net/project/showfiles.php?group_id=32455
+
+If you are installing on RedHat, I recommend that you use the RPM file. If you
+are installing on Windows, I recommended that you use the windows installer.
+Otherwise, you should use one of the source install files.
+
+
+Getting Epydoc from Subversion
+------------------------------
+
+If you wish to keep up on the latest developments, you can get the latest
+version of epydoc from the `subversion repository`_::
+
+ [/home/edloper]$ svn co https://svn.sourceforge.net/svnroot/epydoc/trunk/epydoc epydoc
+ [/home/edloper]$ ls epydoc
+ Makefile doc man sandbox src
+
+This will create a directory named ``epydoc`` containing the latest version of
+epydoc. The ``epydoc`` package itself is in ``epydoc/src/epydoc`` (so adding
+``epydoc/src`` to your ``PYTHONPATH`` will let you use it). You should
+periodically update your copy of the subversion repository, to make sure you
+have all the latest changes::
+
+ [/home/edloper/epydoc]$ svn up
+
+You can browse the subversion repository here__.
+
+.. _subversion repository: http://sourceforge.net/svn/?group_id=32455
+.. __: http://svn.sourceforge.net/viewcvs.cgi/epydoc/trunk/epydoc/
+
+
+Installing from the RPM File
+----------------------------
+
+1. Download the RPM file to a directory of your choice.
+2. Use rpm to install the new package. ::
+
+ [/tmp]$ su
+ Password:
+ [/tmp]# rpm -i epydoc-3.0beta1.noarch.rpm
+
+3. Once epydoc is installed, you can delete the RPM file. ::
+
+ [/tmp]# rm epydoc-3.0beta1.rpm
+
+
+Installing from the Windows Installer
+-------------------------------------
+
+1. Download and run ``epydoc-3.0beta1.win32.exe``.
+2. Follow the on-screen instructions. Epydoc will be installed in the epydoc
+ subdirectory of your Python installation directory (typically
+ ``C:\Python24\``).
+3. The Windows installer creates two scripts in the ``Scripts`` subdirectory of
+ your Python installation directory: ``epydoc.pyw`` opens the graphical user
+ interface, and ``epydoc.py`` calls the command line interface. If you'd
+ like, you can create shortcuts from these scripts to more convenient
+ locations (such as your desktop or start menu).
+4. Once epydoc is installed, you can delete ``epydoc-3.0beta1.win32.exe``.
+
+
+Installing from the Source Distribution (using make)
+----------------------------------------------------
+
+1. Download an epydoc source distribution to a directory of your choice, and
+ uncompress it. ::
+
+ [/tmp]$ wget -q http://prdownloads.sourceforge.net/epydoc/epydoc-3.0beta1.tar.gz
+ [/tmp]$ gunzip epydoc-3.0beta1.tar.gz
+ [/tmp]$ tar -xvf epydoc-3.0beta1.tar
+
+2. Use ``make install`` in the ``eydoc-3.0beta1/`` directory to install
+ epydoc. ::
+
+ [/tmp]$ cd epydoc-3.0beta1/
+ [/tmp/epydoc-3.0beta1]$ su
+ Password:
+ [/tmp/epydoc-3.0beta1]# make install
+ running install
+ running build
+ [...]
+ copying build/scripts/epydoc -> /usr/bin
+ changing mode of /usr/bin/epydoc to 100775
+
+3. If you'd like to keep a local copy of the documentation, then use ``make
+ installdocs``. By default, this will install the documentation to
+ ``/usr/share/doc/`` and the man pages to ``/usr/share/man/``. If you would
+ prefer to install documentation to different directories (such as
+ ``/usr/lib/doc``), then edit the ``MAN`` and ``DOC`` variables at the top of
+ ``Makefile`` before running ``make installdocs``. ::
+
+ [/tmp/epydoc-3.0beta1]# make installdocs
+
+4. Once epydoc is installed, you can delete the installation directory and the
+ source distribution file. ::
+
+ [/tmp/epydoc-3.0beta1]# cd ..
+ [/tmp]# rm -r epydoc-3.0beta1
+ [/tmp]# rm epydoc-3.0beta1.tar
+
+
+Installing from the Source Distribution (without make)
+------------------------------------------------------
+
+1. Download an epydoc source distribution to a directory of your choice, and
+ uncompress it. ::
+
+ [/tmp]$ wget -q http://prdownloads.sourceforge.net/epydoc/epydoc-3.0beta1.tar.gz
+ [/tmp]$ gunzip epydoc-3.0beta1.tar.gz
+ [/tmp]$ tar -xvf epydoc-3.0beta1.tar
+
+2. Use the ``setup.py`` script in the ``eydoc-3.0beta1/`` directory to install
+ epydoc. ::
+
+ [/tmp]$ cd epydoc-3.0beta1/
+ [/tmp/epydoc-3.0beta1]$ su
+ Password:
+ [/tmp/epydoc-3.0beta1]# python setup.py install
+ running install
+ running build
+ [...]
+ copying build/scripts/epydoc -> /usr/bin
+ changing mode of /usr/bin/epydoc to 100775
+ [/tmp/epydoc-3.0beta1]# cd ..
+ [/tmp]#
+
+3. If you'd like to keep a local copy of the documentation, then copy it to a
+ permanant location, such as ``/usr/share/doc/``. You may also want to copy
+ the man pages to a permanant location, such as ``/usr/share/man/``. ::
+
+ [/tmp]# cp -r epydoc-3.0beta1/doc/ /usr/share/doc/epydoc/
+ [/tmp]# cp epydoc-3.0beta1/man/* /usr/share/man/
+
+4. Once epydoc is installed, you can delete the installation directory and the
+ source distribution file. ::
+
+ [/tmp]# rm -r epydoc-3.0beta1
+ [/tmp]# rm epydoc-3.0beta1.tar
+
+
+Installing on Debian
+--------------------
+
+Epydoc 2.1 is available as a testing debian package (``python-epydoc``). The
+epydoc documentation is also available as a package (``epydoc-doc``).
Property changes on: trunk/epydoc/doc/manual-install.txt
___________________________________________________________________
Name: svn:keywords
+ Id
Name: svn:eol-style
+ native
Added: trunk/epydoc/doc/manual-reference.txt
===================================================================
--- trunk/epydoc/doc/manual-reference.txt (rev 0)
+++ trunk/epydoc/doc/manual-reference.txt 2007-02-20 09:49:56 UTC (rev 1541)
@@ -0,0 +1,367 @@
+References
+==========
+
+.. $Id$
+
+Command Line Usage
+------------------
+
+Usage: ``epydoc.py`` [*ACTION*] [*options*] *NAMES...*
+
+NAMES...
+ A list of the Python objects that should be documented. Objects can be
+ specified using dotted names (such as ``os.path``), module filenames (such
+ as ``epydoc/epytext.py``), or package directory names (such as
+ ``epydoc/``). Packages are expanded to include all sub-modules and
+ sub-packages.
+
+options
+ .. parsed-literal::
+
+ --config=FILE A configuration file, specifying additional OPTIONS
+ and/or NAMES. This option may be repeated.
+ -o PATH, --output=PATH
+ The output directory. If PATH does not exist, then it
+ will be created.
+ -q, --quiet Decrease the verbosity.
+ -v, --verbose Increase the verbosity.
+ --debug Show full tracebacks for internal errors.
+ --simple-term Do not try to use color or cursor control when
+ displaying the progress bar, warnings, or errors.
+
+ Actions:
+ --html Write HTML output.
+ --text Write plaintext output. (not implemented yet)
+ --latex Write LaTeX output.
+ --dvi Write DVI output.
+ --ps Write Postscript output.
+ --pdf Write PDF output.
+ --check Check completeness of docs.
+ --pickle Write the documentation to a pickle file.
+ --version Show epydoc's version number and exit.
+ -h, --help Show this message and exit. For help on specific
+ topics, use "--help TOPIC". Use "--help topics" for a
+ list of available help topics
+
+ Generation Options:
+ --docformat=NAME The default markup language for docstrings. Defaults
+ to "epytext".
+ --parse-only Get all information from parsing (don't introspect)
+ --introspect-only Get all information from introspecting (don't parse)
+ --exclude=PATTERN Exclude modules whose dotted name matches the regular
+ expression PATTERN
+ --exclude-introspect=PATTERN
+ Exclude introspection of modules whose dotted name
+ matches the regular expression PATTERN
+ --exclude-parse=PATTERN
+ Exclude parsing of modules whose dotted name matches
+ the regular expression PATTERN
+ --inheritance=STYLE
+ The format for showing inheritance objects. STYLE
+ should be one of: grouped, listed, included.
+ --show-private Include private variables in the output. (default)
+ --no-private Do not include private variables in the output.
+ --show-imports List each module's imports.
+ --no-imports Do not list each module's imports. (default)
+ --show-sourcecode Include source code with syntax highlighting in the
+ HTML output. (default)
+ --no-sourcecode Do not include source code with syntax highlighting in
+ the HTML output.
+ --include-log Include a page with the process log (epydoc-log.html)
+
+ Output Options:
+ --name=NAME The documented project's name (for the navigation
+ bar).
+ --css=STYLESHEET The CSS stylesheet. STYLESHEET can be either a
+ builtin stylesheet or the name of a CSS file.
+ --url=URL The documented project's URL (for the navigation bar).
+ --navlink=HTML HTML code for a navigation link to place in the
+ navigation bar.
+ --top=PAGE The "top" page for the HTML documentation. PAGE can
+ be a URL, the name of a module or class, or one of the
+ special names "trees.html", "indices.html", or
+ "help.html"
+ --help-file=FILE An alternate help file. FILE should contain the body
+ of an HTML file -- navigation bars will be added to
+ it.
+ --show-frames Include frames in the HTML output. (default)
+ --no-frames Do not include frames in the HTML output.
+ --separate-classes When generating LaTeX or PDF output, list each class
+ in its own section, instead of listing them under
+ their containing module.
+
+ API Linking Options:
+ --external-api=NAME
+ Define a new API document. A new interpreted text
+ role NAME will be added.
+ --external-api-file=NAME:FILENAME
+ Use records in FILENAME to resolve objects in the API
+ named NAME.
+ --external-api-root=NAME:STRING
+ Use STRING as prefix for the URL generated from the
+ API NAME.
+
+ Graph Options:
+ --graph=...
[truncated message content] |
