diff options
| -rw-r--r-- | Doc/conf.py | 85 | ||||
| -rw-r--r-- | Doc/tools/sphinx-build.py | 16 | ||||
| -rw-r--r-- | Doc/tools/sphinxext/download.html | 53 | ||||
| -rw-r--r-- | Doc/tools/sphinxext/indexcontent.html | 56 | ||||
| -rw-r--r-- | Doc/tools/sphinxext/indexsidebar.html | 19 |
5 files changed, 211 insertions, 18 deletions
diff --git a/Doc/conf.py b/Doc/conf.py index 8e1c39d..7776332 100644 --- a/Doc/conf.py +++ b/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'] diff --git a/Doc/tools/sphinx-build.py b/Doc/tools/sphinx-build.py index 8f952be..ed2366b 100644 --- a/Doc/tools/sphinx-build.py +++ b/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)) diff --git a/Doc/tools/sphinxext/download.html b/Doc/tools/sphinxext/download.html new file mode 100644 index 0000000..f6a593a --- /dev/null +++ b/Doc/tools/sphinxext/download.html @@ -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@python.org">docs@python.org</a>.</p> + +{% endblock %} diff --git a/Doc/tools/sphinxext/indexcontent.html b/Doc/tools/sphinxext/indexcontent.html new file mode 100644 index 0000000..218f346 --- /dev/null +++ b/Doc/tools/sphinxext/indexcontent.html @@ -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> diff --git a/Doc/tools/sphinxext/indexsidebar.html b/Doc/tools/sphinxext/indexsidebar.html new file mode 100644 index 0000000..b74c54f --- /dev/null +++ b/Doc/tools/sphinxext/indexsidebar.html @@ -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> |