[Python-Dev] [Python-3000] Documentation switch imminent

[Neal Norwitz]

On 8/15/07, Georg Brandl <g.brandl at gmx.net> wrote:
> Georg Brandl schrieb:
> >
> > Neal will change his build scripts, so that the 2.6 and 3.0 devel
> > documentation pages at docs.python.org will be built from these new
> > trees soon.
>
> Okay, I made the switch.  I tagged the state of both Python branches
> before the switch as tags/py{26,3k}-before-rstdocs/.

http://docs.python.org/dev/
http://docs.python.org/dev/3.0/

The upgrade went smoothly.  Below are all the issues I noticed.  I had
to install a version of python 2.5 since that is a minimum
requirement.  I had to change from a plain 'make' in the Doc directory
to 'make html'.  The output is in build/html rather than html/ now.

2.6 output:
trying to load pickled env... failed: [Errno 2] No such file or
directory: 'build/doctrees/environment.pickle'

writing output...
... library/contextlib.rst<string>:3: Warning: 'with' will become a
reserved keyword in Python 2.6
tutorial/errors.rst<string>:1: Warning: 'with' will become a reserved
keyword in Python

3.0 output:
Traceback (most recent call last):
  File "tools/sphinx-build.py", line 13, in <module>
    from sphinx import main
  File "/home/neal/python/py3k/Doc/tools/sphinx/__init__.py", line 16,
in <module>
    from .builder import builders
  File "/home/neal/python/py3k/Doc/tools/sphinx/builder.py", line 35,
in <module>
    from .environment import BuildEnvironment
  File "/home/neal/python/py3k/Doc/tools/sphinx/environment.py", line
34, in <module>
    from docutils.parsers.rst.states import Body
  File "/home/neal/python/py3k/Doc/tools/docutils/parsers/rst/__init__.py",
line 77, in <module>
    from docutils.parsers.rst import states
  File "/home/neal/python/py3k/Doc/tools/docutils/parsers/rst/states.py",
line 110, in <module>
    import roman
ImportError: No module named roman

After this error, I just linked my tools directory to the one in 2.6
(trunk) and that worked. I'm not sure if this will create problems in
the future.

trying to load pickled env... failed: [Errno 2] No such file or
directory: 'build/doctrees/environment.pickle'

writing output...
... library/contextlib.rst<string>:3: Warning: 'with' will become a
reserved keyword in Python 2.6
library/shutil.rst<string>:17: Warning: 'as' will become a reserved
keyword in Python 2.6
library/subprocess.rst<string>:7: Warning: 'as' will become a reserved
keyword in Python 2.6
tutorial/errors.rst<string>:1: Warning: 'with' will become a reserved
keyword in Python 2.6

I realize none of these are a big deal.  However, it would be nice if
it was cleaned up so that people unfamiliar with building the docs
aren't surprised.

n