[Python-checkins] r60006 - in python/trunk/Doc: conf.py tools/sphinx-build.py tools/sphinxext tools/sphinxext/download.html tools/sphinxext/indexcontent.html tools/sphinxext/indexsidebar.html
georg.brandl
python-checkins at python.org
Wed Jan 16 21:27:56 CET 2008
Author: georg.brandl
Date: Wed Jan 16 21:27:56 2008
New Revision: 60006
Added:
python/trunk/Doc/tools/sphinxext/
python/trunk/Doc/tools/sphinxext/download.html
python/trunk/Doc/tools/sphinxext/indexcontent.html
python/trunk/Doc/tools/sphinxext/indexsidebar.html
Modified:
python/trunk/Doc/conf.py
python/trunk/Doc/tools/sphinx-build.py
Log:
Add Python-specific content to Doc dir. Update configuration file
to work with the newest Sphinx.
Modified: python/trunk/Doc/conf.py
==============================================================================
--- python/trunk/Doc/conf.py (original)
+++ python/trunk/Doc/conf.py Wed Jan 16 21:27:56 2008
@@ -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 @@
'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 @@
# 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 @@
# 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 at 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']
Modified: python/trunk/Doc/tools/sphinx-build.py
==============================================================================
--- python/trunk/Doc/tools/sphinx-build.py (original)
+++ python/trunk/Doc/tools/sphinx-build.py Wed Jan 16 21:27:56 2008
@@ -11,14 +11,14 @@
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))
Added: python/trunk/Doc/tools/sphinxext/download.html
==============================================================================
--- (empty file)
+++ python/trunk/Doc/tools/sphinxext/download.html Wed Jan 16 21:27:56 2008
@@ -0,0 +1,53 @@
+{% 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 at python.org">docs at python.org</a>.</p>
+
+{% endblock %}
Added: python/trunk/Doc/tools/sphinxext/indexcontent.html
==============================================================================
--- (empty file)
+++ python/trunk/Doc/tools/sphinxext/indexcontent.html Wed Jan 16 21:27:56 2008
@@ -0,0 +1,56 @@
+ <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 & 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>
Added: python/trunk/Doc/tools/sphinxext/indexsidebar.html
==============================================================================
--- (empty file)
+++ python/trunk/Doc/tools/sphinxext/indexsidebar.html Wed Jan 16 21:27:56 2008
@@ -0,0 +1,19 @@
+ <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> </li>
+ <li><a href="http://www.python.org/doc/versions/">Previous versions</a></li>
+ <li> </li>
+ </ul>
More information about the Python-checkins
mailing list