Skip to content

Commit 82be6d5

Browse files
author
georg.brandl
committed
Some cleanup in the docs.
git-svn-id: http://svn.python.org/projects/python/trunk@59606 6015fed2-1504-0410-9fe1-9d1591cc4771
1 parent 3ea801f commit 82be6d5

126 files changed

Lines changed: 805 additions & 1182 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎Doc/Makefile‎

Lines changed: 8 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -16,10 +16,11 @@ ALLSPHINXOPTS = -b $(BUILDER) -d build/doctrees -D latex_paper_size=$(PAPER) \
1616

1717
help:
1818
@echo "Please use \`make <target>' where <target> is one of"
19-
@echo " html to make standalone HTML files"
20-
@echo " web to make file usable by Sphinx.web"
19+
@echo " html to make standalone HTML files"
20+
@echo " web to make file usable by Sphinx.web"
2121
@echo " htmlhelp to make HTML files and a HTML help project"
22-
@echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
22+
@echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
23+
@echo " changes to make an overview over all changed/added/deprecated items"
2324

2425
checkout:
2526
@if [ ! -d tools/sphinx ]; then \
@@ -66,6 +67,10 @@ latex: build
6667
@echo "Run \`make all-pdf' or \`make all-ps' in that directory to" \
6768
"run these through (pdf)latex."
6869

70+
changes: BUILDER = changes
71+
changes: build
72+
@echo "The overview file is in build/changes."
73+
6974
clean:
7075
-rm -rf build/*
7176
-rm -rf tools/sphinx

‎Doc/README.txt‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -51,6 +51,10 @@ Available make targets are:
5151
* "latex", which builds LaTeX source files that can be run with "pdflatex"
5252
to produce PDF documents.
5353

54+
* "changes", which builds an overview over all versionadded/versionchanged/
55+
deprecated items in the current version. This is meant as a help for the
56+
writer of the "What's New" document.
57+
5458
A "make update" updates the Subversion checkouts in `tools/`.
5559

5660

‎Doc/c-api/exceptions.rst‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -37,8 +37,8 @@ Python variables ``sys.exc_type``, ``sys.exc_value`` and ``sys.exc_traceback``.
3737
API functions exist to interact with the error indicator in various ways. There
3838
is a separate error indicator for each thread.
3939

40-
.. % XXX Order of these should be more thoughtful.
41-
.. % Either alphabetical or some kind of structure.
40+
.. XXX Order of these should be more thoughtful.
41+
Either alphabetical or some kind of structure.
4242
4343
4444
.. cfunction:: void PyErr_Print()

‎Doc/c-api/init.rst‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -266,7 +266,7 @@ Initialization, Finalization, and Threads
266266
as the list ``sys.path``, which may be modified to change the future search path
267267
for loaded modules.
268268

269-
.. % XXX should give the exact rules
269+
.. XXX should give the exact rules
270270
271271
272272
.. cfunction:: const char* Py_GetVersion()
@@ -361,8 +361,8 @@ Initialization, Finalization, and Threads
361361
to initialize ``sys.argv``, a fatal condition is signalled using
362362
:cfunc:`Py_FatalError`.
363363

364-
.. % XXX impl. doesn't seem consistent in allowing 0/NULL for the params;
365-
.. % check w/ Guido.
364+
.. XXX impl. doesn't seem consistent in allowing 0/NULL for the params;
365+
check w/ Guido.
366366
367367
368368
.. _threads:

‎Doc/c-api/intro.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -489,7 +489,7 @@ Here is the corresponding C code, in all its glory::
489489
single: PyErr_Clear()
490490
single: Py_XDECREF()
491491

492-
This example represents an endorsed use of the :keyword:`goto` statement in C!
492+
This example represents an endorsed use of the ``goto`` statement in C!
493493
It illustrates the use of :cfunc:`PyErr_ExceptionMatches` and
494494
:cfunc:`PyErr_Clear` to handle specific exceptions, and the use of
495495
:cfunc:`Py_XDECREF` to dispose of owned references that may be *NULL* (note the

‎Doc/c-api/newtypes.rst‎

Lines changed: 6 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -476,7 +476,7 @@ type objects) *must* have the :attr:`ob_size` field.
476476
declare the instance struct) and this in turn includes the :attr:`_ob_prev` and
477477
:attr:`_ob_next` fields if they are present. This means that the only correct
478478
way to get an initializer for the :attr:`tp_basicsize` is to use the
479-
:keyword:`sizeof` operator on the struct used to declare the instance layout.
479+
``sizeof`` operator on the struct used to declare the instance layout.
480480
The basic size does not include the GC header size (this is new in Python 2.2;
481481
in 2.1 and 2.0, the GC header size was included in :attr:`tp_basicsize`).
482482

@@ -1175,7 +1175,7 @@ The next fields, up to and including :attr:`tp_weaklist`, only exist if the
11751175

11761176
PyObject * tp_descr_get(PyObject *self, PyObject *obj, PyObject *type);
11771177

1178-
XXX blah, blah.
1178+
XXX explain.
11791179

11801180
This field is inherited by subtypes.
11811181

@@ -1190,7 +1190,7 @@ The next fields, up to and including :attr:`tp_weaklist`, only exist if the
11901190

11911191
This field is inherited by subtypes.
11921192

1193-
XXX blah, blah.
1193+
XXX explain.
11941194

11951195

11961196
.. cmember:: long PyTypeObject.tp_dictoffset
@@ -1734,10 +1734,9 @@ member in the :ctype:`PyTypeObject` structure should be *NULL*. Otherwise, the
17341734
and :exc:`SystemError` should be raised when *segment* specifies a segment that
17351735
doesn't exist.
17361736

1737-
.. % Why doesn't it raise ValueError for this one?
1738-
.. % GJS: because you shouldn't be calling it with an invalid
1739-
.. % segment. That indicates a blatant programming error in the C
1740-
.. % code.
1737+
.. Why doesn't it raise ValueError for this one?
1738+
GJS: because you shouldn't be calling it with an invalid
1739+
segment. That indicates a blatant programming error in the C code.
17411740
17421741
17431742
.. ctype:: Py_ssize_t (*segcountproc) (PyObject *self, Py_ssize_t *lenp)

‎Doc/distutils/setupscript.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -137,7 +137,7 @@ the Distutils to go out and find the right files; you have to specify the
137137
extension name, source file(s), and any compile/link requirements (include
138138
directories, libraries to link with, etc.).
139139

140-
.. % XXX read over this section
140+
.. XXX read over this section
141141
142142
All of this is done through another keyword argument to :func:`setup`, the
143143
:option:`ext_modules` option. :option:`ext_modules` is just a list of

‎Doc/documenting/fromlatex.rst‎

Lines changed: 20 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -154,25 +154,35 @@ These changes to information units should be noted:
154154

155155
Description.
156156

157-
* **New information unit**
157+
* **New information units**
158158

159-
There is a new generic information unit called "describe" which can be used
160-
to document things that are not covered by the other units::
159+
There are new generic information units: One is called "describe" and can be
160+
used to document things that are not covered by the other units::
161161

162162
.. describe:: a == b
163163

164164
The equals operator.
165165

166+
The others are::
167+
168+
.. cmdoption:: -O
169+
170+
Describes a command-line option.
171+
172+
.. envvar:: PYTHONINSPECT
173+
174+
Describes an environment variable.
175+
166176

167177
Structure
168178
---------
169179

170-
The LaTeX docs were split in several toplevel manuals. Now, all files
171-
are part of the same documentation tree, as indicated by the *toctree*
172-
directives in the sources. Every *toctree* directive embeds other files
173-
as subdocuments of the current file (this structure is not necessarily
174-
mirrored in the filesystem layout). The toplevel file is
175-
:file:`contents.rst`.
180+
The LaTeX docs were split in several toplevel manuals. Now, all files are part
181+
of the same documentation tree, as indicated by the *toctree* directives in the
182+
sources (though individual output formats may choose to split them up into parts
183+
again). Every *toctree* directive embeds other files as subdocuments of the
184+
current file (this structure is not necessarily mirrored in the filesystem
185+
layout). The toplevel file is :file:`contents.rst`.
176186

177187
However, most of the old directory structure has been kept, with the
178188
directories renamed as follows:
@@ -184,7 +194,7 @@ directories renamed as follows:
184194
* :file:`inst` -> :file:`installing`
185195
* :file:`lib` -> :file:`library`
186196
* :file:`mac` -> merged into :file:`library`, with :file:`mac/using.tex`
187-
moved to :file:`howto/pythonmac.rst`
197+
moved to :file:`using/mac.rst`
188198
* :file:`ref` -> :file:`reference`
189199
* :file:`tut` -> :file:`tutorial`, with the single TeX file split up
190200

‎Doc/documenting/markup.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -455,7 +455,7 @@ in a different style:
455455

456456
.. describe:: keyword
457457

458-
The name of a keyword in a programming language.
458+
The name of a keyword in Python.
459459

460460
.. describe:: mailheader
461461

‎Doc/documenting/sphinx.rst‎

Lines changed: 21 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -47,14 +47,30 @@ unused_files : list of strings
4747
could be docs for temporarily disabled modules or documentation that's not
4848
yet ready for public consumption.
4949

50-
last_updated_format : string
50+
add_function_parentheses : bool
51+
If true, ``()`` will be appended to the content of ``:func:``, ``:meth:`` and
52+
``:cfunc:`` cross-references.
53+
54+
add_module_names : bool
55+
If true, the current module name will be prepended to all description unit
56+
titles (such as ``.. function::``).
57+
58+
Builder-specific variables
59+
^^^^^^^^^^^^^^^^^^^^^^^^^^
60+
61+
html_download_base_url : string
62+
The base URL for download links on the download page.
63+
64+
html_last_updated_fmt : string
5165
If this is not an empty string, it will be given to ``time.strftime()`` and
5266
written to each generated output file after "last updated on:".
5367

54-
use_smartypants : bool
68+
html_use_smartypants : bool
5569
If true, use SmartyPants to convert quotes and dashes to the typographically
5670
correct entities.
5771

58-
add_function_parentheses : bool
59-
If true, ``()`` will be appended to the content of ``:func:``, ``:meth:`` and
60-
``:cfunc:`` cross-references.
72+
latex_paper_size : "letter" or "a4"
73+
The paper size option for the LaTeX document class.
74+
75+
latex_font_size : "10pt", "11pt" or "12pt"
76+
The font size option for the LaTeX document class.

0 commit comments

Comments
 (0)