#
# You can set these variables from the command line.
-PYTHON ?= python
-SVNROOT ?= http://svn.python.org/projects
-SPHINXOPTS ?=
+PYTHON = python
+SVNROOT = http://svn.python.org/projects
+SPHINXOPTS =
ALLSPHINXOPTS = -b$(BUILDER) -dbuild/doctrees $(SPHINXOPTS) . build/$(BUILDER)
htmlhelp: BUILDER = htmlhelp
htmlhelp: build
@echo "Build finished; now you can run HTML Help Workshop with the" \
- "build/hhp/pydoc.hhp project file."
+ "build/htmlhelp/pydoc.hhp project file."
clean:
-rm -rf build/*
The ``synopsis`` option should consist of one sentence describing the
module's purpose -- it is currently only used in the Global Module Index.
+ The ``deprecated`` option can be given (with no value) to mark a module as
+ deprecated; it will be designated as such in various locations then.
+
.. describe:: moduleauthor
The ``moduleauthor`` directive, which can appear multiple times, names the
``:func:`foo.filter``` clearly refers to the ``filter`` function in the ``foo``
module.
+Normally, names in these roles are searched first without any further
+qualification, then with the current module name prepended, then with the
+current module and class name (if any) prepended. If you prefix the name with a
+dot, this order is reversed. For example, in the documentation of the
+:mod:`codecs` module, ``:func:`open``` always refers to the built-in function,
+while ``:func:`.open``` refers to :func:`codecs.open`.
+
A similar heuristic is used to determine whether the name is an attribute of
the currently documented class.
samples in a file. AIFF-C is a newer version of the format that includes the
ability to compress the audio data.
-**Caveat:** Some operations may only work under IRIX; these will raise
-:exc:`ImportError` when attempting to import the :mod:`cl` module, which is only
-available on IRIX.
+.. warning::
+
+ Some operations may only work under IRIX; these will raise :exc:`ImportError`
+ when attempting to import the :mod:`cl` module, which is only available on IRIX.
Audio files have a number of parameters that describe the audio data. The
sampling rate or frame rate is the number of times per second the sound is
(``'single'``, the default) or as an expression (``'eval'``). Any other value
will cause :exc:`ValueError` to be raised.
- **Caveat:** It is possible (but not likely) that the parser stops parsing with a
- successful outcome before reaching the end of the source; in this case, trailing
- symbols may be ignored instead of causing an error. For example, a backslash
- followed by two newlines may be followed by arbitrary garbage. This will be
- fixed once the API for the parser is better.
+ .. warning::
+
+ It is possible (but not likely) that the parser stops parsing with a
+ successful outcome before reaching the end of the source; in this case,
+ trailing symbols may be ignored instead of causing an error. For example,
+ a backslash followed by two newlines may be followed by arbitrary garbage.
+ This will be fixed once the API for the parser is better.
.. class:: Compile()
it is deleted when the output file is closed. In-place filtering is disabled
when standard input is read.
-**Caveat:** The current implementation does not work for MS-DOS 8+3 filesystems.
+.. warning::
+
+ The current implementation does not work for MS-DOS 8+3 filesystems.
-The two following opening hooks are provided by this module:
+The two following opening hooks are provided by this module:
.. function:: hook_compressed(filename, mode)
Finds the caller's source filename and line number. Returns the filename, line
number and function name as a 3-element tuple.
- .. versionchanged:: 2.5
+ .. versionchanged:: 2.4
The function name was added. In earlier versions, the filename and line number
were returned as a 2-element tuple..
themselves supported; and recursive lists and dictionaries should not be written
(they will cause infinite loops).
-**Caveat:** On machines where C's ``long int`` type has more than 32 bits (such
-as the DEC Alpha), it is possible to create plain Python integers that are
-longer than 32 bits. If such an integer is marshaled and read back in on a
-machine where C's ``long int`` type has only 32 bits, a Python long integer
-object is returned instead. While of a different type, the numeric value is the
-same. (This behavior is new in Python 2.2. In earlier versions, all but the
-least-significant 32 bits of the value were lost, and a warning message was
-printed.)
+.. warning::
+
+ On machines where C's ``long int`` type has more than 32 bits (such as the
+ DEC Alpha), it is possible to create plain Python integers that are longer
+ than 32 bits. If such an integer is marshaled and read back in on a machine
+ where C's ``long int`` type has only 32 bits, a Python long integer object
+ is returned instead. While of a different type, the numeric value is the
+ same. (This behavior is new in Python 2.2. In earlier versions, all but the
+ least-significant 32 bits of the value were lost, and a warning message was
+ printed.)
There are functions that read/write files as well as functions operating on
strings.
.. module:: mimetools
:synopsis: Tools for parsing MIME-style message bodies.
+ :deprecated:
.. deprecated:: 2.3
.. module:: multifile
:synopsis: Support for reading files which contain distinct parts, such as some MIME data.
+ :deprecated:
.. sectionauthor:: Eric S. Raymond <esr@snark.thyrsus.com>
.. module:: rfc822
:synopsis: Parse 2822 style mail messages.
+ :deprecated:
.. deprecated:: 2.3
collections of files. In particular, functions are provided which support file
copying and removal.
-**Caveat:** On MacOS, the resource fork and other metadata are not used. For
-file copies, this means that resources will be lost and file type and creator
-codes will not be correct.
+.. warning::
+
+ On MacOS, the resource fork and other metadata are not used. For file copies,
+ this means that resources will be lost and file type and creator codes will
+ not be correct.
.. function:: copyfile(src, dst)
.. module:: stringprep
:synopsis: String preparation, as per RFC 3453
+ :deprecated:
.. moduleauthor:: Martin v. Löwis <martin@v.loewis.de>
.. sectionauthor:: Martin v. Löwis <martin@v.loewis.de>
based on the definition of canonical equivalence and compatibility equivalence.
In Unicode, several characters can be expressed in various way. For example, the
character U+00C7 (LATIN CAPITAL LETTER C WITH CEDILLA) can also be expressed as
- the sequence U+0043 (LATIN CAPITAL LETTER C) U+0327 (COMBINING CEDILLA).
+ the sequence U+0327 (COMBINING CEDILLA) U+0043 (LATIN CAPITAL LETTER C).
For each character, there are two normal forms: normal form C and normal form D.
Normal form D (NFD) is also known as canonical decomposition, and translates
(NFKC) first applies the compatibility decomposition, followed by the canonical
composition.
+ Even if two unicode strings are normalized and look the same to
+ a human reader, if one has combining characters and the other
+ doesn't, they may not compare equal.
+
.. versionadded:: 2.3
In addition, the module exposes the following constant:
.. note::
If the ZipFile was created by passing in a file-like object as the first
- argument to the constructor, then the object returned by :meth:`open` shares the
+ argument to the constructor, then the object returned by :meth:`.open` shares the
ZipFile's file pointer. Under these circumstances, the object returned by
- :meth:`open` should not be used after any additional operations are performed
+ :meth:`.open` should not be used after any additional operations are performed
on the ZipFile object. If the ZipFile was created by passing in a string (the
- filename) as the first argument to the constructor, then :meth:`open` will
+ filename) as the first argument to the constructor, then :meth:`.open` will
create a new file object that will be held by the ZipExtFile, allowing it to
operate independently of the ZipFile.
* Strings are compared lexicographically using the numeric equivalents (the
result of the built-in function :func:`ord`) of their characters. Unicode and
- 8-bit strings are fully interoperable in this behavior.
+ 8-bit strings are fully interoperable in this behavior. [#]_
* Tuples and lists are compared lexicographically using comparison of
corresponding elements. This means that to compare equal, each element must
cases, Python returns the latter result, in order to preserve that
``divmod(x,y)[0] * y + x % y`` be very close to ``x``.
+.. [#] While comparisons between unicode strings make sense at the byte
+ level, they may be counter-intuitive to users. For example, the
+ strings ``u"\u00C7"`` and ``u"\u0327\u0043"`` compare differently,
+ even though they both represent the same unicode character (LATIN
+ CAPTITAL LETTER C WITH CEDILLA).
+
.. [#] The implementation computes this efficiently, without constructing lists or
sorting.
import sys
if __name__ == '__main__':
+
+ if sys.version_info[:3] < (2, 5, 0):
+ print >>sys.stderr, """\
+Error: Sphinx needs to be executed with Python 2.5 or newer.
+(If you run this from the Makefile, you can set the PYTHON variable
+to the path of an alternative interpreter executable.)
+"""
+ sys.exit(1)
+
from sphinx import main
sys.exit(main(sys.argv))
projects / python / commitdiff