Package epydoc

[hide private]
[frames] | no frames]

# Source Code for Package epydoc

      1  # epydoc
      2  #
      3  # Copyright (C) 2005 Edward Loper
      4  # Author: Edward Loper <edloper@loper.org>
      5  # URL: <http://epydoc.sf.net>
      6  #
      7  # $Id: __init__.py 1691 2008-01-30 17:11:09Z edloper $
      8
      9  """
     10  Automatic Python reference documentation generator.  Epydoc processes
     11  Python modules and docstrings to generate formatted API documentation,
     12  in the form of HTML pages.  Epydoc can be used via a command-line
     13  interface (`epydoc.cli`) and a graphical interface (`epydoc.gui`).
     14  Both interfaces let the user specify a set of modules or other objects
     15  to document, and produce API documentation using the following steps:
     16
     17  1. Extract basic information about the specified objects, and objects
     18     that are related to them (such as the values defined by a module).
     19     This can be done via introspection, parsing, or both:
     20
     21     * *Introspection* imports the objects, and examines them directly
     22       using Python's introspection mechanisms.
     23
     24     * *Parsing* reads the Python source files that define the objects,
     25       and extracts information from those files.
     26
     27  2. Combine and process that information.
     28
     29     * **Merging**: Merge the information obtained from introspection &
     30       parsing each object into a single structure.
     31
     32     * **Linking**: Replace any \"pointers\" that were created for
     33       imported variables with the documentation that they point to.
     34
     35     * **Naming**: Assign unique *canonical names* to each of the
     36       specified objects, and any related objects.
     37
     38     * **Docstrings**: Parse the docstrings of each of the specified
     39       objects.
     40
     41     * **Inheritance**: Add variables to classes for any values that
     42       they inherit from their base classes.
     43
     44  3. Generate output.  Output can be generated in a variety of formats:
     45
     46     * An HTML webpage.
     47
     48     * A LaTeX document (which can be rendered as a PDF file)
     49
     50     * A plaintext description.
     51
     52  .. digraph:: Overview of epydoc's architecture
     53     :caption: The boxes represent steps in epydoc's processing chain.
     54               Arrows are annotated with the data classes used to
     55               communicate between steps.  The lines along the right
     56               side mark what portions of the processing chain are
     57               initiated by build_doc_index() and cli().  Click on
     58               any item to see its documentation.
     59
     60     /*
     61                    Python module or value                 *       *
     62                        /           \                      |       |
     63                       V             V                     |       |
     64              introspect_docs()  parse_docs()              |       |
     65                          \        /                       |       |
     66                           V      V                        |       |
     67                          merge_docs()                     |       |
     68                               |              build_doc_index()  cli()
     69                               V                           |       |
     70                         link_imports()                    |       |
     71                               |                           |       |
     72                               V                           |       |
     73                      assign_canonical_names()             |       |
     74                               |                           |       |
     75                               V                           |       |
     76                        parse_docstrings()                 |       |
     77                               |                           |       |
     78                               V                           |       |
     79                         inherit_docs()                    *       |
     80                        /      |        \                          |
     81                       V       V         V                         |
     82                  HTMLWriter LaTeXWriter PlaintextWriter           *
     83     */
     84
     85     ranksep = 0.1;
     86     node [shape="box", height="0", width="0"]
     87
     88     { /* Task nodes */
     89       node [fontcolor=\"#000060\"]
     90       introspect  [label="Introspect value:\\nintrospect_docs()",
     91                    href="<docintrospecter.introspect_docs>"]
     92       parse       [label="Parse source code:\\nparse_docs()",
     93                    href="<docparser.parse_docs>"]
     94       merge       [label="Merge introspected & parsed docs:\\nmerge_docs()",
     95                    href="<docbuilder.merge_docs>", width="2.5"]
     96       link        [label="Link imports:\\nlink_imports()",
     97                    href="<docbuilder.link_imports>", width="2.5"]
     98       name        [label="Assign names:\\nassign_canonical_names()",
     99                    href="<docbuilder.assign_canonical_names>", width="2.5"]
    100       docstrings  [label="Parse docstrings:\\nparse_docstring()",
    101                    href="<docstringparser.parse_docstring>", width="2.5"]
    102       inheritance [label="Inherit docs from bases:\\ninherit_docs()",
    103                    href="<docbuilder.inherit_docs>", width="2.5"]
    104       write_html  [label="Write HTML output:\\nHTMLWriter",
    105                   href="<docwriter.html>"]
    106       write_latex  [label="Write LaTeX output:\\nLaTeXWriter",
    107                   href="<docwriter.latex>"]
    108       write_text  [label="Write text output:\\nPlaintextWriter",
    109                   href="<docwriter.plaintext>"]
    110     }
    111
    112     { /* Input & Output nodes */
    113       node [fontcolor=\"#602000\", shape="plaintext"]
    114       input [label="Python module or value"]
    115       output [label="DocIndex", href="<apidoc.DocIndex>"]
    116     }
    117
    118     { /* Graph edges */
    119       edge [fontcolor=\"#602000\"]
    120       input -> introspect
    121       introspect -> merge [label="APIDoc", href="<apidoc.APIDoc>"]
    122       input -> parse
    123       parse -> merge [label="APIDoc", href="<apidoc.APIDoc>"]
    124       merge -> link [label=" DocIndex", href="<apidoc.DocIndex>"]
    125       link -> name [label=" DocIndex", href="<apidoc.DocIndex>"]
    126       name -> docstrings [label=" DocIndex", href="<apidoc.DocIndex>"]
    127       docstrings -> inheritance [label=" DocIndex", href="<apidoc.DocIndex>"]
    128       inheritance -> output
    129       output -> write_html
    130       output -> write_latex
    131       output -> write_text
    132     }
    133
    134     { /* Task collections */
    135       node [shape="circle",label="",width=.1,height=.1]
    136       edge [fontcolor="black", dir="none", fontcolor=\"#000060\"]
    137       l3 -> l4 [label=" epydoc.\\l docbuilder.\\l build_doc_index()",
    138                 href="<docbuilder.build_doc_index>"]
    139       l1 -> l2 [label=" epydoc.\\l cli()", href="<cli>"]
    140     }
    141     { rank=same; l1 l3 input }
    142     { rank=same; l2 write_html }
    143     { rank=same; l4 output }
    144
    145  Package Organization
    146  ====================
    147  The epydoc package contains the following subpackages and modules:
    148
    149  .. packagetree::
    150     :style: UML
    151
    152  The user interfaces are provided by the `gui` and `cli` modules.
    153  The `apidoc` module defines the basic data types used to record
    154  information about Python objects.  The programmatic interface to
    155  epydoc is provided by `docbuilder`.  Docstring markup parsing is
    156  handled by the `markup` package, and output generation is handled by
    157  the `docwriter` package.  See the submodule list for more
    158  information about the submodules and subpackages.
    159
    160  :group User Interface: gui, cli
    161  :group Basic Data Types: apidoc
    162  :group Documentation Generation: docbuilder, docintrospecter, docparser
    163  :group Docstring Processing: docstringparser, markup
    164  :group Output Generation: docwriter
    165  :group Completeness Checking: checker
    166  :group Miscellaneous: log, util, test, compat
    167
    168  :author: `Edward Loper <edloper@gradient.cis.upenn.edu>`__
    169  :requires: Python 2.3+
    170  :version: 3.0.1
    171  :see: `The epydoc webpage <http://epydoc.sourceforge.net>`__
    172  :see: `The epytext markup language
    173      manual <http://epydoc.sourceforge.net/epytext.html>`__
    174
    175  :todo: Create a better default top_page than trees.html.
    176  :todo: Fix trees.html to work when documenting non-top-level
    177         modules/packages
    178  :todo: Implement @include
    179  :todo: Optimize epytext
    180  :todo: More doctests
    181  :todo: When introspecting, limit how much introspection you do (eg,
    182         don't construct docs for imported modules' vars if it's
    183         not necessary)
    184
    185  :bug: UserDict.* is interpreted as imported .. why??
    186
    187  :license: IBM Open Source License
    188  :copyright: |copy| 2006 Edward Loper
    189
    190  :newfield contributor: Contributor, Contributors (Alphabetical Order)
    191  :contributor: `Glyph Lefkowitz  <mailto:glyph@twistedmatrix.com>`__
    192  :contributor: `Edward Loper  <mailto:edloper@gradient.cis.upenn.edu>`__
    193  :contributor: `Bruce Mitchener  <mailto:bruce@cubik.org>`__
    194  :contributor: `Jeff O'Halloran  <mailto:jeff@ohalloran.ca>`__
    195  :contributor: `Simon Pamies  <mailto:spamies@bipbap.de>`__
    196  :contributor: `Christian Reis  <mailto:kiko@async.com.br>`__
    197  :contributor: `Daniele Varrazzo  <mailto:daniele.varrazzo@gmail.com>`__
    198
    199  .. |copy| unicode:: 0xA9 .. copyright sign
    200  """
    201  __docformat__ = 'restructuredtext en'
    202
    203  __version__ = '3.0.1'
    204  """The version of epydoc"""
    205
    206  __author__ = 'Edward Loper <edloper@gradient.cis.upenn.edu>'
    207  """The primary author of eypdoc"""
    208
    209  __url__ = 'http://epydoc.sourceforge.net'
    210  """The URL for epydoc's homepage"""
    211
    212  __license__ = 'IBM Open Source License'
    213  """The license governing the use and distribution of epydoc"""
    214
    215  # [xx] this should probably be a private variable:
    216  DEBUG = False
    217  """True if debugging is turned on."""
    218
    219  # Changes needed for docs:
    220  #   - document the method for deciding what's public/private
    221  #   - epytext: fields are defined slightly differently (@group)
    222  #   - new fields
    223  #   - document __extra_epydoc_fields__ and @newfield
    224  #   - Add a faq?
    225  #   - @type a,b,c: ...
    226  #   - new command line option: --command-line-order
    227