mirror of https://github.com/python/cpython
Merged revisions 67154,67157-67159,67162-67163,67166,67175-67176,67189,67224-67225,67243 via svnmerge from
svn+ssh://pythondev@svn.python.org/python/trunk ........ r67154 | hirokazu.yamamoto | 2008-11-08 04:46:17 +0100 (Sat, 08 Nov 2008) | 1 line Issue #4071: ntpath.abspath returned an empty string for long unicode path. ........ r67157 | georg.brandl | 2008-11-08 12:47:44 +0100 (Sat, 08 Nov 2008) | 2 lines Don't use "HOWTO" as the title for all howto .tex files. ........ r67158 | georg.brandl | 2008-11-08 12:48:20 +0100 (Sat, 08 Nov 2008) | 2 lines Update "Documenting" a bit. Concentrate on Python-specifics. ........ r67159 | georg.brandl | 2008-11-08 13:52:25 +0100 (Sat, 08 Nov 2008) | 2 lines Fix warning. ........ r67162 | benjamin.peterson | 2008-11-08 17:55:33 +0100 (Sat, 08 Nov 2008) | 1 line a few compile() and ast doc improvements ........ r67163 | benjamin.peterson | 2008-11-08 18:04:18 +0100 (Sat, 08 Nov 2008) | 1 line move context clue to versionchanged tag ........ r67166 | benjamin.peterson | 2008-11-08 18:07:06 +0100 (Sat, 08 Nov 2008) | 1 line clarify what was added ........ r67175 | benjamin.peterson | 2008-11-09 02:44:32 +0100 (Sun, 09 Nov 2008) | 1 line update link ........ r67176 | benjamin.peterson | 2008-11-09 02:52:32 +0100 (Sun, 09 Nov 2008) | 1 line fix comment ........ r67189 | benjamin.peterson | 2008-11-11 22:56:06 +0100 (Tue, 11 Nov 2008) | 1 line use correct name ........ r67224 | georg.brandl | 2008-11-15 09:10:04 +0100 (Sat, 15 Nov 2008) | 2 lines #4324: fix getlocale() argument. ........ r67225 | brett.cannon | 2008-11-15 23:33:25 +0100 (Sat, 15 Nov 2008) | 1 line Clarify the docs for the 'strict' argument to httplib.HTTPConnection. ........ r67243 | benjamin.peterson | 2008-11-17 22:39:05 +0100 (Mon, 17 Nov 2008) | 1 line a few fixes on the download page ........
This commit is contained in:
Georg Brandl
parent
6b257f4b3d
commit
bb608a84aa
|
|
@ -128,7 +128,7 @@ latex_documents = [
|
|||
]
|
||||
# Collect all HOWTOs individually
|
||||
latex_documents.extend(('howto/' + fn[:-4], 'howto-' + fn[:-4] + '.tex',
|
||||
'HOWTO', _stdauthor, 'howto')
|
||||
'', _stdauthor, 'howto')
|
||||
for fn in os.listdir('howto')
|
||||
if fn.endswith('.rst') and fn != 'index.rst')
|
||||
|
||||
|
|
|
|||
|
|
@ -8,7 +8,7 @@
|
|||
The Python language has a substantial body of documentation, much of it
|
||||
contributed by various authors. The markup used for the Python documentation is
|
||||
`reStructuredText`_, developed by the `docutils`_ project, amended by custom
|
||||
directives and using a toolset named *Sphinx* to postprocess the HTML output.
|
||||
directives and using a toolset named `Sphinx`_ to postprocess the HTML output.
|
||||
|
||||
This document describes the style guide for our documentation, the custom
|
||||
reStructuredText markup introduced to support Python documentation and how it
|
||||
|
|
@ -16,6 +16,7 @@ should be used, as well as the Sphinx build system.
|
|||
|
||||
.. _reStructuredText: http://docutils.sf.net/rst.html
|
||||
.. _docutils: http://docutils.sf.net/
|
||||
.. _Sphinx: http://sphinx.pocoo.org/
|
||||
|
||||
If you're interested in contributing to Python's documentation, there's no need
|
||||
to write reStructuredText if you're not so inclined; plain text contributions
|
||||
|
|
@ -28,7 +29,3 @@ are more than welcome as well.
|
|||
rest.rst
|
||||
markup.rst
|
||||
fromlatex.rst
|
||||
sphinx.rst
|
||||
|
||||
.. XXX add credits, thanks etc.
|
||||
|
||||
|
|
|
|||
|
|
@ -8,24 +8,11 @@ markup. This section contains the reference material for these facilities.
|
|||
Documentation for "standard" reST constructs is not included here, though
|
||||
they are used in the Python documentation.
|
||||
|
||||
File-wide metadata
|
||||
------------------
|
||||
.. note::
|
||||
|
||||
reST has the concept of "field lists"; these are a sequence of fields marked up
|
||||
like this::
|
||||
|
||||
:Field name: Field content
|
||||
|
||||
A field list at the very top of a file is parsed as the "docinfo", which in
|
||||
normal documents can be used to record the author, date of publication and
|
||||
other metadata. In Sphinx, the docinfo is used as metadata, too, but not
|
||||
displayed in the output.
|
||||
|
||||
At the moment, only one metadata field is recognized:
|
||||
|
||||
``nocomments``
|
||||
If set, the web application won't display a comment form for a page generated
|
||||
from this source file.
|
||||
This is just an overview of Sphinx' extended markup capabilities; full
|
||||
coverage can be found in `its own documentation
|
||||
<http://sphinx.pocoo.org/contents.html>`_.
|
||||
|
||||
|
||||
Meta-information markup
|
||||
|
|
@ -88,7 +75,6 @@ As you can see, the module-specific markup consists of two directives, the
|
|||
authors of the module code, just like ``sectionauthor`` names the author(s)
|
||||
of a piece of documentation. It too does not result in any output currently.
|
||||
|
||||
|
||||
.. note::
|
||||
|
||||
It is important to make the section title of a module-describing file
|
||||
|
|
@ -272,7 +258,7 @@ Syntax highlighting is handled in a smart way:
|
|||
This language is used until the next ``highlightlang`` directive is
|
||||
encountered.
|
||||
|
||||
* The valid values for the highlighting language are:
|
||||
* The values normally used for the highlighting language are:
|
||||
|
||||
* ``python`` (the default)
|
||||
* ``c``
|
||||
|
|
@ -799,7 +785,7 @@ Substitutions
|
|||
-------------
|
||||
|
||||
The documentation system provides three substitutions that are defined by default.
|
||||
They are set in the build configuration file, see :ref:`doc-build-config`.
|
||||
They are set in the build configuration file :file:`conf.py`.
|
||||
|
||||
.. describe:: |release|
|
||||
|
||||
|
|
|
|||
|
|
@ -67,12 +67,6 @@ autonumbered using a ``#`` sign::
|
|||
#. This is a numbered list.
|
||||
#. It has two items too.
|
||||
|
||||
Note that Sphinx disables the use of enumerated lists introduced by alphabetic
|
||||
or roman numerals, such as ::
|
||||
|
||||
A. First item
|
||||
B. Second item
|
||||
|
||||
|
||||
Nested lists are possible, but be aware that they must be separated from the
|
||||
parent list items by blank lines::
|
||||
|
|
@ -247,5 +241,3 @@ There are some problems one commonly runs into while authoring reST documents:
|
|||
* **Separation of inline markup:** As said above, inline markup spans must be
|
||||
separated from the surrounding text by non-word characters, you have to use
|
||||
an escaped space to get around that.
|
||||
|
||||
.. XXX more?
|
||||
|
|
|
|||
|
|
@ -1,76 +0,0 @@
|
|||
.. highlightlang:: rest
|
||||
|
||||
The Sphinx build system
|
||||
=======================
|
||||
|
||||
.. XXX: intro...
|
||||
|
||||
.. _doc-build-config:
|
||||
|
||||
The build configuration file
|
||||
----------------------------
|
||||
|
||||
The documentation root, that is the ``Doc`` subdirectory of the source
|
||||
distribution, contains a file named ``conf.py``. This file is called the "build
|
||||
configuration file", and it contains several variables that are read and used
|
||||
during a build run.
|
||||
|
||||
These variables are:
|
||||
|
||||
version : string
|
||||
A string that is used as a replacement for the ``|version|`` reST
|
||||
substitution. It should be the Python version the documentation refers to.
|
||||
This consists only of the major and minor version parts, e.g. ``2.5``, even
|
||||
for version 2.5.1.
|
||||
|
||||
release : string
|
||||
A string that is used as a replacement for the ``|release|`` reST
|
||||
substitution. It should be the full version string including
|
||||
alpha/beta/release candidate tags, e.g. ``2.5.2b3``.
|
||||
|
||||
Both ``release`` and ``version`` can be ``'auto'``, which means that they are
|
||||
determined at runtime from the ``Include/patchlevel.h`` file, if a complete
|
||||
Python source distribution can be found, or else from the interpreter running
|
||||
Sphinx.
|
||||
|
||||
today_fmt : string
|
||||
A ``strftime`` format that is used to format a replacement for the
|
||||
``|today|`` reST substitution.
|
||||
|
||||
today : string
|
||||
A string that can contain a date that should be written to the documentation
|
||||
output literally. If this is nonzero, it is used instead of
|
||||
``strftime(today_fmt)``.
|
||||
|
||||
unused_files : list of strings
|
||||
A list of reST filenames that are to be disregarded during building. This
|
||||
could be docs for temporarily disabled modules or documentation that's not
|
||||
yet ready for public consumption.
|
||||
|
||||
add_function_parentheses : bool
|
||||
If true, ``()`` will be appended to the content of ``:func:``, ``:meth:`` and
|
||||
``:cfunc:`` cross-references.
|
||||
|
||||
add_module_names : bool
|
||||
If true, the current module name will be prepended to all description unit
|
||||
titles (such as ``.. function::``).
|
||||
|
||||
Builder-specific variables
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
html_download_base_url : string
|
||||
The base URL for download links on the download page.
|
||||
|
||||
html_last_updated_fmt : string
|
||||
If this is not an empty string, it will be given to ``time.strftime()`` and
|
||||
written to each generated output file after "last updated on:".
|
||||
|
||||
html_use_smartypants : bool
|
||||
If true, use SmartyPants to convert quotes and dashes to the typographically
|
||||
correct entities.
|
||||
|
||||
latex_paper_size : "letter" or "a4"
|
||||
The paper size option for the LaTeX document class.
|
||||
|
||||
latex_font_size : "10pt", "11pt" or "12pt"
|
||||
The font size option for the LaTeX document class.
|
||||
|
|
@ -66,5 +66,5 @@ Unix
|
|||
1970s.
|
||||
|
||||
|
||||
.. _Apple Publications Style Guide: http://developer.apple.com/documentation/UserExperience/Conceptual/APStyleGuide/AppleStyleGuide2006.pdf
|
||||
.. _Apple Publications Style Guide: http://developer.apple.com/documentation/UserExperience/Conceptual/APStyleGuide/APSG_2008.pdf
|
||||
|
||||
|
|
|
|||
|
|
@ -21,13 +21,12 @@ abstract syntax grammar. The abstract syntax itself might change with each
|
|||
Python release; this module helps to find out programmatically what the current
|
||||
grammar looks like.
|
||||
|
||||
An abstract syntax tree can be generated by passing :data:`_ast.PyCF_ONLY_AST`
|
||||
as a flag to the :func:`compile` builtin function, or using the :func:`parse`
|
||||
An abstract syntax tree can be generated by passing :data:`ast.PyCF_ONLY_AST` as
|
||||
a flag to the :func:`compile` builtin function, or using the :func:`parse`
|
||||
helper provided in this module. The result will be a tree of objects whose
|
||||
classes all inherit from :class:`ast.AST`.
|
||||
classes all inherit from :class:`ast.AST`. An abstract syntax tree can be
|
||||
compiled into a Python code object using the built-in :func:`compile` function.
|
||||
|
||||
A modified abstract syntax tree can be compiled into a Python code object using
|
||||
the built-in :func:`compile` function.
|
||||
|
||||
Node classes
|
||||
------------
|
||||
|
|
@ -126,7 +125,7 @@ and classes for traversing abstract syntax trees:
|
|||
.. function:: parse(expr, filename='<unknown>', mode='exec')
|
||||
|
||||
Parse an expression into an AST node. Equivalent to ``compile(expr,
|
||||
filename, mode, PyCF_ONLY_AST)``.
|
||||
filename, mode, ast.PyCF_ONLY_AST)``.
|
||||
|
||||
|
||||
.. function:: literal_eval(node_or_string)
|
||||
|
|
|
|||
|
|
@ -199,15 +199,8 @@ available. They are listed here in alphabetical order.
|
|||
|
||||
Compile the *source* into a code or AST object. Code objects can be executed
|
||||
by an :keyword:`exec` statement or evaluated by a call to :func:`eval`.
|
||||
*source* can either be a string or an AST object. Refer to the :mod:`_ast`
|
||||
module documentation for information on how to compile into and from AST
|
||||
objects.
|
||||
|
||||
When compiling a string with multi-line statements, two caveats apply: line
|
||||
endings must be represented by a single newline character (``'\n'``), and the
|
||||
input must be terminated by at least one newline character. If line endings
|
||||
are represented by ``'\r\n'``, use the string :meth:`replace` method to
|
||||
change them into ``'\n'``.
|
||||
*source* can either be a string or an AST object. Refer to the :mod:`ast`
|
||||
module documentation for information on how to work with AST objects.
|
||||
|
||||
The *filename* argument should give the file from which the code was read;
|
||||
pass some recognizable value if it wasn't read from a file (``'<string>'`` is
|
||||
|
|
@ -219,15 +212,15 @@ available. They are listed here in alphabetical order.
|
|||
interactive statement (in the latter case, expression statements that
|
||||
evaluate to something else than ``None`` will be printed).
|
||||
|
||||
The optional arguments *flags* and *dont_inherit* (which are new in Python 2.2)
|
||||
control which future statements (see :pep:`236`) affect the compilation of
|
||||
*source*. If neither is present (or both are zero) the code is compiled with
|
||||
those future statements that are in effect in the code that is calling compile.
|
||||
If the *flags* argument is given and *dont_inherit* is not (or is zero) then the
|
||||
The optional arguments *flags* and *dont_inherit* control which future
|
||||
statements (see :pep:`236`) affect the compilation of *source*. If neither
|
||||
is present (or both are zero) the code is compiled with those future
|
||||
statements that are in effect in the code that is calling compile. If the
|
||||
*flags* argument is given and *dont_inherit* is not (or is zero) then the
|
||||
future statements specified by the *flags* argument are used in addition to
|
||||
those that would be used anyway. If *dont_inherit* is a non-zero integer then
|
||||
the *flags* argument is it -- the future statements in effect around the call to
|
||||
compile are ignored.
|
||||
the *flags* argument is it -- the future statements in effect around the call
|
||||
to compile are ignored.
|
||||
|
||||
Future statements are specified by bits which can be bitwise ORed together to
|
||||
specify multiple statements. The bitfield required to specify a given feature
|
||||
|
|
@ -237,7 +230,18 @@ available. They are listed here in alphabetical order.
|
|||
This function raises :exc:`SyntaxError` if the compiled source is invalid,
|
||||
and :exc:`TypeError` if the source contains null bytes.
|
||||
|
||||
.. versionadded:: 2.6
|
||||
.. note::
|
||||
|
||||
When compiling a string with multi-line statements, line endings must be
|
||||
represented by a single newline character (``'\n'``), and the input must
|
||||
be terminated by at least one newline character. If line endings are
|
||||
represented by ``'\r\n'``, use :meth:`str.replace` to change them into
|
||||
``'\n'``.
|
||||
|
||||
.. versionchanged:: 2.3
|
||||
The *flags* and *dont_inherit* arguments were added.
|
||||
|
||||
.. versionchanged:: 2.6
|
||||
Support for compiling AST objects.
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -40,7 +40,8 @@ The module provides the following classes:
|
|||
server. It should be instantiated passing it a host and optional port
|
||||
number. If no port number is passed, the port is extracted from the host
|
||||
string if it has the form ``host:port``, else the default HTTP port (80) is
|
||||
used. When True, the optional parameter *strict* causes ``BadStatusLine`` to
|
||||
used. When True, the optional parameter *strict* (which defaults to a false
|
||||
value) causes ``BadStatusLine`` to
|
||||
be raised if the status line can't be parsed as a valid HTTP/1.0 or 1.1
|
||||
status line. If the optional *timeout* parameter is given, blocking
|
||||
operations (like connection attempts) will timeout after that many seconds
|
||||
|
|
|
|||
|
|
@ -492,7 +492,7 @@ descriptions are taken from the corresponding description in the GNU C library.
|
|||
Example::
|
||||
|
||||
>>> import locale
|
||||
>>> loc = locale.getlocale(locale.LC_ALL) # get current locale
|
||||
>>> loc = locale.getlocale() # get current locale
|
||||
>>> locale.setlocale(locale.LC_ALL, 'de_DE') # use German locale; name might vary with platform
|
||||
>>> locale.strcoll('f\xe4n', 'foo') # compare a string containing an umlaut
|
||||
>>> locale.setlocale(locale.LC_ALL, '') # use user's preferred locale
|
||||
|
|
|
|||
|
|
@ -1870,7 +1870,7 @@ handler type) for messages from different processes to get mixed up.
|
|||
Below is an example session with logging turned on::
|
||||
|
||||
>>> import multiprocessing, logging
|
||||
>>> logger = multiprocessing.getLogger()
|
||||
>>> logger = multiprocessing.get_logger()
|
||||
>>> logger.setLevel(logging.INFO)
|
||||
>>> logger.warning('doomed')
|
||||
[WARNING/MainProcess] doomed
|
||||
|
|
|
|||
|
|
@ -14,7 +14,7 @@
|
|||
|
||||
<p>To download an archive containing all the documents for this version of
|
||||
Python in one of various formats, follow one of links in this table. The numbers
|
||||
in the table are the size of the download files in Kilobytes.</p>
|
||||
in the table are the size of the download files in megabytes.</p>
|
||||
|
||||
<table class="docutils">
|
||||
<tr><th>Format</th><th>Packed as .zip</th><th>Packed as .tar.bz2</th></tr>
|
||||
|
|
@ -54,7 +54,7 @@ platform. These are created on Unix using the InfoZIP zip program.</p>
|
|||
<h2>Problems</h2>
|
||||
|
||||
<p>If you have comments or suggestions for the Python documentation, please send
|
||||
email to <a href="docs@python.org">docs@python.org</a>.</p>
|
||||
email to <a href="mailto:docs@python.org">docs@python.org</a>.</p>
|
||||
{% endif %}
|
||||
|
||||
{% endblock %}
|
||||
|
|
|
|||
|
|
@ -532,9 +532,8 @@ except ImportError:
|
|||
# the Formatter class
|
||||
# see PEP 3101 for details and purpose of this class
|
||||
|
||||
# The hard parts are reused from the C implementation. They're
|
||||
# exposed here via the sys module. sys was chosen because it's always
|
||||
# available and doesn't have to be dynamically loaded.
|
||||
# The hard parts are reused from the C implementation. They're exposed as "_"
|
||||
# prefixed methods of str and unicode.
|
||||
|
||||
# The overall parser is implemented in str._formatter_parser.
|
||||
# The field name parser is implemented in str._formatter_field_name_split
|
||||
|
|
|
|||
|
|
@ -2393,13 +2393,27 @@ posix__getfullpathname(PyObject *self, PyObject *args)
|
|||
if (unicode_file_names()) {
|
||||
PyUnicodeObject *po;
|
||||
if (PyArg_ParseTuple(args, "U|:_getfullpathname", &po)) {
|
||||
Py_UNICODE woutbuf[MAX_PATH*2];
|
||||
Py_UNICODE *wpath = PyUnicode_AS_UNICODE(po);
|
||||
Py_UNICODE woutbuf[MAX_PATH*2], *woutbufp = woutbuf;
|
||||
Py_UNICODE *wtemp;
|
||||
if (!GetFullPathNameW(PyUnicode_AS_UNICODE(po),
|
||||
sizeof(woutbuf)/sizeof(woutbuf[0]),
|
||||
woutbuf, &wtemp))
|
||||
return win32_error("GetFullPathName", "");
|
||||
return PyUnicode_FromUnicode(woutbuf, wcslen(woutbuf));
|
||||
DWORD result;
|
||||
PyObject *v;
|
||||
result = GetFullPathNameW(wpath,
|
||||
sizeof(woutbuf)/sizeof(woutbuf[0]),
|
||||
woutbuf, &wtemp);
|
||||
if (result > sizeof(woutbuf)/sizeof(woutbuf[0])) {
|
||||
woutbufp = malloc(result * sizeof(Py_UNICODE));
|
||||
if (!woutbufp)
|
||||
return PyErr_NoMemory();
|
||||
result = GetFullPathNameW(wpath, result, woutbufp, &wtemp);
|
||||
}
|
||||
if (result)
|
||||
v = PyUnicode_FromUnicode(woutbufp, wcslen(woutbufp));
|
||||
else
|
||||
v = win32_error_unicode("GetFullPathNameW", wpath);
|
||||
if (woutbufp != woutbuf)
|
||||
free(woutbufp);
|
||||
return v;
|
||||
}
|
||||
/* Drop the argument parsing error as narrow strings
|
||||
are also valid. */
|
||||
|
|
|
|||
Loading…
Reference in New Issue