Commit 8be1a448 authored by Andreas Jung's avatar Andreas Jung

removed

parent ead411ac
This directory contains some third party packages.
To upgrade docutils:
- untar docutils-XX.tar.gz inside the third_party directoy
- rename it to 'docutils'
- remove docutils/tools/editors/emacs/* (files are GPLed)
- update the files in the CVS
================
Docutils_ Bugs
================
:Author: David Goodger; open to all Docutils developers
:Contact: goodger@python.org
:Date: $Date: 2004/10/29 19:08:15 $
:Revision: $Revision: 1.1.4.1 $
:Copyright: This document has been placed in the public domain.
.. _Docutils: http://docutils.sourceforge.net/
Bugs in Docutils?!? Yes, we do have a few. Some are old-timers that
tend to stay in the shadows and don't bother anybody. Once in a while
new bugs are born. From time to time some bugs (new and old) crawl
out into the light and must be dealt with. Icky.
This document describes how to report a bug, and lists known bugs.
.. contents::
How To Report A Bug
===================
If you think you've discovered a bug, please read through these
guidelines before reporting it.
First, make sure it's a new bug:
* Please check the list of `known bugs`_ below and the `SourceForge
Bug Tracker`_ to see if it has already been reported.
* Are you using the very latest version of Docutils? The bug may have
already been fixed. Please get the latest version of Docutils from
CVS_ or from the `development snapshot`_ and check again. Even if
your bug has not been fixed, others probably have, and you're better
off with the most up-to-date code.
If you don't have time to check the latest snapshot, please report
the bug anyway. We'd rather tell you that it's already fixed than
miss reports of unfixed bugs.
* If Docutils does not behave the way you expect, look in the
documentation_ (don't forget the FAQ_!) and `mailing list archives`_
for evidence that it should behave the way you expect.
If you're not sure, please ask on the
docutils-users@lists.sourceforge.net [1]_ mailing list first.
If it's a new bug, the most important thing you can do is to write a
simple description and a recipe that reproduces the bug. Try to
create a minimal document that demonstrates the bug. The easier you
make it to understand and track down the bug, the more likely a fix
will be.
Now you're ready to write the bug report. Please include:
* A clear description of the bug. Describe how you expected Docutils
to behave, and contrast that with how it actually behaved. While
the bug may seem obvious to you, it may not be so obvious to someone
else, so it's best to avoid a guessing game.
* A complete description of the environment in which you reproduced
the bug:
- Your operating system & version.
- The version of Python (``python -V``).
- The version of Docutils (use the "-V" option to most Docutils
front-end tools).
- Any private modifications you made to Docutils.
- Anything else that could possibly be relevant. Err on the side
of too much information, rather than too little.
* A literal transcript of the *exact* command you ran, and the *exact*
output. Use the "--traceback" option to get a complete picture.
* The exact input and output files. Better to attach complete files
to your bug report than to include just a summary or excerpt.
* If you also want to include speculation as to the cause, and even a
patch to fix the bug, that would be great!
The best place to send your bug report is to the `SourceForge Bug
Tracker`_. That way, it won't be misplaced or forgotten. In fact, an
open bug report on SourceForge is a constant irritant that begs to be
squashed.
Thank you!
(This section was inspired by the `Subversion project's`__ BUGS__
file.)
.. [1] Due to overwhelming amounts of spam, the
docutils-users@lists.sourceforge.net mailing list has been set up
for subscriber posting only. Non-subscribers who post to
docutils-users will receive a message with "Subject: Your message
to Docutils-users awaits moderator approval". Legitimate messages
are accepted and posted as soon as possible (a list administrator
must verify the message manually). If you'd like to subscribe to
docutils-users, please visit
<http://lists.sourceforge.net/lists/listinfo/docutils-users>.
__ http://subversion.tigris.org/
__ http://svn.collab.net/viewcvs/svn/trunk/BUGS?view=markup
.. _CVS: http://sourceforge.net/cvs/?group_id=38414
.. _development snapshot: http://docutils.sf.net/#development-snapshot
.. _documentation: docs/
.. _FAQ: FAQ.html
.. _mailing list archives: http://docutils.sf.net/#mailing-lists
.. _SourceForge Bug Tracker:
http://sourceforge.net/tracker/?group_id=38414&atid=422030
Known Bugs
==========
Also see the `SourceForge Bug Tracker`_.
* _`Line numbers` in system messages are inconsistent in the parser.
- In text inserted by the "include" directive, errors are often not
reported with the correct "source" or "line" numbers. Perhaps all
Reporter calls need "source" and "line" keyword arguments.
Elements' .line assignments should be checked. (Assign to .source
too? Add a set_info method? To what?) There's a test in
test/test_parsers/test_rst/test_directives/test_include.py.
- Some line numbers in elements are not being set properly
(explicitly), just implicitly/automatically. See rev. 1.74 of
docutils/parsers/rst/states.py for an example of how to set.
* .. _none source:
Quite a few nodes are getting a "None" source attribute as well. In
particular, see the bodies of definition lists.
* .. _mislocated targets:
Explicit targets are sometimes mis-located. In particular, placing
a target before a section header puts the target at the end of the
previous section instead of the start of the next section. The code
in docutils.transforms.misc.ClassAttribute could be used to fix
this. (Reported by David Priest.)
* David Abrahams pointed out that _`doubly-indirect substitutions`
have a bug, but only when there's multiple references::
|substitute| my coke for gin
|substitute| you for my mum
at least I'll get my washing done
.. |substitute| replace:: |replace|
.. |replace| replace:: swap
This is tricky. Substitutions have to propagate back completely.
* .. _subsitutions and references:
Another bug from David Abrahams (run with ``rst2html.py --traceback``)::
|substitution| and again a |substitution|.
.. |substitution| replace:: ref__
__ a.html
__ b.html
Change the references.Substitutions tranform's priority from 220 to
680, so it happens after reference resolution? Then we have to deal
with multiple IDs. Perhaps the Substitution transform should remove
all IDs from definitions after the first substitution reference is
processed.
..
Local Variables:
mode: indented-text
indent-tabs-mode: nil
sentence-end-double-space: t
fill-column: 70
End:
==================
Copying Docutils
==================
:Author: David Goodger
:Contact: goodger@users.sourceforge.net
:Date: $Date: 2004/10/29 19:08:15 $
:Web site: http://docutils.sourceforge.net/
:Copyright: This document has been placed in the public domain.
Most of the files included in this project have been placed in the
public domain, and therefore have no license requirements and no
restrictions on copying or usage; see the `Public Domain Dedication`_
below. There are a few exceptions_, listed below.
One goal of the Docutils project is to be included in the Python
standard library distribution, at which time it is expected that
copyright will be asserted by the `Python Software Foundation
<http://www.python.org/psf/>`_.
Public Domain Dedication
========================
The persons who have associated their work with this project (the
"Dedicator": David Goodger and the many contributors to the Docutils
project) hereby dedicate the entire copyright, less the exceptions_
listed below, in the work of authorship known as "Docutils" identified
below (the "Work") to the public domain.
The primary repository for the Work is the Internet World Wide Web
site <http://docutils.sourceforge.net/>. The Work consists of the
files within the "docutils" module of the Docutils project CVS
repository (Internet host cvs.sourceforge.net, filesystem path
/cvsroot/docutils), whose Internet web interface is located at
<http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/docutils/docutils/>.
Files dedicated to the public domain may be identified by the
inclusion, near the beginning of each file, of a declaration of the
form::
Copyright: This document/module/DTD/stylesheet/file/etc. has been
placed in the public domain.
Dedicator makes this dedication for the benefit of the public at large
and to the detriment of Dedicator's heirs and successors. Dedicator
intends this dedication to be an overt act of relinquishment in
perpetuity of all present and future rights under copyright law,
whether vested or contingent, in the Work. Dedicator understands that
such relinquishment of all rights includes the relinquishment of all
rights to enforce (by lawsuit or otherwise) those copyrights in the
Work.
Dedicator recognizes that, once placed in the public domain, the Work
may be freely reproduced, distributed, transmitted, used, modified,
built upon, or otherwise exploited by anyone for any purpose,
commercial or non-commercial, and in any way, including by methods
that have not yet been invented or conceived.
(This dedication is derived from the text of the `Creative Commons
Public Domain Dedication
<http://creativecommons.org/licenses/publicdomain>`_.)
Exceptions
==========
The exceptions to the `Public Domain Dedication`_ above are:
* extras/optparse.py, copyright by Gregory P. Ward, released under a
BSD-style license (which can be found in the module's source code).
* extras/textwrap.py, copyright by Gregory P. Ward and the Python
Software Foundation, released under the `Python 2.3 license`_
(`local copy`__).
__ licenses/python-2-3.txt
* extras/roman.py, copyright by Mark Pilgrim, released under the
`Python 2.1.1 license`_ (`local copy`__).
__ licenses/python-2-1-1.txt
* test/docutils_difflib.py, copyright by the Python Software
Foundation, released under the `Python 2.2 license`_ (`local
copy`__). This file is included for compatibility with Python
versions less than 2.2. (It's only used to report test failures
anyhow; it isn't installed anywhere. The included file is a
pre-generator version of the difflib.py module included in Python
2.2.)
__ licenses/python-2-2.txt
* tools/pep2html.py, copyright by the Python Software Foundation,
released under the `Python 2.2 license`_ (`local copy`__).
__ licenses/python-2-2.txt
* tools/editors/emacs/rst-html.el, copyright by Martin Blais, released
under the `GNU General Public License`_ (`local copy`__).
__ licenses/gpl.txt
* tools/editors/emacs/rst-mode.el, copyright by Stefan Merten,
released under the `GNU General Public License`_ (`local copy`__).
__ licenses/gpl.txt
(Disclaimer: I am not a lawyer.) The BSD license and the Python
licenses are OSI-approved_ and GPL-compatible_. Although complicated
by multiple owners and lots of legalese, the Python license basically
lets you copy, use, modify, and redistribute files as long as you keep
the copyright attribution intact, note any changes you make, and don't
use the owner's name in vain. The BSD license is similar.
Plaintext versions of all the linked-to licenses are provided in the
licenses_ directory.
.. _licenses: licenses/
.. _Python 2.1.1 license: http://www.python.org/2.1.1/license.html
.. _Python 2.2 license: http://www.python.org/2.2/license.html
.. _Python 2.3 license: http://www.python.org/2.3/license.html
.. _GNU General Public License: http://www.gnu.org/copyleft/gpl.html
.. _OSI-approved: http://opensource.org/licenses/
.. _GPL-compatible: http://www.gnu.org/philosophy/license-list.html
This diff is collapsed.
This diff is collapsed.
Metadata-Version: 1.0
Name: docutils
Version: 0.3.5
Summary: Docutils -- Python Documentation Utilities
Home-page: http://docutils.sourceforge.net/
Author: David Goodger
Author-email: goodger@users.sourceforge.net
License: public domain, Python, BSD, GPL (see COPYING.txt)
Description: Docutils is a modular system for processing documentation
into useful formats, such as HTML, XML, and LaTeX. For
input Docutils supports reStructuredText, an easy-to-read,
what-you-see-is-what-you-get plaintext markup syntax.
Platform: OS-independent
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: Intended Audience :: Other Audience
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: Public Domain
Classifier: License :: OSI Approved :: Python Software Foundation License
Classifier: License :: OSI Approved :: BSD License
Classifier: License :: OSI Approved :: GNU General Public License (GPL)
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Topic :: Documentation
Classifier: Topic :: Software Development :: Documentation
Classifier: Topic :: Text Processing
Classifier: Natural Language :: English
Classifier: Natural Language :: Afrikaans
Classifier: Natural Language :: Esperanto
Classifier: Natural Language :: French
Classifier: Natural Language :: German
Classifier: Natural Language :: Italian
Classifier: Natural Language :: Russian
Classifier: Natural Language :: Slovak
Classifier: Natural Language :: Spanish
Classifier: Natural Language :: Swedish
This diff is collapsed.
Acknowledgements
================
:Author: David Goodger
:Contact: goodger@python.org
:Date: $Date: 2004/10/29 19:08:15 $
:Revision: $Revision: 1.1.4.1 $
:Copyright: This document has been placed in the public domain.
I would like to acknowledge the people who have made a direct impact
on the Docutils project, knowingly or not, in terms of encouragement,
suggestions, criticism, bug reports, code contributions, cash
donations, tasty treats, and related projects:
* Aahz
* David Abrahams
* David Ascher
* Heiko Baumann
* Eric Bellot
* Ian Bicking
* Marek Blaha
* Martin Blais
* Stephen Boulet
* Fred Bremmer
* Simon Budig
* Bill Bumgarner
* Brett Cannon
* Greg Chapman
* Nicolas Chauveau
* Beni Cherniavsky
* Adam Chodorowski
* Brent Cook
* Laura Creighton
* Artur de Sousa Rocha
* Stephan Deibel & `Wing IDE <http://wingide.com/>`__
* Jason Diamond
* William Dode
* Fred Drake
* Reggie Dugard
* Dethe Elza
* Marcus Ertl
* Benja Fallenstein
* fantasai
* Stefane Fermigier
* Jim Fulton
* Peter Funk
* Lele Gaifax
* Dinu C. Gherman
* Matt Gilbert
* Jorge Gonzalez
* Engelbert Gruber
* Jacob Hallen
* Simon Hefti
* Doug Hellmann
* Marc Herbert
* Juergen Hermann
* Jannie Hofmeyr
* Steve Holden
* Michael Hudson
* Marcelo Huerta San Martin
* Ludger Humbert
* Jeremy Hylton
* Tony Ibbs
* Alan Jaffray
* Dmitry Jemerov
* Richard Jones
* Andreas Jung
* Garth Kidd
* Axel Kollmorgen
* Jeff Kowalczyk
* Dave Kuhlman
* Lloyd Kvam
* Kirill Lapshin
* Nicola Larosa
* Daniel Larsson
* Marc-Andre Lemburg
* Julien Letessier
* Wolfgang Lipp
* Edward Loper
* Dallas Mahrt
* Ken Manheimer
* Bob Marshall
* Mark McEahern
* Vincent McIntyre
* John F Meinel Jr
* Vasko Miroslav
* Skip Montanaro
* Paul Moore
* Nigel W. Moriarty
* Mark Nodine
* Patrick K. O'Brien
* Michel Pelletier
* Sam Penrose
* Tim Peters
* Pearu Peterson
* Mark Pilgrim
* Brett g Porter
* David Priest
* Jens Quade
* Andy Robinson
* Tavis Rudd
* Tracy Ruggles
* Oliver Rutherfurd
* Kenichi Sato
* Ueli Schlaepfer
* Gunnar Schwant
* Bill Sconce
* Frank Siebenlist
* Bruce Smith
* Darek Suchojad
* Roman Suzi
* tav
* Kent Tenney
* Bob Tolbert
* Paul Tremblay
* Laurence Tratt
* Adrian van den Dries
* Guido van Rossum
* Paul Viren
* Martin von Loewis
* Greg Ward
* Barry Warsaw
* Edward Welbourne
* Felix Wiemann
* Ka-Ping Yee
* Moshe Zadka
Thank you!
Special thanks to `SourceForge <http://sourceforge.net>`__ and the
`Python Software Foundation <http://www.python.org/psf/>`__.
Hopefully I haven't forgotten anyone or misspelled any names;
apologies (and please let me know!) if I have.
===============================================
Inside A Docutils Command-Line Front-End Tool
===============================================
:Author: David Goodger
:Contact: goodger@python.org
:Date: $Date: 2004/10/29 19:08:16 $
:Revision: $Revision: 1.1.4.1 $
:Copyright: This document has been placed in the public domain.
`The Docutils Publisher`_ class was set up to make building
command-line tools easy. All that's required is to choose components
and supply settings for variations. Let's take a look at a typical
command-line front-end tool, ``tools/rst2html.py``, from top to
bottom.
On Unixish systems, it's best to make the file executable (``chmod +x
file``), and supply an interpreter on the first line, the "shebang" or
"hash-bang" line::
#!/usr/bin/env python
Windows systems can be set up to associate the Python interpreter with
the ``.py`` extension.
Next are some comments providing metadata::
# Author: David Goodger
# Contact: goodger@python.org
# Revision: $Revision: ...
# Date: $Date: ...
# Copyright: This module has been placed in the public domain.
The module docstring describes the purpose of the tool::
"""
A minimal front end to the Docutils Publisher, producing HTML.
"""
This next block attempts to invoke locale support for
internationalization services, specifically text encoding. It's not
supported on all platforms though, so it's forgiving::
try:
import locale
locale.setlocale(locale.LC_ALL, '')
except:
pass
The real work will be done by the code that's imported here::
from docutils.core import publish_cmdline, default_description
We construct a description of the tool, for command-line help::
description = ('Generates (X)HTML documents from standalone '
'reStructuredText sources. ' + default_description)
Now we call the Publisher convenience function, which takes over.
Most of it's defaults are used ("standalone" Reader,
"reStructuredText" Parser, etc.). The HTML Writer is chosen by name,
and a description for command-line help is passed in::
publish_cmdline(writer_name='html', description=description)
That's it! `The Docutils Publisher`_ takes care of the rest.
.. _The Docutils Publisher: ./publisher.html
========================
The Docutils Publisher
========================
:Author: David Goodger
:Contact: goodger@python.org
:Date: $Date: 2004/10/29 19:08:16 $
:Revision: $Revision: 1.1.4.1 $
:Copyright: This document has been placed in the public domain.
.. contents::
Publisher Convenience Functions
===============================
Each of these functions set up a ``docutils.core.Publisher`` object,
then call its ``publish`` method. ``docutils.core.Publisher.publish``
handles everything else. There are five convenience functions in the
``docutils.core`` module:
* ``publish_cmdline``: for command-line front-end tools, like
``rst2html.py``. There are several examples in the ``tools/``
directory. A detailed analysis of one such tool is in `Inside A
Docutils Command-Line Front-End Tool`_
* ``publish_file``: for programmatic use with file-like I/O. In
addition to writing the encoded output to a file, also returns the
encoded output as a string.
* ``publish_string``: for programmatic use with string I/O. Returns
the encoded output as a string.
* ``publish_parts``: for programmatic use with string input; returns a
dictionary of document parts. Dictionary keys are the names of
parts, and values are Unicode strings; encoding is up to the client.
Useful when only portions of the processed document are desired.
Currently only implemented for the HTML Writer.
There are examples in the ``docutils/examples.py`` module.
* ``publish_programmatically``: for custom programmatic use. This
function implements common code and is used by ``publish_file``,
``publish_string``, and ``publish_parts``. It returns a 2-tuple:
the encoded string output and the Publisher object.
.. _Inside A Docutils Command-Line Front-End Tool: ./cmdline-tool.html
Configuration
-------------
To pass application-specific setting defaults to the Publisher
convenience functions, use the ``settings_overrides`` parameter. Pass
a dictionary of setting names & values, like this::
overrides = {'input_encoding': 'ascii',
'output_encoding': 'latin-1'}
output = publish_string(..., settings_overrides=overrides)
Settings from command-line options override configuration file
settings, and they override application defaults. For details, see
`Docutils Runtime Settings`_. See `Docutils Configuration Files`_ for
details about individual settings.
.. _Docutils Runtime Settings: ./runtime-settings.html
.. _Docutils Configuration Files: ../user/tools.html
Encodings
---------
The default output encoding of Docutils is UTF-8. If you have any
non-ASCII in your text, you may have to do a bit more setup. Docutils
may introduce some non-ASCII text if you use symbol-footnotes or
section numbering.
===========================
Docutils Runtime Settings
===========================
:Author: David Goodger
:Contact: goodger@python.org
:Date: $Date: 2004/10/29 19:08:16 $
:Revision: $Revision: 1.1.4.1 $
:Copyright: This document has been placed in the public domain.
.. contents::
Introduction
============
Docutils runtime settings are assembled from several sources:
component settings specifications, application settings
specifications, configuration files, and command-line options.
Docutils overlays default and explicitly specified values from these
sources such that settings behave the way we want and expect them to
behave.
To understand how Docutils deals with runtime settings, the attributes
and parameters involved must first be understood. Begin with the the
docstrings of the attributes of the ``docutils.SettingsSpec`` base
class (in the ``docutils/__init__.py`` module):
* ``settings_spec``
* ``settings_defaults``
* ``settings_default_overrides``
* ``relative_path_settings``
* ``config_section``
* ``config_section_dependencies``
Next, several _`convenience function parameters` are also significant
(described in the ``docutils.core.publish_programmatically`` function
docstring):
* ``settings``, if present, is assumed to be complete and no further
runtime settings processing is done.
* ``settings_spec`` is treated as a fourth component (after the
Parser, Reader, and Writer).
* ``settings_overrides`` is a dictionary which will override the
defaults of the components.
* ``config_section`` sets or overrides an application-specific
configuration file section.
.. _command-line tools:
Runtime Settings Processing for Command-Line Tools
==================================================
Following along with the actual code is recommended. The
``docutils/__init__.py``, ``docutils/core.py``, and
``docutils.frontend`` modules are described.
1. A command-line front-end tool imports and calls
``docutils.core.publish_cmdline``. The relevant `convenience
function parameters`_ are described above.
2. ``docutils.core.publish_cmdline`` initializes a
``docutils.core.Publisher`` object, then calls its ``publish``
method.
3. The ``docutils.core.Publisher`` object's ``publish`` method checks
its ``settings`` attribute to see if it's defined. If it is, no
further runtime settings processing is done.
If ``settings`` is not defined, ``self.process_command_line`` is
called with the following relevant arguments:
* ``settings_spec``
* ``config_section``
* ``settings_overrides`` (in the form of excess keyword
arguments, collected in the ``defaults`` parameter)
4. ``self.process_command_line`` calls ``self.setup_option_parser``,
passing ``settings_spec``, ``config_section``, and ``defaults``.
5. ``self.setup_option_parser`` checks its ``config_section``
parameter; if defined, it adds that config file section to
``settings_spec`` (or to a new, empty ``docutils.SettingsSpec``
object), replacing anything defined earlier. (See `Docutils
Configuration Files`_ for details.) Then it instantiates a new
``docutils.frontend.OptionParser`` object, passing the following
relevant arguments:
* ``components``: A tuple of ``docutils.SettingsSpec`` objects,
``(self.parser, self.reader, self.writer, settings_spec)``
* ``defaults`` (originally from ``settings_overrides``)
6. The ``docutils.frontend.OptionParser`` object's ``__init__`` method
calls ``self.populate_from_components`` with ``self.components``,
which consists of ``self`` prepended to the ``components`` tuple it
received. ``self`` (``docutils.frontend.OptionParser``) defines
general Docutils settings.
7. In ``self.populate_from_components``, for each component passed,
``component.settings_spec`` is processed and
``component.settings_defaults`` is applied. Then, for each
component, ``component.settings_default_overrides`` is applied.
This two-loop process ensures that
``component.settings_default_overrides`` can override the default
settings of any other component.
8. Back in ``docutils.frontend.OptionParser.__init__``, the
``defaults`` parameter (derived from the ``settings_overrides``
parameter of ``docutils.core.Publisher.publish``) is overlaid over
``self.defaults``. So ``settings_overrides`` has priority over all
``SettingsSpec`` data.
9. Next, ``docutils.frontend.OptionParser.__init__`` checks if
configuration files are enabled (its ``read_config_files``
parameter is true, and ``self.defaults['_disable_config']`` is
false). If they are enabled (and normally, they are),
``self.get_standard_config_settings`` is called. This reads the
`docutils configuration files`_, and returns a dictionary of
settings. This is then overlaid on ``self.defaults``. So
configuration file settings have priority over all software-defined
defaults.
10. Back in the ``docutils.core.Publisher`` object,
``self.setup_option_parser`` returns the ``option_parser`` object
to its caller, ``self.process_command_line``.
11. ``self.process_command_line`` calls ``option_parser.parse_args``,
which parses all command line options and returns a
``docutils.frontend.Values`` object. This is assigned to the
``docutils.core.Publisher`` object's ``self.settings``. So
command-line options have priority over configuration file
settings.
When ``option_parser.parse_args`` is called, the source and
destination command-line arguments are also parsed, and assigned
to the ``_source`` and ``_destination`` attributes of what becomes
the ``docutils.core.Publisher`` object's ``self.settings``.
12. From ``docutils.core.Publisher.publish``, ``self.set_io`` is
called with no arguments. If either ``self.source`` or
``self.destination`` are not set, the corresponding
``self.set_source`` and ``self.set_destination`` are called,
effectively with no arguments.
13. ``self.set_source`` checks for a ``source_path`` parameter, and if
there is none (which is the case for command-line use), it is
taken from ``self.settings._source``. ``self.source`` is set by
instantiating a ``self.source_class`` object. For command-line
front-end tools, the default ``self.source_class`` is used,
``docutils.io.FileInput``.
14. ``self.set_destination`` does the same job for the destination
that ``self.set_source`` does for the source (the default
``self.destination_class`` is ``docutils.io.FileOutput``).
.. _Docutils Configuration Files: ../user/tools.html
Runtime Settings Processing From Applications
=============================================
Applications process runtime settings in a significantly different way
than `command-line tools`_ do. Instead of calling
``publish_cmdline``, the application calls one of ``publish_file``,
``publish_string``, or ``publish_parts``. These in turn call
``publish_programmatically``, which implements a generic programmatic
interface. Although an application may also call
``publish_programmatically`` directly, it is not recommended (if it
does seem to be necessary, please write to the `Docutils-Develop
mailing list`_).
``publish_programmatically`` accepts the same `convenience function
parameters`_ as ``publish_cmdline``. Where things differ is that
programmatic use does not
TO BE COMPLETED.
.. copy & modify the list from command-line tools?
.. _Docutils-Develop mailing list: docutils-develop@lists.sf.net
==================================
Enthought API Documentation Tool
==================================
-----------------------
Request for Proposals
-----------------------
:Author: Janet Swisher, Senior Technical Writer
:Organization: `Enthought, Inc. <http://www.enthought.com>`_
:Copyright: 2004 by Enthought, Inc.
:License: `Enthought License`_ (BSD Style)
.. _Enthought License: http://docutils.sf.net/licenses/enthought.txt
The following is excerpted from the full RFP, and is published here
with permission from `Enthought, Inc.`_ See the `Plan for Enthought
API Documentation Tool`__.
__ enthought-plan.html
.. contents::
.. sectnum::
Requirements
============
The documentation tool will address the following high-level goals:
Documentation Extraction
------------------------
1. Documentation will be generated directly from Python source code,
drawing from the code structure, docstrings, and possibly other
comments.
2. The tool will extract logical constructs as appropriate, minimizing
the need for comments that are redundant with the code structure.
The output should reflect both documented and undocumented
elements.
Source Format
-------------
1. The docstrings will be formatted in as terse syntax as possible.
Required tags, syntax, and white space should be minimized.
2. The tool must support the use of Traits. Special comment syntax
for Traits may be necessary. Information about the Traits package
is available at http://old.scipy.org/site_content/traits. In the
following example, each trait definition is prefaced by a plain
comment::
__traits__ = {
# The current selection within the frame.
'selection' : Trait([], TraitInstance(list)),
# The frame has been activated or deactivated.
'activated' : TraitEvent(),
'closing' : TraitEvent(),
# The frame is closed.
'closed' : TraitEvent(),
}
3. Support for ReStructuredText (ReST) format is desirable, because
much of the existing docstrings uses ReST. However, the complete
ReST specification need not be supported, if a subset can achieve
the project goals. If the tool does not support ReST, the
contractor should also provide a tool or path to convert existing
docstrings.
Output Format
-------------
1. Documentation will be output as a navigable suite of HTML
files.
2. The style of the HTML files will be customizable by a cascading
style sheet and/or a customizable template.
3. Page elements such as headers and footer should be customizable, to
support differing requirements from one documentation project to
the next.
Output Structure and Navigation
-------------------------------
1. The navigation scheme for the HTML files should not rely on frames,
and should harmonize with conversion to Microsoft HTML Help (.chm)
format.
2. The output should be structured to make navigable the architecture
of the Python code. Packages, modules, classes, traits, and
functions should be presented in clear, logical hierarchies.
Diagrams or trees for inheritance, collaboration, sub-packaging,
etc. are desirable but not required.
3. The output must include indexes that provide a comprehensive view
of all packages, modules, and classes. These indexes will provide
readers with a clear and exhaustive view of the code base. These
indexes should be presented in a way that is easily accessible and
allows easy navigation.
4. Cross-references to other documented elements will be used
throughout the documentation, to enable the reader to move quickly
relevant information. For example, where type information for an
element is available, the type definition should be
cross-referenced.
5. The HTML suite should provide consistent navigation back to the
home page, which will include the following information:
* Bibliographic information
- Author
- Copyright
- Release date
- Version number
* Abstract
* References
- Links to related internal docs (i.e., other docs for the same
product)
- Links to related external docs (e.g., supporting development
docs, Python support docs, docs for included packages)
It should be possible to specify similar information at the top
level of each package, so that packages can be included as
appropriate for a given application.
License
=======
Enthought intends to release the software under an open-source
("BSD-style") license.
This diff is collapsed.
<!--
======================================================================
Docutils Python Source DTD
======================================================================
:Author: David Goodger
:Contact: goodger@users.sourceforge.net
:Revision: $Revision: 1.1.4.1 $
:Date: $Date: 2004/10/29 19:08:16 $
:Copyright: This DTD has been placed in the public domain.
:Filename: pysource.dtd
This DTD (document type definition) extends the Generic DTD (see
below).
More information about this DTD and the Docutils project can be found
at http://docutils.sourceforge.net/. The latest version of this DTD
is available from
http://docutils.sourceforge.net/docs/dev/pysource.dtd.
The formal public identifier for this DTD is::
+//IDN docutils.sourceforge.net//DTD Docutils Python Source//EN//XML
-->
<!--
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Parameter Entity Overrides
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-->
<!ENTITY % additional.section.elements
" | package_section | module_section | class_section
| method_section | function_section
| module_attribute_section | function_attribute_section
| class_attribute_section | instance_attribute_section ">
<!ENTITY % additional.inline.elements
" | package | module | class | method | function
| variable | parameter | type | attribute
| module_attribute | class_attribute | instance_attribute
| exception_class | warning_class ">
<!--
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Generic DTD
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This DTD extends the Docutils Generic DTD, available from
http://docutils.sourceforge.net/docs/ref/docutils.dtd.
-->
<!ENTITY % docutils PUBLIC
"+//IDN python.org//DTD Docutils Generic//EN//XML"
"docutils.dtd">
%docutils;
<!--
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Additional Section Elements
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-->
<!ELEMENT package_section
(package, fullname?, import_list?, %structure.model;)>
<!ATTLIST package_section %basic.atts;>
<!ELEMENT module_section
(module, fullname?, import_list?, %structure.model;)>
<!ATTLIST module_section %basic.atts;>
<!ELEMENT class_section
(class, inheritance_list?, fullname?, subclasses?,
%structure.model;)>
<!ATTLIST class_section %basic.atts;>
<!ELEMENT method_section
(method, parameter_list?, fullname?, overrides?,
%structure.model;)>
<!ATTLIST method_section %basic.atts;>
<!ELEMENT function_section
(function, parameter_list?, fullname?, %structure.model;)>
<!ATTLIST function_section %basic.atts;>
<!ELEMENT module_attribute_section
(attribute, initial_value?, fullname?, %structure.model;)>
<!ATTLIST module_attribute_section %basic.atts;>
<!ELEMENT function_attribute_section
(attribute, initial_value?, fullname?, %structure.model;)>
<!ATTLIST function_attribute_section %basic.atts;>
<!ELEMENT class_attribute_section
(attribute, initial_value?, fullname?, overrides?,
%structure.model;)>
<!ATTLIST class_attribute_section %basic.atts;>
<!ELEMENT instance_attribute_section
(attribute, initial_value?, fullname?, overrides?,
%structure.model;)>
<!ATTLIST instance_attribute_section %basic.atts;>
<!--
Section Subelements
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-->
<!ELEMENT fullname
(package | module | class | method | function | attribute)+>
<!ATTLIST fullname %basic.atts;>
<!ELEMENT import_list (import_item+)>
<!ATTLIST import_list %basic.atts;>
<!--
Support ``import module``, ``import module as alias``, ``from module
import identifier``, and ``from module import identifier as alias``.
-->
<!ELEMENT import_item (fullname, identifier?, alias?)>
<!ATTLIST import_item %basic.atts;>
<!ELEMENT inheritance_list (class+)>
<!ATTLIST inheritance_list %basic.atts;>
<!ELEMENT subclasses (class+)>
<!ATTLIST subclasses %basic.atts;>
<!ELEMENT parameter_list
((parameter_item+, optional_parameters*) | optional_parameters+)>
<!ATTLIST parameter_list %basic.atts;>
<!ELEMENT parameter_item
((parameter | parameter_tuple), parameter_default?)>
<!ATTLIST parameter_item %basic.atts;>
<!ELEMENT optional_parameters (parameter_item+, optional_parameters*)>
<!ATTLIST optional_parameters %basic.atts;>
<!ELEMENT parameter_tuple (parameter | parameter_tuple)+>
<!ATTLIST parameter_tuple %basic.atts;>
<!ELEMENT parameter_default (#PCDATA)>
<!ATTLIST parameter_default %basic.atts;>
<!ELEMENT overrides (fullname+)>
<!ATTLIST overrides %basic.atts;>
<!ELEMENT initial_value (#PCDATA)>
<!ATTLIST initial_value %basic.atts;>
<!--
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Additional Inline Elements
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-->
<!-- Also used as the `package_section` identifier/title. -->
<!ELEMENT package (#PCDATA)>
<!ATTLIST package
%basic.atts;
%reference.atts;>
<!-- Also used as the `module_section` identifier/title. -->
<!ELEMENT module (#PCDATA)>
<!ATTLIST module
%basic.atts;
%reference.atts;>
<!--
Also used as the `class_section` identifier/title, and in the
`inheritance` element.
-->
<!ELEMENT class (#PCDATA)>
<!ATTLIST class
%basic.atts;
%reference.atts;>
<!-- Also used as the `method_section` identifier/title. -->
<!ELEMENT method (#PCDATA)>
<!ATTLIST method
%basic.atts;
%reference.atts;>
<!-- Also used as the `function_section` identifier/title. -->
<!ELEMENT function (#PCDATA)>
<!ATTLIST function
%basic.atts;
%reference.atts;>
<!--
??? Use this instead of the ``*_attribute`` elements below? Add a
"type" attribute to differentiate?
Also used as the identifier/title for `module_attribute_section`,
`class_attribute_section`, and `instance_attribute_section`.
-->
<!ELEMENT attribute (#PCDATA)>
<!ATTLIST attribute
%basic.atts;
%reference.atts;>
<!--
Also used as the `module_attribute_section` identifier/title. A module
attribute is an exported module-level global variable.
-->
<!ELEMENT module_attribute (#PCDATA)>
<!ATTLIST module_attribute
%basic.atts;
%reference.atts;>
<!-- Also used as the `class_attribute_section` identifier/title. -->
<!ELEMENT class_attribute (#PCDATA)>
<!ATTLIST class_attribute
%basic.atts;
%reference.atts;>
<!--
Also used as the `instance_attribute_section` identifier/title.
-->
<!ELEMENT instance_attribute (#PCDATA)>
<!ATTLIST instance_attribute
%basic.atts;
%reference.atts;>
<!ELEMENT variable (#PCDATA)>
<!ATTLIST variable
%basic.atts;
%reference.atts;>
<!-- Also used in `parameter_list`. -->
<!ELEMENT parameter (#PCDATA)>
<!ATTLIST parameter
%basic.atts;
%reference.atts;
excess_positional %yesorno; #IMPLIED
excess_keyword %yesorno; #IMPLIED>
<!ELEMENT type (#PCDATA)>
<!ATTLIST type
%basic.atts;
%reference.atts;>
<!ELEMENT exception_class (#PCDATA)>
<!ATTLIST exception_class
%basic.atts;
%reference.atts;>
<!ELEMENT warning_class (#PCDATA)>
<!ATTLIST warning_class
%basic.atts;
%reference.atts;>
<!--
Local Variables:
mode: sgml
indent-tabs-mode: nil
fill-column: 70
End:
-->
======================
Python Source Reader
======================
:Author: David Goodger
:Contact: goodger@users.sourceforge.net
:Revision: $Revision: 1.1.4.1 $
:Date: $Date: 2004/10/29 19:08:16 $
:Copyright: This document has been placed in the public domain.
This document explores issues around extracting and processing
docstrings from Python modules.
For definitive element hierarchy details, see the "Python Plaintext
Document Interface DTD" XML document type definition, pysource.dtd_
(which modifies the generic docutils.dtd_). Descriptions below list
'DTD elements' (XML 'generic identifiers' or tag names) corresponding
to syntax constructs.
.. contents::
Model
=====
The Python Source Reader ("PySource") model that's evolving in my mind
goes something like this:
1. Extract the docstring/namespace [#]_ tree from the module(s) and/or
package(s).
.. [#] See `Docstring Extractor`_ below.
2. Run the parser on each docstring in turn, producing a forest of
doctrees (per nodes.py).
3. Join the docstring trees together into a single tree, running
transforms:
- merge hyperlinks
- merge namespaces
- create various sections like "Module Attributes", "Functions",
"Classes", "Class Attributes", etc.; see pysource.dtd_
- convert the above special sections to ordinary doctree nodes
4. Run transforms on the combined doctree. Examples: resolving
cross-references/hyperlinks (including interpreted text on Python
identifiers); footnote auto-numbering; first field list ->
bibliographic elements.
(Or should step 4's transforms come before step 3?)
5. Pass the resulting unified tree to the writer/builder.
I've had trouble reconciling the roles of input parser and output
writer with the idea of modes ("readers" or "directors"). Does the
mode govern the tranformation of the input, the output, or both?
Perhaps the mode should be split into two.
For example, say the source of our input is a Python module. Our
"input mode" should be the "Python Source Reader". It discovers (from
``__docformat__``) that the input parser is "reStructuredText". If we
want HTML, we'll specify the "HTML" output formatter. But there's a
piece missing. What *kind* or *style* of HTML output do we want?
PyDoc-style, LibRefMan style, etc. (many people will want to specify
and control their own style). Is the output style specific to a
particular output format (XML, HTML, etc.)? Is the style specific to
the input mode? Or can/should they be independent?
I envision interaction between the input parser, an "input mode" , and
the output formatter. The same intermediate data format would be used
between each of these, being transformed as it progresses.
Docstring Extractor
===================
We need code that scans a parsed Python module, and returns an ordered
tree containing the names, docstrings (including attribute and
additional docstrings), and additional info (in parentheses below) of
all of the following objects:
- packages
- modules
- module attributes (+ values)
- classes (+ inheritance)
- class attributes (+ values)
- instance attributes (+ values)
- methods (+ formal parameters & defaults)
- functions (+ formal parameters & defaults)
(Extract comments too? For example, comments at the start of a module
would be a good place for bibliographic field lists.)
In order to evaluate interpreted text cross-references, namespaces for
each of the above will also be required.
See python-dev/docstring-develop thread "AST mining", started on
2001-08-14.
Interpreted Text
================
DTD elements: package, module, class, method, function,
module_attribute, class_attribute, instance_attribute, variable,
parameter, type, exception_class, warning_class.
To classify identifiers explicitly, the role is given along with the
identifier in either prefix or suffix form::
Use :method:`Keeper.storedata` to store the object's data in
`Keeper.data`:instance_attribute:.
The role may be one of 'package', 'module', 'class', 'method',
'function', 'module_attribute', 'class_attribute',
'instance_attribute', 'variable', 'parameter', 'type',
'exception_class', 'exception', 'warning_class', or 'warning'. Other
roles may be defined.
.. _pysource.dtd: pysource.dtd
.. _docutils.dtd: ../ref/docutils.dtd
..
Local Variables:
mode: indented-text
indent-tabs-mode: nil
fill-column: 70
End:
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
# Author: David Goodger
# Contact: goodger@users.sourceforge.net
# Revision: $Revision: 1.1.4.1 $
# Date: $Date: 2004/10/29 19:08:21 $
# Copyright: This module has been placed in the public domain.
# Internationalization details are documented in
# <http://docutils.sf.net/docs/howto/i18n.html>.
"""
This package contains modules for language-dependent features of Docutils.
"""
__docformat__ = 'reStructuredText'
_languages = {}
def get_language(language_code):
if _languages.has_key(language_code):
return _languages[language_code]
module = __import__(language_code, globals(), locals())
_languages[language_code] = module
return module
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment