sandbox/tibs/pysource2/log.txt

   1 =============================
   2 Writing and testing pysource2
   3 =============================
   4
   5 :Author: Tibs
   6 :Contact: tibs@tibsnjoan.co.uk
   7 :Revision: $Revision$
   8 :Date: $Date$
   9 :Copyright: This document has been placed in the public domain.
  10
  11 pysource2 is my attempt to rewrite the original pysource. pysource
  12 itself was a proof-of-concept module to find docstrings withing Python
  13 source files and present them as (by default) HTML documentation, as
  14 described by the Docutils project. Since it was written before the
  15 Docutils codebase became stabilised around its current Reader/Writer
  16 patterns, it doesn't really mesh well with the current approaches. Also,
  17 lots of the code is fairly grotty anyway, and could do with a rewrite on
  18 principle - not least because it is not well tested.
  19
  20 So, pysource2 is both that rewrite, and also an attempt on my part to
  21 learn how to do test driven development.
  22
  23 Setting the path
  24 ================
  25
  26 I want to take my docutils stuff directly from the source directories,
  27 so that I work with the latest CVS code, and don't have to keep installing
  28 things. Thus I need to set the Python path to point to the source
  29 directories::
  30
  31     export PYTHONPATH=${PYTHONPATH}:${HOME}/docutils
  32
  33 Since I'm using Python 2.2.3, I also need the modules in the "extras"
  34 directory::
  35
  36     export PYTHONPATH=${PYTHONPATH}:${HOME}/docutils/extras
  37
  38 If I want access to the testing stuff, I also need the "test"
  39 directory::
  40
  41     export PYTHONPATH=${PYTHONPATH}:${HOME}/docutils/test
  42
  43
  44 NB: Relies upon the code in docutils/docutils/readers/python/moduleparser.py
  45
  46 Log
  47 ===
  48 The "obvious" place to start is with packages - the previous pysource
  49 never did quite get them right (for a start, it wouldn't cope with
  50 sub-packages). Also, having a utility to report on packages, then on
  51 modules, and gradually on to finer levels of detail, seems like giving
  52 something useful as soon as possible.
  53
  54 It looked over-complex to adopt the docutils test framework itself,
  55 initially, especially since I am new both to unit testing *and* to test
  56 driven development. So I am being less ambitious, and working with
  57 "pure" unit tests - I reckon I'll learn more that way.
  58
  59 So, the first pass gives me package.py and test_package.py.
  60
  61 My first impressions of (such a little bit of) development is that TDD
  62 does indeed give one the feeling of reassurance I'd expected from my
  63 half-TDD efforts in Java at LSL.
  64
  65 Initially, I was looking to detect a request for a package that didn't
  66 exist, or wasn't a directory file, explicitly, with dedicated
  67 exceptions. This felt rather over-complex, and indeed refactoring those
  68 tests out and just catching a (non-explicit) OSError in the tests works
  69 well enough - in reality, a user is not going to ask to parse a package
  70 that is not already known to be an existant directory (heck, the "user"
  71 is probably a program that's just figured out if the thing whose
  72 documentation is wanted is a file or a directory), and if they do then
  73 OSError makes sense since it is what one would normally get.
  74
  75 \f
  76 Questions
  77 =========
  78
  79 * Should we attempt to parse files that don't end in ".py"?
  80
  81   What about ".pyw"?
  82
  83   What about Python files on Unix which have had their extension removed and
  84   been made executable?
  85
  86 * Should there be an option to produce a document for a directory of Python
  87   files that is not a package - e.g., a directory of useful scripts put
  88   together just to be on the UNIX path, or Python's own library.
  89
  90
  91 TODO
  92 ====
  93
  94  * Add a method to Module to indicate if it has an Attribute called
  95    __docformat__, and if so, what its value is.
  96
  97  * That requires understanding how the testing for the moduleparser is
  98    organised and works, so I can add an appropriate test.
  99
 100  * At which stage, should I incorporate Package (and NotPython) therein?
 101
 102  * Write a simple transform (first learn how!) to parse any Docstring
 103    contents in a module with __docformat__ equal to one of the reStructuredText
 104    indicators.
 105
 106  * Write another transform to turn the Pythonic doctree into a standard one.
 107
 108  * At which point, we'll have something useful, albeit not very powerful,
 109    so provide an appropriate command line interface for (at least) HTML output.
 110
 111  * Work out how to do attribute references, etc., in *this* context (I have
 112    no idea if the mechanisms from the original pysource will be any use).
 113