sandbox/dkuhlman/Extract/extract_doc.txt

   1
   2 :author: Dave Kuhlman
   3 :address: dkuhlman@rexx.com \\\\
   4     http://www.rexx.com/~dkuhlman
   5
   6 :revision: 1.0a
   7 :date: July 22, 2003
   8
   9 :copyright: Copyright (c) 2003 Dave Kuhlman.
  10     Permission is hereby granted, free of charge, to any person
  11     obtaining a copy of this software and associated documentation
  12     files (the "Software"), to deal in the Software without
  13     restriction, including without limitation the rights to use,
  14     copy, modify, merge, publish, distribute, sublicense, and/or
  15     sell copies of the Software, and to permit persons to whom the
  16     Software is furnished to do so, subject to the following
  17     conditions: The above copyright notice and this permission
  18     notice shall be included in all copies or substantial portions
  19     of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT
  20     WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT
  21     LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
  22     PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
  23     AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES
  24     OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
  25     OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
  26     SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  27
  28 :abstract: This document describes extract_doc.py which is a
  29     program for extracting documentation from Python source code
  30     files and producing reStructuredText output.
  31
  32
  33 =============================================================
  34 *extract_doc.py* --- Extract Python Source Code Documentation
  35 =============================================================
  36
  37
  38 Description
  39 ===========
  40
  41 *extract_doc* extracts documentation embedded in Python source
  42 code files.
  43
  44 Currently, it generates reStructuredText.  An extension that
  45 generates LaTeX for the Python LaTeX documentation system is
  46 being investigated.
  47
  48 *extract_doc* is derived from and uses code in *pydoc.py* from the
  49 Python standard library.
  50
  51 One goal of *extract_doc* is to provide code that is simple enough
  52 so that the implementation and the output it produces can be
  53 customized for specific applications or by specific users.
  54
  55
  56 Where to Get It
  57 ===============
  58
  59 You can find a distribution file for ``extract_doc`` at:
  60
  61     http://www.rexx.com/~dkuhlman/extract_doc.zip
  62
  63
  64 How to Use extract_doc
  65 ======================
  66
  67 Here is the usage information from `extract_doc`::
  68
  69     Usage:
  70         python extract_doc.py [options] <module_name>
  71     Options:
  72         -h, --help      Display this help message.
  73         -r, --rest      Extract to decorated reST.
  74         -l, --latex     Extract to Python LaTeX (module doc type). Not implemented.
  75         -p, --pager     Use a pager; else write to stdout.
  76         -o, --over      Use over *and* under title adornment, else only under.
  77     Example:
  78         python extract_doc.py -r mymodule1
  79         python extract_doc.py -p -o -r mymodule2
  80
  81
  82 Command line flag descriptions
  83 ------------------------------
  84
  85 -r, --rest    Generate reStructuredText output.
  86
  87 -l, --latex   Generate LaTeX for the Python LaTeX documentation
  88               system.  Not yet implemented.
  89
  90 -p, --pager   Use a pager, else write to stdout.  Selects a pager
  91               and pushes generated output through the pager.  On
  92               my system it selects *less*.
  93
  94 -o, --over    Generate over *and* under title adornment, else
  95               generate under title adornment only.
  96
  97
  98
  99 How to Modify *extract_doc*
 100 ===========================
 101
 102 *extract_doc* contains one important class: ReSTDoc.  It is a
 103 subclass of class Doc in module pydoc in the Python standard
 104 library.  As such, it should have followed other sub-classes of
 105 class Doc closely.  However, it does not.  ReSTDoc is a fairly
 106 radical re-write of TextDoc.  This re-write had these goals:
 107
 108 - Produce reStructuredText (rather than text or HTML).
 109
 110 - Provide code that is simple, consistent, and clear enough so
 111   that others can understand and modify it.
 112
 113 Basically, I want it to produce reStructuredText and to enables
 114 others to customize the reStructuredText that it produces for
 115 their individual needs.
 116
 117 The current class ``ReSTDoc`` produces reStructuredText.  You can
 118 try it for yourself.
 119
 120 Here is a bit of guidance for the second aspect of the goal, i.e.
 121 modifiability:
 122
 123 - Output is accumulated by calling ``self.push(line)`` for each
 124   line of text to be produced.
 125
 126 - There are four functions that produce output.  They are as
 127   follows:
 128
 129   - ``docmodule`` is called for the module.  It is responsible for
 130     producing the documentation for a module.
 131
 132   - ``docclass`` is called for each class.  It is responsible for
 133     producing the documentation for a class.
 134
 135   - ``docroutine`` -- Called for each method (in a class) and each
 136     function (at top level in a module).  It is responsible for
 137     producing the documentation for a method or a function.
 138
 139   - ``docother`` -- Called for data members.  It is responsible for
 140     producing the documentation for a data member.
 141
 142 - Module ``inspect`` from the Python standard library is used to
 143   obtain the internals of an object such as its members, to
 144   determine the type of an object (e.g. method or function),
 145   format the arguments for a function, etc.
 146
 147 - Function getdoc in module ``pydoc`` is called to get the
 148   documentation for an object, for example the documentation for a
 149   module, a class, a method, or a function.
 150
 151 - There is a method (emphasize) to emphasize a piece of text.  It
 152   adds asterisks around the text.
 153
 154 In order to produce your own customized documentation extraction
 155 capability, you might want to do the following:
 156
 157 - Copy class ``ReSTDoc``.
 158
 159 - Modify methods ``docmodule``, ``docclass``, ``docroutine``, and
 160   ``docother`` in class ``ReSTDoc``.
 161
 162 - copy function ``extract_to_rest``.
 163
 164 - Modify function ``extract_to_rest``:
 165
 166   - Add your own title, preferatory stuff, etc. Note where method
 167     ``genTitle`` is called and where the "Generated by ..."
 168     content is added.
 169
 170   - Add your own end-of-doc content.  Add this after the call to
 171     ``formatter.document()``.
 172
 173
 174 Related Work
 175 ============
 176
 177 *PySource* -- Python Source Reader
 178 ----------------------------------
 179
 180 This documentation extractor takes a very different approach.  It
 181 is *not* modelled on pydoc in the Python standard library.  It
 182 does not use the inspect module from the Python standard library.
 183 (I grepped for "inspect" in ``sandbox/davidg/pysource_reader``.)
 184 The documentation says that it:
 185
 186   "... scans a parsed Python module, and returns an ordered tree
 187   containing the names, docstrings (including attribute and
 188   additional docstrings), and additional info ..."
 189
 190 The approach followed by ``PySource`` appears more complex than
 191 that of ``extract_doc, but also more powerful.  I'm going to guess
 192 that the start-up time for a simple-minded programmer (like me) to
 193 begin modifying and customizing ``PySource`` for user specific
 194 needs would be longer than for ``extract_doc``.
 195
 196 I'd appreciate any comments and comparisons that others might
 197 have.
 198
 199 Credits
 200 =======
 201
 202 Thanks to the developers of Docutils, in particular, David
 203 Goodger, project lead.
 204
 205 Thanks to Ka-Ping Yee for *pydoc*.
 206
 207
 208 See Also
 209 ========
 210
 211 `Docutils: Python Documentation Utilities`_
 212
 213 .. _`Docutils: Python Documentation Utilities`:
 214     http://docutils.sourceforge.net/
 215
 216 `pydoc -- Documentation generator and online help system`_
 217
 218 .. _`pydoc -- Documentation generator and online help system`:
 219     http://www.python.org/doc/current/lib/module-pydoc.html
 220
 221
 222