Add Python-specific content to Doc dir. Update configuration file

to work with the newest Sphinx.

Doc/conf.py

@@ -2,22 +2,28 @@
 #
 # Python documentation build configuration file
 #
+# This file is execfile()d with the current directory set to its containing dir.
+#
 # The contents of this file are pickled, so don't put values in the namespace
 # that aren't pickleable (module imports are okay, they're removed automatically).
 
 # General configuration
 # ---------------------
 
+# General substitutions.
+project = 'Python'
+copyright = '1990-2007, Python Software Foundation'
+
 # The default replacements for |version| and |release|.
-# If 'auto', Sphinx looks for the Include/patchlevel.h file in the current Python
+# If '<auto>', Sphinx looks for the Include/patchlevel.h file in the current Python
 # source tree and replaces the values accordingly.
 #
 # The short X.Y version.
 # version = '2.6'
-version = 'auto'
+version = '<auto>'
 # The full version, including alpha/beta/rc tags.
 # release = '2.6a0'
-release = 'auto'
+release = '<auto>'
 
 # There are two options for replacing |today|: either, you set today to some
 # non-false value, then it is used:
@@ -38,6 +44,9 @@ unused_files = [
     'library/xml.etree.rst',
 ]
 
+# Relative filename of the reference count data file.
+refcount_file = 'data/refcounts.dat'
+
 # If true, '()' will be appended to :func: etc. cross-reference text.
 add_function_parentheses = True
 
@@ -49,9 +58,6 @@ add_module_names = True
 # Options for HTML output
 # -----------------------
 
-# The base URL for download links.
-html_download_base_url = 'http://docs.python.org/ftp/python/doc/'
-
 # If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
 # using the given strftime format.
 html_last_updated_fmt = '%b %d, %Y'
@@ -60,12 +66,71 @@ html_last_updated_fmt = '%b %d, %Y'
 # typographically correct entities.
 html_use_smartypants = True
 
+# Content template for the index page, filename relative to this file.
+html_index = 'tools/sphinxext/indexcontent.html'
+
+# Custom sidebar templates, filenames relative to this file.
+html_sidebars = {
+    'index': 'tools/sphinxext/indexsidebar.html',
+}
+
+# Additional templates that should be rendered to pages.
+html_additional_pages = {
+    'download': 'tools/sphinxext/download.html',
+}
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'pydoc'
+
 
 # Options for LaTeX output
 # ------------------------
 
-# The paper size ("letter" or "a4").
-latex_paper_size = "a4"
+# The paper size ('letter' or 'a4').
+latex_paper_size = 'a4'
+
+# The font size ('10pt', '11pt' or '12pt').
+latex_font_size = '10pt'
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title, author, document class [howto/manual]).
+_stdauthor = r'Guido van Rossum\\Fred L. Drake, Jr., editor'
+latex_documents = [
+    ('c-api/index.rst', 'c-api.tex',
+     'The Python/C API', _stdauthor, 'manual'),
+    ('distutils/index.rst', 'distutils.tex',
+     'Distributing Python Modules', _stdauthor, 'manual'),
+    ('documenting/index.rst', 'documenting.tex',
+     'Documenting Python', 'Georg Brandl', 'manual'),
+    ('extending/index.rst', 'extending.tex',
+     'Extending and Embedding Python', _stdauthor, 'manual'),
+    ('install/index.rst', 'install.tex',
+     'Installing Python Modules', _stdauthor, 'manual'),
+    ('library/index.rst', 'library.tex',
+     'The Python Library Reference', _stdauthor, 'manual'),
+    ('reference/index.rst', 'reference.tex',
+     'The Python Language Reference', _stdauthor, 'manual'),
+    ('tutorial/index.rst', 'tutorial.tex',
+     'Python Tutorial', _stdauthor, 'manual'),
+    ('using/index.rst', 'using.tex',
+     'Using Python', _stdauthor, 'manual'),
+    ('whatsnew/' + version + '.rst', 'whatsnew.tex',
+     'What\'s New in Python', 'A. M. Kuchling', 'howto'),
+]
+# Collect all HOWTOs individually
+import os
+latex_documents.extend(('howto/' + fn, 'howto-' + fn[:-4] + '.tex',
+                        'HOWTO', _stdauthor, 'howto')
+                       for fn in os.listdir('howto')
+                       if fn.endswith('.rst') and fn != 'index.rst')
+
+# Additional stuff for the LaTeX preamble.
+latex_preamble = r'''
+\authoraddress{
+  \strong{Python Software Foundation}\\
+  Email: \email{docs@python.org}
+}
+'''
 
-# The font size ("10pt", "11pt" or "12pt").
-latex_font_size = "10pt"
+# Documents to append as an appendix to all manuals.
+latex_appendices = ['glossary.rst', 'about.rst', 'license.rst', 'copyright.rst']

Doc/tools/sphinx-build.py

@@ -11,14 +11,14 @@ import sys
 
 if __name__ == '__main__':
 
-    if sys.version_info[:3] < (2, 5, 1):
-        print >>sys.stderr, """\
-Error: Sphinx needs to be executed with Python 2.5.1 or newer
-(If you run this from the Makefile, you can set the PYTHON variable
-to the path of an alternative interpreter executable, e.g.,
-``make html PYTHON=python2.5``).
-"""
-        sys.exit(1)
+#    if sys.version_info[:3] < (2, 5, 1):
+#        print >>sys.stderr, """\
+#Error: Sphinx needs to be executed with Python 2.5.1 or newer
+#(If you run this from the Makefile, you can set the PYTHON variable
+#to the path of an alternative interpreter executable, e.g.,
+#``make html PYTHON=python2.5``).
+#"""
+#        sys.exit(1)
 
     from sphinx import main
     sys.exit(main(sys.argv))

Doc/tools/sphinxext/download.html

+{% extends "layout.html" %}
+{% set title = 'Download' %}
+{% block body %}
+
+<h1>Download Python {{ release }} Documentation
+  {%- if last_updated %} (last updated on {{ last_updated }}){% endif %}</h1>
+
+<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>
+
+{# XXX download links #}
+
+
+<p>These archives contain all the content in the documentation section.</p>
+
+<h2>Unpacking</h2>
+
+<p>Unix users should download the .tar.bz2 archives; these are bzipped tar
+archives and can be handled in the usual way using tar and the bzip2
+program. The <a href="http://www.info-zip.org">InfoZIP</a> unzip program can be
+used to handle the ZIP archives if desired. The .tar.bz2 archives provide the
+best compression and fastest download times.</p>
+
+<p>Windows users can use the ZIP archives since those are customary on that
+platform. These are created on Unix using the InfoZIP zip program. They may be
+unpacked using the free WiZ tool (from the InfoZIP developers) or any other
+tool for handling ZIP archives; any of them should work.</p>
+
+<p>Note that the .tar.bz2 files are smaller than the other archives; Windows
+users may want to install the bzip2 tools on their systems as well. Windows
+binaries for a command-line tool are available at <a
+href="http://www.bzip.org">The bzip2 and libbzip2 official home page</a>, but
+most other archiving utilities support the tar and bzip2 formats as well.</p>
+
+
+<h2>Problems</h2>
+
+<p><strong>Printing PDFs using Adobe Acrobat Reader 5.0:</strong> Adobe has
+reportedly admitted that there is a bug in Acrobat Reader 5.0 which causes it
+not to print at least some PDF files generated by pdfTeX. This software is used
+to produce the PDF version of the Python documentation, and our documents
+definately trigger this bug in Acrobat Reader. To print the PDF files, use
+Acrobat Reader 4.x, ghostscript, or xpdf.</p>
+
+<p>Reportedly, Acrobat Reader 6.0 can print these documents without this
+problem, but we've not yet had an opportunity to confirm the report. Sadly,
+version 6.0 is not yet available on Unix platforms.</p>
+
+<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>
+
+{% endblock %}

Doc/tools/sphinxext/indexcontent.html

+  <p><strong>Parts of the documentation:</strong></p>
+  <table class="contentstable" align="center"><tr>
+    <td width="50%">
+      <p class="biglink"><a class="biglink" href="{{ pathto("whatsnew/" + version) }}">What's new in Python {{ version }}?</a><br>
+         <span class="linkdescr">changes since previous major release</span></p>
+      <p class="biglink"><a class="biglink" href="{{ pathto("tutorial/index") }}">Tutorial</a><br>
+         <span class="linkdescr">start here</span></p>
+      <p class="biglink"><a class="biglink" href="{{ pathto("using/index") }}">Using Python</a><br>
+         <span class="linkdescr">how to use Python on different platforms</span></p>
+      <p class="biglink"><a class="biglink" href="{{ pathto("reference/index") }}">Language Reference</a><br>
+         <span class="linkdescr">describes syntax and language elements</span></p>
+      <p class="biglink"><a class="biglink" href="{{ pathto("library/index") }}">Library Reference</a><br>
+         <span class="linkdescr">keep this under your pillow</span></p>
+      <p class="biglink"><a class="biglink" href="{{ pathto("howto/index") }}">Python HOWTOs</a><br>
+         <span class="linkdescr">in-depth documents on specific topics</span></p>
+    </td><td width="50%">
+      <p class="biglink"><a class="biglink" href="{{ pathto("extending/index") }}">Extending and Embedding</a><br>
+         <span class="linkdescr">tutorial for C/C++ programmers</span></p>
+      <p class="biglink"><a class="biglink" href="{{ pathto("c-api/index") }}">Python/C API</a><br>
+         <span class="linkdescr">reference for C/C++ programmers</span></p>
+      <p class="biglink"><a class="biglink" href="{{ pathto("install/index") }}">Installing Python Modules</a><br>
+         <span class="linkdescr">information for installers &amp; sys-admins</span></p>
+      <p class="biglink"><a class="biglink" href="{{ pathto("distutils/index") }}">Distributing Python Modules</a><br>
+         <span class="linkdescr">sharing modules with others</span></p>
+      <p class="biglink"><a class="biglink" href="{{ pathto("documenting/index") }}">Documenting Python</a><br>
+         <span class="linkdescr">guide for documentation authors</span></p>
+    </td></tr>
+  </table>
+
+  <p><strong>Indices and tables:</strong></p>
+  <table class="contentstable" align="center"><tr>
+    <td width="50%">
+      <p class="biglink"><a class="biglink" href="{{ pathto("modindex") }}">Global Module Index</a><br>
+         <span class="linkdescr">quick access to all modules</span></p>
+      <p class="biglink"><a class="biglink" href="{{ pathto("genindex") }}">General Index</a><br>
+         <span class="linkdescr">all functions, classes, terms</span></p>
+      <p class="biglink"><a class="biglink" href="{{ pathto("glossary") }}">Glossary</a><br>
+         <span class="linkdescr">the most important terms explained</span></p>
+    </td><td width="50%">
+      <p class="biglink"><a class="biglink" href="{{ pathto("search") }}">Search page</a><br>
+         <span class="linkdescr">search this documentation</span></p>
+      <p class="biglink"><a class="biglink" href="{{ pathto("contents") }}">Complete Table of Contents</a><br>
+         <span class="linkdescr">lists all sections and subsections</span></p>
+    </td></tr>
+  </table>
+
+  <p><strong>Meta information:</strong></p>
+  <table class="contentstable" align="center"><tr>
+    <td width="50%">
+      <p class="biglink"><a class="biglink" href="{{ pathto("bugs") }}">Reporting bugs</a></p>
+      <p class="biglink"><a class="biglink" href="{{ pathto("about") }}">About the documentation</a></p>
+    </td><td width="50%">
+      <p class="biglink"><a class="biglink" href="{{ pathto("license") }}">History and License of Python</a></p>
+      <p class="biglink"><a class="biglink" href="{{ pathto("copyright") }}">Copyright</a></p>
+    </td></tr>
+  </table>

Doc/tools/sphinxext/indexsidebar.html

+            <h3>Download</h3>
+            <p><a href="{{ pathto('download') }}">Download these documents</a></p>
+            <h3>Other resources</h3>
+            <ul>
+              {# XXX: many of these should probably be merged in the main docs #}
+              <li><a href="http://www.python.org/doc/faq/">FAQs</a></li>
+              <li><a href="http://www.python.org/doc/intros/">Introductions</a></li>
+              <li><a href="http://www.python.org/doc/essays/">Guido's Essays</a></li>
+              <li><a href="http://www.python.org/doc/newstyle/">New-style Classes</a></li>
+              <li><a href="http://www.python.org/dev/peps/">PEP Index</a></li>
+              <li><a href="http://wiki.python.org/moin/BeginnersGuide">Beginner's Guide</a></li>
+              <li><a href="http://www.python.org/topics/">Topic Guides</a></li>
+              <li><a href="http://wiki.python.org/moin/PythonBooks">Book List</a></li>
+              <li><a href="http://www.python.org/doc/av/">Audio/Visual Talks</a></li>
+              <li><a href="http://www.python.org/doc/other/">Other Doc Collections</a></li>
+              <li>&nbsp;</li>
+              <li><a href="http://www.python.org/doc/versions/">Previous versions</a></li>
+              <li>&nbsp;</li>
+            </ul>