sandbox/tibs/pysource/doc/readme.rtxt

   1 pysource
   2 ========
   3
   4 :Author: Tibs (tibs@tibsnjoan.co.uk)
   5 :Date: $Date$
   6 :Revision: $Revision$
   7 :Version: 0.1
   8
   9 Ahem
  10 ----
  11 This file needs updating - unless this notice has disappeared, treat the
  12 rest of the file as out-of-date...
  13
  14 History
  15 -------
  16 2002-04:
  17
  18 * Name changed from 'pydps' to 'pysource' (in line with a suggestion
  19   made a while back on the Doc-SIG by David Goodger).
  20
  21   It's not that that's a great name, just that it's better than 'pydps'
  22   (especially now that 'dps' has become 'docutils'), and the rather more
  23   obvious 'pydoc' is already taken. Any suggestions for a better name will
  24   be gratefully received!
  25
  26 * Converted from the old 'dps' and 'restructuredtext' packages to the
  27   new 'docutils' package.
  28
  29 * All previous history is elided with the change of name and first release...
  30
  31 Obtaining the package
  32 ---------------------
  33 The latest version of 'pysource' may be found in the Docutils sandbox
  34 (tarball_ and browsable_).
  35
  36 .. _tarball: http://docutils.sourceforge.net/docutils-sandbox-snapshot.tgz
  37 .. _browsable: http://docutils.sourceforge.net/sandbox/tibs/pysource/
  38
  39 I hope to keep a copy of the current "released" version at
  40
  41     http://www.tibsnjoan.co.uk/reST/pysource.tgz
  42
  43 Purpose
  44 -------
  45 This module provides code to
  46
  47   * parse a Python file using the Python Compiler module, which is
  48     standard with Python 2.2 and later, and available in the Tools
  49     directory in earlier versions,
  50   * extract relevant information, including docstrings,
  51   * and ultimately produce (in the first instance) HTML documentation
  52     therefrom.
  53
  54 As a subsidiary capability, it can read a restructuredtext file and produce
  55 HTML from that.
  56
  57 There are obviously other tools which perform similar tasks - see the
  58 accompanying file whythis.rtxt for some comparisons, and an
  59 explanation of why I think it is worth developing this tool
  60 independently.
  61
  62
  63 *** TO HERE ***
  64
  65 Usage
  66 -----
  67 The command ``python pysource/pysource.py --help`` gives the following
  68 information::
  69
  70   """The command line interface to docutil's Python documentation extractor.
  71
  72   Usage: ``pysource.py <switches> <inpath> [<outfile>]``
  73
  74       <inpath> is the path to a package or module.
  75
  76       <outfile> is the path to the output file. If it's not given, then
  77       output will be written to a file with the same name as the input
  78       file, but defaulting to the current directory, and with extension
  79       derived from the type of output:
  80
  81       - show   -> ``.show``
  82       - ast    -> ``.ast``
  83       - xml    -> ``.xml``
  84       - html   -> ``.html``
  85       - pretty -> ``.pretty``
  86
  87       (unless --stdout is requested). The default is --html.
  88
  89       Note that progress messages (and ``verb`` information) are written
  90       to ``sys.stderr``.
  91   """
  92
  93       <switches> are:
  94
  95         -v, --verbose   Report on progress in more detail
  96         -q, --quiet     Suppress normal progress messages
  97         -t, --text      The input file is a plain (text) reST file
  98         -s, --show      Output basic information about the input
  99         -a, --ast       Output a representation of the AST
 100         -x, --xml       Output an XML representation of the input
 101         -h, --html      Output an HTML representation of the input [default]
 102         -p, --pretty    Output a 'pretty' representation of the input
 103         -d, --doctest   Treat a reST file as doctest input.
 104         -h, --help      Show 'help' information
 105         -n, --new       Use David Goodger's HTML Writer (sort of)
 106             --stdout    Write output to stdout, instead of a file
 107
 108 I recommend use of the ``--pretty`` option for gaining an understanding of the
 109 DPS tree itself.
 110
 111 Limitations and dependencies
 112 ----------------------------
 113 This is beta software, and is still, to some extent, a proof and exploration of
 114 concept.
 115
 116 The following limitations are obvious:
 117
 118   * Its concept of a "package" is rather limited - it doesn't understand
 119     sub-packages (i.e., it only copes with a "flat" directory structure).
 120   * It only produces a single HTML file - a more sophisticated approach
 121     is clearly needed, particularly for large packages (or even large
 122     modules).
 123   * It is not fully integrated with the Docutils HTML Writer, which it
 124     should be using in preference to my own home-grown approach.
 125   * The Docutils tree that it produces could use some improvement - in
 126     particular the Python specific nodes need various design decisions
 127     to be made.
 128
 129 Also:
 130
 131   * It doesn't throw away as much information as it should.
 132   * It doesn't check all assignments for use of global values.
 133   * It doesn't handle all Python entities that it should.
 134   * The HTML it produces is pretty yuck, and is *designed* not
 135     to look terribly nice (although you should remember not to
 136     ask my opinion of the HTML output by pydoc).
 137   * Autonumbered footnote resolution is done by the HTML writer,
 138     which means that it will likely go wrong if it needs to do
 139     anything with Python source that contains autonumbered
 140     footnotes in docstrings(!). But it does work (I believe)
 141     for .rtxt files.
 142   * Various other Docutils tree transforms that should be applied
 143     are not yet performed.
 144
 145 Subtler things:
 146
 147   * The ``--doctest`` mode just pretends that the whole file is
 148     a single doctest string (i.e., just as if doctest had found
 149     it as a docstring in a Python file).
 150
 151     That's quite sensible, except that the current doctest doesn't
 152     know that it should ignore literal blocks, and thus may find
 153     apparent Python code where it shouldn't.
 154
 155 It depends on:
 156
 157   * The latest versions of Docutils, as of the
 158     time it was uploaded (I generally track these fairly well,
 159     so am normally using the latest versions whilst developing).
 160     These should have been installed (using the setup scripts
 161     they provide).
 162   * Python 2.0 or above
 163   * Tools/compiler for the current Python. For Pythons before
 164     2.2a4 (I think it was) this should be installed using the
 165     setup script it provides (after that it comes as standard).
 166
 167 I develop it with Python 2.1 on Windows/NT and with Python 2.2 on
 168 Debian GNU/Linux.
 169
 170 Refactoring warning
 171 -------------------
 172 It is my aim to refactor this code to follow David Goodger's
 173
 174     Reader - Transformer - Writer
 175
 176 model more closely than it currently does. And there is also lots of
 177 tidying up to do (especially in `visit.py`).
 178
 179 Interesting things to do
 180 ------------------------
 181 Run it over docutils/spec/reStructuredText.txt.
 182
 183 Run it over docutils/docutils.
 184
 185 Run it over pysource/visit.py.
 186
 187 Run it over the standard string module, and compare the result with that
 188 of ``pydoc``.
 189