mirror of https://github.com/python/cpython
Add Python-specific content to Doc dir. Update configuration file
to work with the newest Sphinx.
This commit is contained in:
Georg Brandl
parent
415c1e36a9
commit
7155a09c44
85
Doc/conf.py
85
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"
|
||||
# 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}
|
||||
}
|
||||
'''
|
||||
|
||||
# Documents to append as an appendix to all manuals.
|
||||
latex_appendices = ['glossary.rst', 'about.rst', 'license.rst', 'copyright.rst']
|
||||
|
|
|
|||
|
|
@ -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))
|
||||
|
|
|
|||
|
|
@ -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 %}
|
||||
|
|
@ -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>
|
||||
|
|
@ -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>
|
||||
Loading…
Reference in New Issue