I initially had a bit of the same confusion as Daniel, and hence agree on clarifying.

I have more comments on 7.6. Building the documentation.

1. "You need to have Python 2.4 or higher installed."

Until 3.x docs can be built with 3.x, (and I just verified that this is 'not yet') change '2.4 or higher' to '2.4 to 2.7'.

1A. "To build the documentation, follow the instructions from one of the sections below."

Perhaps we should add "These instructions assume that <repository>/Doc/ is the current directory." Then we would not have to repeat in multiple places.

2. "7.6.1. Using make On Unix, ..."

It turns out that there is an almost easy-to-use make.bat that *almost* works the same. So it should be documented, but, unfortunately, we cannot just say "On Unix or Windows ...".

One problem is this line:
if "%PYTHON%" EQU "" set PYTHON=..\pcbuild\python
Since we elsewhere say to build python_d.exe rather than python.exe for development, that line needs '_d' added. But even with that correction, making docs will still fail for 3.x. So we need a new paragraph that says something like
'''
On Windows, with svn available, download the needed modules with
...\Doc> make checkout            [in code box]
As with unix, update with "make update". Make the html docs with [in code box]
...\Doc> set PYTHON=<path to 2.x executable>
...\Doc> make html
The list of other possible targets is almost the same, except that “coverage” and “pydoc-topics” are not available, which "suspicious" warns about suspicious constructs that are not errors.
'''
Perhaps "suspicious" is available on *nix, just not documented. Could someone check?

The need to set PYTHON each session is a nuisance. I made another batch file with the correct setting for my system. But that will keep showing up as a file to be added. I will try to write a master dmake.bat file that sits outside of the repository directories. Once working, it might be suitable as a template.

3. "Then, make an output directory, e.g. under `build/`"

This is awkward, both before and after the proposed patch and is overly stingly with words. I suggest:

"While in the Doc directory, make a master output directory `build/` that will contain subdirectories for each target, such as `build/html/`.  Then run ..."

4. "the directory containing `conf.py` "

Why the euphimism for Doc/? Is it ever anything else.