diff options
Diffstat (limited to 'sandbox/tibs/pysource/doc')
| -rw-r--r-- | sandbox/tibs/pysource/doc/readme.rtxt | 189 | ||||
| -rw-r--r-- | sandbox/tibs/pysource/doc/whythis.rtxt | 122 |
2 files changed, 0 insertions, 311 deletions
diff --git a/sandbox/tibs/pysource/doc/readme.rtxt b/sandbox/tibs/pysource/doc/readme.rtxt deleted file mode 100644 index 5710eaa53..000000000 --- a/sandbox/tibs/pysource/doc/readme.rtxt +++ /dev/null @@ -1,189 +0,0 @@ -pysource -======== - -:Author: Tibs (tibs@tibsnjoan.co.uk) -:Date: $Date$ -:Revision: $Revision$ -:Version: 0.1 - -Ahem ----- -This file needs updating - unless this notice has disappeared, treat the -rest of the file as out-of-date... - -History -------- -2002-04: - -* Name changed from 'pydps' to 'pysource' (in line with a suggestion - made a while back on the Doc-SIG by David Goodger). - - It's not that that's a great name, just that it's better than 'pydps' - (especially now that 'dps' has become 'docutils'), and the rather more - obvious 'pydoc' is already taken. Any suggestions for a better name will - be gratefully received! - -* Converted from the old 'dps' and 'restructuredtext' packages to the - new 'docutils' package. - -* All previous history is elided with the change of name and first release... - -Obtaining the package ---------------------- -The latest version of 'pysource' may be found in the Docutils sandbox -(tarball_ and browsable_). - -.. _tarball: http://docutils.sourceforge.net/docutils-sandbox-snapshot.tgz -.. _browsable: http://docutils.sourceforge.net/sandbox/tibs/pysource/ - -I hope to keep a copy of the current "released" version at - - http://www.tibsnjoan.co.uk/reST/pysource.tgz - -Purpose -------- -This module provides code to - - * parse a Python file using the Python Compiler module, which is - standard with Python 2.2 and later, and available in the Tools - directory in earlier versions, - * extract relevant information, including docstrings, - * and ultimately produce (in the first instance) HTML documentation - therefrom. - -As a subsidiary capability, it can read a restructuredtext file and produce -HTML from that. - -There are obviously other tools which perform similar tasks - see the -accompanying file whythis.rtxt for some comparisons, and an -explanation of why I think it is worth developing this tool -independently. - - -*** TO HERE *** - -Usage ------ -The command ``python pysource/pysource.py --help`` gives the following -information:: - - """The command line interface to docutil's Python documentation extractor. - - Usage: ``pysource.py <switches> <inpath> [<outfile>]`` - - <inpath> is the path to a package or module. - - <outfile> is the path to the output file. If it's not given, then - output will be written to a file with the same name as the input - file, but defaulting to the current directory, and with extension - derived from the type of output: - - - show -> ``.show`` - - ast -> ``.ast`` - - xml -> ``.xml`` - - html -> ``.html`` - - pretty -> ``.pretty`` - - (unless --stdout is requested). The default is --html. - - Note that progress messages (and ``verb`` information) are written - to ``sys.stderr``. - """ - - <switches> are: - - -v, --verbose Report on progress in more detail - -q, --quiet Suppress normal progress messages - -t, --text The input file is a plain (text) reST file - -s, --show Output basic information about the input - -a, --ast Output a representation of the AST - -x, --xml Output an XML representation of the input - -h, --html Output an HTML representation of the input [default] - -p, --pretty Output a 'pretty' representation of the input - -d, --doctest Treat a reST file as doctest input. - -h, --help Show 'help' information - -n, --new Use David Goodger's HTML Writer (sort of) - --stdout Write output to stdout, instead of a file - -I recommend use of the ``--pretty`` option for gaining an understanding of the -DPS tree itself. - -Limitations and dependencies ----------------------------- -This is beta software, and is still, to some extent, a proof and exploration of -concept. - -The following limitations are obvious: - - * Its concept of a "package" is rather limited - it doesn't understand - sub-packages (i.e., it only copes with a "flat" directory structure). - * It only produces a single HTML file - a more sophisticated approach - is clearly needed, particularly for large packages (or even large - modules). - * It is not fully integrated with the Docutils HTML Writer, which it - should be using in preference to my own home-grown approach. - * The Docutils tree that it produces could use some improvement - in - particular the Python specific nodes need various design decisions - to be made. - -Also: - - * It doesn't throw away as much information as it should. - * It doesn't check all assignments for use of global values. - * It doesn't handle all Python entities that it should. - * The HTML it produces is pretty yuck, and is *designed* not - to look terribly nice (although you should remember not to - ask my opinion of the HTML output by pydoc). - * Autonumbered footnote resolution is done by the HTML writer, - which means that it will likely go wrong if it needs to do - anything with Python source that contains autonumbered - footnotes in docstrings(!). But it does work (I believe) - for .rtxt files. - * Various other Docutils tree transforms that should be applied - are not yet performed. - -Subtler things: - - * The ``--doctest`` mode just pretends that the whole file is - a single doctest string (i.e., just as if doctest had found - it as a docstring in a Python file). - - That's quite sensible, except that the current doctest doesn't - know that it should ignore literal blocks, and thus may find - apparent Python code where it shouldn't. - -It depends on: - - * The latest versions of Docutils, as of the - time it was uploaded (I generally track these fairly well, - so am normally using the latest versions whilst developing). - These should have been installed (using the setup scripts - they provide). - * Python 2.0 or above - * Tools/compiler for the current Python. For Pythons before - 2.2a4 (I think it was) this should be installed using the - setup script it provides (after that it comes as standard). - -I develop it with Python 2.1 on Windows/NT and with Python 2.2 on -Debian GNU/Linux. - -Refactoring warning -------------------- -It is my aim to refactor this code to follow David Goodger's - - Reader - Transformer - Writer - -model more closely than it currently does. And there is also lots of -tidying up to do (especially in `visit.py`). - -Interesting things to do ------------------------- -Run it over docutils/spec/reStructuredText.txt. - -Run it over docutils/docutils. - -Run it over pysource/visit.py. - -Run it over the standard string module, and compare the result with that -of ``pydoc``. - diff --git a/sandbox/tibs/pysource/doc/whythis.rtxt b/sandbox/tibs/pysource/doc/whythis.rtxt deleted file mode 100644 index 0307654a2..000000000 --- a/sandbox/tibs/pysource/doc/whythis.rtxt +++ /dev/null @@ -1,122 +0,0 @@ -Why pysource? -============= - -There is the question of why a new tool is needed to go with Docutils and -reStructuredText, when there are several existing tools which could have been -adopted. - -Perhaps the main reason is simply as a "proof of concept" - even if pysource -itself is not adopted as *the* tool for use in documenting Python source files -(and I certainly would not advocate that it be the only one, as other tools -present their own particular advantages), it *is* worth doing as a "proof of -concept" - as an examplar that it is possible to do the job. - -Three existing tools deserve particular consideration: - - - pydoc - - HappyDoc - - PyPaSax - -pydoc ------ - -pydoc is Ka-Ping Yee's classic application. It is now (as of Python 2.1) -included in the standard Python library, where it also provides the backbone -for the "help" command. - -pydoc uses introspection of "live" objects to determine information - that is, -it requires that the modules to be documented be imported. This can be a -limiting factor - sometimes it is not advisable to import a module, and -sometimes it is simply not possible. - -It provides output as HTML, and also has a rather output mode for use at -a terminal. - -.. note: - I've still to work out how to make pydoc work as a standalone tool - (i.e., at the terminal prompt) for documenting my own Python code - - for instance, doing ``pydoc.py pysource/visit.py``, which, at best, - doesn't seem to see any documentation! - -HappyDoc --------- - - http://happydoc.sourceforge.net/ - -HappyDoc is a seriously neat tool, and one of the longest standing in the -arena. It is a mature tool, and: - - - supports several forms of structured text within docstrings - notably - plain text, "raw" text, StructuredTextClassic and StructuredTextNG. - - - allows the extraction of documentation from comments as well as from - docstrings. - - - supports several forms of output - notably HTML, SGML and XML DocBook, - plain text, and Dia files. - - - has documented mechanisms for adding new import and export filters. - - - has sophisticated control over the actual details of export (HTML options, - single or multiple files, etc.) - -I would expect it to add support for reStructuredText in the near future. - -PyPaSax -------- - - http://www.logilab.org/pypasax/ - -PyPaSax is a Python module that uses the python parser to generate Sax2 events, -and thus enables the visualisation of a python document as an XML tree. This is -used at Logilab for documenting the source code of Narval. Logilab are also -working on an XSL transformation to generate XMI from the generated XML, which -should allow interface to UML tools. - -This is a very interesting approach to the problem of extracting information -from Python modules, but it is currently relatively "coarse grained" - it does -not, for instance, pay attention to docstrings. - -pysource --------- - -http://docutils.sourceforge.net/sandbox/pysource/ (or from the tarball_). - -.. _tarball: http://docutils.sourceforge.net/docutils-sandbox-snapshot.tgz - -pysource is intended as a proof-of-concept implementation of the concepts in -the Docutils PEPs. - -It parses Python files using the Compiler module, honouring the __docformat__ -module value to decide whether docstrings are in reStructuredText or plain -text. - -It uses Docutils to organise the information so gained, and the results of -parsing the Python code are integrated with the parsed docstring text into a -single Docutils nodes tree. - -The initial version of pysource supports the output of XML (which is a native -ability of Docutils itself), and HTML. Since it is intended that pysource -integrate closely with Docutils, additional output formats will occur as new -Writers are added to Docutils itself. - -See also --------- -pep-0256: Docstring Processing System Framework - - This includes a closer analysis of why pydoc is not directly suitable - for the purposes of Docutils. - -pep-0257: Docstring conventions - - This describes the high-level structure of docstrings. - -pep-0258: Docutils Design Specification - - This includes a description of what a tool such as pysource should - actually do - what docstrings to extract and from where, and how to - decide what format is used within said docstrings. - -pep-0287: reStructuredText Standard Docstring Format - - The PEP for reStructuredText itself. |