IntenseWebs/sphinx
3
0
Fork 0
mirror of https://github.com/sphinx-doc/sphinx.git synced 2025-02-25 18:55:22 -06:00
Code Issues Packages Projects Releases Wiki Activity

Merge with birkenfeld/sphinx

Browse Source
This commit is contained in:
Roland Meister
2010-01-09 11:06:00 +01:00
parent 1ab6457436 1efbe7c623
commit 3e9c7dc8a6
171 changed files with 2616 additions and 1010 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
AUTHORS
View File

@@ -5,6 +5,8 @@ Substantial parts of the templates were written by Armin Ronacher
Other contributors, listed alphabetically, are:
* Andi Albrecht -- agogo theme
* Henrique Bastos -- SVG support for graphviz extension
* Daniel Bültmann -- todo extension
* Michael Droettboom -- inheritance_diagram extension
* Charles Duffy -- original graphviz extension
@@ -14,7 +16,9 @@ Other contributors, listed alphabetically, are:
* Dave Kuhlman -- original LaTeX writer
* Thomas Lamb -- linkcheck builder
* Dan MacKinlay -- metadata fixes
* Martin Mahner -- nature theme
* Will Maier -- directory HTML builder
* Roland Meister -- epub builder
* Christopher Perkins -- autosummary integration
* Benjamin Peterson -- unittests
* Stefan Seefeld -- toctree improvements

70
CHANGES
View File

@@ -1,12 +1,44 @@
Release 1.0 (in development)
============================
* Added ``tab-width`` option to ``literalinclude`` directive.
* The ``html_sidebars`` config value can now contain patterns as
keys, and the values can be lists that explicitly select which
sidebar templates should be rendered. That means that the builtin
sidebar contents can be included only selectively.
* ``html_static_path`` can now contain single file entries.
* The new universal config value ``exclude_patterns`` makes the
old ``unused_docs``, ``exclude_trees`` and ``exclude_dirnames``
obsolete.
* Remove the deprecated ``exclude_dirs`` config value.
* #129: Wrap toctrees in a div tag with class ``toctree-wrapper``
in HTML output.
* #280: Autodoc can now document instance attributes assigned in
``__init__`` methods.
* Added ``alt`` option to ``graphviz`` extension directives.
* Added Epub builder.
* #309: The ``graphviz`` extension can now output SVG instead of PNG
images, controlled by the ``graphviz_output_format`` config value.
* #284: All docinfo metadata is now put into the document metadata, not
just the author.
* Added new HTML theme ``haiku``, inspired by the Haiku OS user guide.
* Added new HTML theme ``nature``.
* Added new HTML theme ``agogo``, created by Andi Albrecht.
* Added new minimal theme called scrolls, created by Armin Ronacher.
* Added new HTML theme ``scrolls``, created by Armin Ronacher.
* Added ``html_output_encoding`` config value.
@@ -47,6 +79,42 @@ Release 1.0 (in development)
Release 0.6.4 (in development)
==============================
* Restore compatibility with Pygments >= 1.2.
* #295: Fix escaping of hyperref targets in LaTeX output.
* #302: Fix links generated by the ``:doc:`` role for LaTeX output.
* #286: collect todo nodes after the whole document has been read;
this allows placing substitution references in todo items.
* #294: do not ignore an explicit ``today`` config value in a
LaTeX build.
* The ``alt`` text of inheritance diagrams is now much cleaner.
* Ignore images in section titles when generating link captions.
* #310: support exception messages in the ``testoutput`` blocks of
the ``doctest`` extension.
* #293: line blocks are styled properly in HTML output.
* #285: make the ``locale_dirs`` config value work again.
* #303: ``html_context`` values given on the command line via ``-A``
should not override other values given in conf.py.
* Fix a bug preventing incremental rebuilds for the ``dirhtml``
builder.
* #299: Fix the mangling of quotes in some literal blocks.
* #292: Fix path to the search index for the ``dirhtml`` builder.
* Fix a Jython compatibility issue: make the dependence on the
``parser`` module optional.
* #238: In autodoc, catch all errors that occur on module import,
not just ``ImportError``.

149
EXAMPLES
View File

@@ -1,93 +1,136 @@
Projects using Sphinx
=====================
This is an (incomplete) alphabetic list of projects that use Sphinx or are
experimenting with using it for their documentation. If you like to be
included, please mail to `the Google group
This is an (incomplete) alphabetic list of projects that use Sphinx or
are experimenting with using it for their documentation. If you like to
be included, please mail to `the Google group
<http://groups.google.com/group/sphinx-dev>`_.
* Applied Mathematics at the Stellenbosch University: http://dip.sun.ac.za/
I've grouped the list into sections to make it easier to find
interesting examples.
Documentation using the default theme
-------------------------------------
* APSW: http://apsw.googlecode.com/svn/publish/index.html
* ASE: https://wiki.fysik.dtu.dk/ase/
* Blender: http://www.blender.org/documentation/250PythonDoc/
* boostmpi: http://documen.tician.de/boostmpi/
* Calibre: http://calibre.kovidgoyal.net/user_manual/
* Chaco: http://code.enthought.com/projects/chaco/docs/html/
* CodePy: http://documen.tician.de/codepy/
* Cython: http://docs.cython.org/
* C\\C++ Python language binding project: http://language-binding.net/index.html
* Director: http://packages.python.org/director/
* Djagios: http://djagios.org/
* Django: http://docs.djangoproject.com/
* F2py: http://www.f2py.org/html/
* Fityk: http://www.unipress.waw.pl/fityk/
* GeoDjango: http://geodjango.org/docs/
* GeoServer: http://docs.geoserver.org/
* Glashammer: http://glashammer.org/
* GPAW: https://wiki.fysik.dtu.dk/gpaw/
* Grok: http://grok.zope.org/doc/current/
* GSL Shell: http://www.nongnu.org/gsl-shell/
* Hedge: http://documen.tician.de/hedge/
* IFM: http://fluffybunny.memebot.com/ifm-docs/index.html
* Jinja: http://jinja.pocoo.org/2/documentation/
* Kaa: http://doc.freevo.org/api/kaa/
* LEPL: http://www.acooke.org/lepl/
* MapServer: http://mapserver.org/
* Matplotlib: http://matplotlib.sourceforge.net/
* Mayavi: http://code.enthought.com/projects/mayavi/docs/development/html/mayavi
* MeshPy: http://documen.tician.de/meshpy/
* MirrorBrain: http://mirrorbrain.org/docs/
* Mixin.com: http://dev.mixin.com/
* mpmath: http://mpmath.googlecode.com/svn/trunk/doc/build/index.html
* MyHDL: http://www.myhdl.org/doc/0.6/
* NetworkX: http://networkx.lanl.gov/
* NOC: http://trac.nocproject.org/trac/wiki/NocGuide
* nose: http://somethingaboutorange.com/mrl/projects/nose/
* NumPy: http://docs.scipy.org/doc/numpy/reference/
* ObjectListView: http://objectlistview.sourceforge.net/python
* Open ERP: http://doc.openerp.com/
* OpenEXR: http://excamera.com/articles/26/doc/index.html
* OpenLayers: http://docs.openlayers.org/
* OpenGDA: http://www.opengda.org/gdadoc/html/
* openWNS: http://docs.openwns.org/
* Paste: http://pythonpaste.org/script/
* Paver: http://www.blueskyonmars.com/projects/paver/
* Py on Windows: http://timgolden.me.uk/python-on-windows/
* Pyccuracy: http://www.pyccuracy.org/
* PyCuda: http://documen.tician.de/pycuda/
* PyEphem: http://rhodesmill.org/pyephem/
* Pyevolve: http://pyevolve.sourceforge.net/
* PyLit: http://pylit.berlios.de/
* Pylo: http://documen.tician.de/pylo/
* Pylons: http://docs.pylonshq.com/
* PyMOTW: http://www.doughellmann.com/PyMOTW/
* PyPubSub: http://pubsub.sourceforge.net/
* pyrticle: http://documen.tician.de/pyrticle/
* Pysparse: http://pysparse.sourceforge.net/
* Python: http://docs.python.org/
* python-apt: http://people.debian.org/~jak/python-apt-doc/
* python-apt: http://apt.alioth.debian.org/python-apt-doc/
* PyUblas: http://documen.tician.de/pyublas/
* Quex: http://quex.sourceforge.net/
* Reteisi: http://docs.argolinux.org/reteisi/
* Roundup: http://www.roundup-tracker.org/
* Sage: http://sagemath.org/doc/
* Satchmo: http://www.satchmoproject.com/docs/svn/
* Quex: http://quex.sourceforge.net/doc/html/main.html
* Scapy: http://www.secdev.org/projects/scapy/doc/
* SimPy: http://simpy.sourceforge.net/SimPyDocs/index.html
* SymPy: http://docs.sympy.org/
* WTForms: http://wtforms.simplecodes.com/docs/
* z3c: http://docs.carduner.net/z3c-tutorial/
Documentation using a customized version of the default theme
-------------------------------------------------------------
* Advanced Generic Widgets: http://xoomer.virgilio.it/infinity77/AGW_Docs/index.html
* Bazaar: http://doc.bazaar.canonical.com/en/
* Chaco: http://code.enthought.com/projects/chaco/docs/html/
* Djagios: http://djagios.org/
* GPAW: https://wiki.fysik.dtu.dk/gpaw/
* Grok: http://grok.zope.org/doc/current/
* IFM: http://fluffybunny.memebot.com/ifm-docs/index.html
* LEPL: http://www.acooke.org/lepl/
* Mayavi: http://code.enthought.com/projects/mayavi/docs/development/html/mayavi
* NOC: http://trac.nocproject.org/trac/wiki/NocGuide
* NumPy: http://docs.scipy.org/doc/numpy/reference/
* Peach^3: http://peach3.nl/doc/latest/userdoc/
* Py on Windows: http://timgolden.me.uk/python-on-windows/
* PyLit: http://pylit.berlios.de/
* Sage: http://sagemath.org/doc/
* SciPy: http://docs.scipy.org/doc/scipy/reference/
* Sprox: http://sprox.org/
* TurboGears: http://turbogears.org/2.0/docs/
* Zope: http://docs.zope.org/zope2/index.html
* zc.async: http://packages.python.org/zc.async/1.5.0/
Documentation using the sphinxdoc theme
---------------------------------------
* Fityk: http://www.unipress.waw.pl/fityk/
* MapServer: http://mapserver.org/
* Matplotlib: http://matplotlib.sourceforge.net/
* MyHDL: http://www.myhdl.org/doc/0.6/
* NetworkX: http://networkx.lanl.gov/
* Pysparse: http://pysparse.sourceforge.net/
* PyTango: http://www.tango-controls.org/static/PyTango/latest/doc/html/index.html
* Reteisi: http://docs.argolinux.org/reteisi/
* Satchmo: http://www.satchmoproject.com/docs/svn/
* Sphinx: http://sphinx.pocoo.org/
* Sqlkit: http://sqlkit.argolinux.org/
* Total Open Station: http://tops.berlios.de/
* WebFaction: http://docs.webfaction.com/
Documentation using another builtin theme
-----------------------------------------
* Distribute: http://packages.python.org/distribute/ (nature)
* Jinja: http://jinja.pocoo.org/2/documentation/ (scrolls)
* pip: http://pip.openplans.org/ (nature)
* sqlparse: http://python-sqlparse.googlecode.com/svn/docs/api/index.html (agogo)
Documentation using a custom theme/integrated in a site
-------------------------------------------------------
* Django: http://docs.djangoproject.com/
* GeoServer: http://docs.geoserver.org/
* Glashammer: http://glashammer.org/
* MirrorBrain: http://mirrorbrain.org/docs/
* nose: http://somethingaboutorange.com/mrl/projects/nose/
* ObjectListView: http://objectlistview.sourceforge.net/python
* Open ERP: http://doc.openerp.com/
* OpenLayers: http://docs.openlayers.org/
* PyEphem: http://rhodesmill.org/pyephem/
* Pylons: http://pylonshq.com/docs/en/0.9.7/
* PyMOTW: http://www.doughellmann.com/PyMOTW/
* Roundup: http://www.roundup-tracker.org/
* Selenium: http://seleniumhq.org/docs/
* Self: http://selflanguage.org/
* SimPy: http://simpy.sourceforge.net/
* Sphinx: http://sphinx.pocoo.org/
* Sprox: http://sprox.org/
* SQLAlchemy: http://www.sqlalchemy.org/docs/
* Sqlkit: http://sqlkit.argolinux.org/
* sqlparse: http://python-sqlparse.googlecode.com/svn/docs/api/index.html
* SymPy: http://docs.sympy.org/
* tinyTiM: http://tinytim.sourceforge.net/docs/2.0/
* The Wine Cellar Book: http://www.thewinecellarbook.com/doc/en/
* TurboGears: http://turbogears.org/2.0/docs/
* VOR: http://www.vor-cycling.be/
* WebFaction: http://docs.webfaction.com/
* Werkzeug: http://werkzeug.pocoo.org/documentation/dev/
* WFront: http://discorporate.us/projects/WFront/
* WTForms: http://wtforms.simplecodes.com/docs/
* Zope 3: e.g. http://docs.carduner.net/z3c-tutorial/
* zc.async: http://packages.python.org/zc.async/1.5.0/
Homepages and other non-documentation sites
-------------------------------------------
* Applied Mathematics at the Stellenbosch University: http://dip.sun.ac.za/
* A personal page: http://www.dehlia.in/
* Benoit Boissinot: http://perso.ens-lyon.fr/benoit.boissinot/
* lunarsite: http://lunaryorn.de/
* The Wine Cellar Book: http://www.thewinecellarbook.com/doc/en/
* VOR: http://www.vor-cycling.be/

2
LICENSE
View File

@@ -1,7 +1,7 @@
License for Sphinx
==================
Copyright (c) 2007-2009 by the Sphinx team (see AUTHORS file).
Copyright (c) 2007-2010 by the Sphinx team (see AUTHORS file).
All rights reserved.
Redistribution and use in source and binary forms, with or without

2
Makefile
View File

@@ -8,7 +8,7 @@ all: clean-pyc check test
check:
@$(PYTHON) utils/check_sources.py -i build -i dist -i sphinx/style/jquery.js \
-i sphinx/pycode/pgen2 -i sphinx/util/smartypants.py \
-i sphinx/pycode/pgen2 -i sphinx/util/smartypants.py -i .ropeproject \
-i doc/_build -i ez_setup.py -i tests/path.py -i tests/coverage.py .
clean: clean-pyc clean-patchfiles

2
doc/_templates/indexsidebar.html vendored
View File

@@ -11,6 +11,8 @@
<p>Get Sphinx from the <a href="http://pypi.python.org/pypi/Sphinx">Python Package
Index</a>, or install it with:</p>
<pre>easy_install -U Sphinx</pre>
<p>Latest <a href="http://sphinx.pocoo.org/latest/">development version docs</a>
are also available.</p>
{% endif %}
<h3>Questions? Suggestions?</h3>

3
doc/_templates/layout.html vendored
View File

@@ -1,12 +1,13 @@
{% extends "!layout.html" %}
{% block extrahead %}
{{ super() }}
{%- if not embedded %}
<style type="text/css">
table.right { float: right; margin-left: 20px; }
table.right td { border: 1px solid #ccc; }
</style>
{% endif %}
{%- endif %}
{% endblock %}
{% block rootrellink %}

8
doc/builders.rst
View File

@@ -67,11 +67,9 @@ The builder's "name" must be given to the **-b** command-line option of
.. class:: EpubBuilder
This builder produces the same output as the standalone HTML builder, but
also generates an *epub* file for ebook readers.
This builder is meant to be used together with the
:confval:`html_theme` ``'epub'``.
See `<http://www.idpf.org/specs.htm>`_ or
`<http://en.wikipedia.org/wiki/EPUB>`_ for the definition of epubs.
also generates an *epub* file for ebook readers. See :ref:`epub-faq` for
details about it. For definition of the epub format, have a look at
`<http://www.idpf.org/specs.htm>`_ or `<http://en.wikipedia.org/wiki/EPUB>`_.
Its name is ``epub``.

4
doc/concepts.rst
View File

@@ -133,8 +133,8 @@ tables of contents. The ``toctree`` directive is the central element.
In the end, all documents in the :term:`source directory` (or subdirectories)
must occur in some ``toctree`` directive; Sphinx will emit a warning if it
finds a file that is not included, because that means that this file will not
be reachable through standard navigation. Use :confval:`unused_documents` to
explicitly exclude documents from building, and :confval:`exclude_dirs` to
be reachable through standard navigation. Use :confval:`unused_docs` to
explicitly exclude documents from building, and :confval:`exclude_trees` to
exclude whole directories.
The "master document" (selected by :confval:`master_doc`) is the "root" of

15
doc/conf.py
View File

@@ -9,8 +9,6 @@ import sys, os, re
extensions = ['sphinx.ext.autodoc', 'sphinx.ext.doctest', 'sphinx.ext.todo',
'sphinx.ext.autosummary']
extlinks = {'issue': ('http://bugs.python.org/issue', 'issue ')}
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
@@ -20,9 +18,11 @@ source_suffix = '.rst'
# The master toctree document.
master_doc = 'contents'
exclude_patterns = ['_build']
# General substitutions.
project = 'Sphinx'
copyright = '2007-2009, Georg Brandl'
copyright = '2007-2010, Georg Brandl'
# The default replacements for |version| and |release|, also used in various
# other places throughout the built documents.
@@ -34,7 +34,7 @@ release = version
show_authors = True
# The HTML template theme.
html_theme = 'epub'
html_theme = 'sphinxdoc'
# A list of ignored prefixes names for module index sorting.
modindex_common_prefix = ['sphinx.']
@@ -52,7 +52,7 @@ html_last_updated_fmt = '%b %d, %Y'
html_index = 'index.html'
# Custom sidebar templates, maps page names to templates.
html_sidebars = {'index': 'indexsidebar.html'}
html_sidebars = {'index': ['indexsidebar.html', 'searchbox.html']}
# Additional templates that should be rendered to pages, maps page names to
# templates.
@@ -65,12 +65,13 @@ html_use_opensearch = 'http://sphinx.pocoo.org'
htmlhelp_basename = 'Sphinxdoc'
# Epub fields
epub_theme = 'epub'
epub_basename = 'sphinx'
epub_author = 'Georg Brandl'
epub_author = 'Georg Brandl'
epub_publisher = 'http://sphinx.pocoo.org/'
epub_scheme = 'url'
epub_identifier = epub_publisher
epub_pre_files = [ ('index', 'Welcome')]
epub_pre_files = [('index', 'Welcome')]
epub_exclude_files = ['_static/opensearch.xml', '_static/doctools.js',
'_static/jquery.js', '_static/searchtools.js',
'_static/basic.css', 'search.html']

184
doc/config.rst
View File

@@ -87,12 +87,37 @@ General configuration
The document name of the "master" document, that is, the document that
contains the root :dir:`toctree` directive. Default is ``'contents'``.
.. confval:: exclude_patterns
A list of glob-style patterns that should be excluded when looking for source
files. [1]_ They are matched against the source file names relative to the
source directory, using slashes as directory separators on all platforms.
Example patterns:
- ``'library/xml.rst'`` -- ignores the ``library/xml.rst`` file (replaces
entry in :confval:`unused_docs`
- ``'library/xml'`` -- ignores the ``library/xml`` directory (replaces entry
in :confval:`exclude_trees`)
- ``'library/xml*'`` -- ignores all files and directories starting with
``library/xml``
- ``'**/.svn'`` -- ignores all ``.svn`` directories (replaces entry in
:confval:`exclude_dirnames`)
:confval:`exclude_patterns` is also consulted when looking for static files
in :confval:`html_static_path`.
.. versionadded:: 1.0
.. confval:: unused_docs
A list of document names that are present, but not currently included in the
toctree. Use this setting to suppress the warning that is normally emitted
in that case.
.. deprecated:: 1.0
Use :confval:`exclude_patterns` instead.
.. confval:: exclude_trees
A list of directory paths, relative to the source directory, that are to be
@@ -101,6 +126,9 @@ General configuration
.. versionadded:: 0.4
.. deprecated:: 1.0
Use :confval:`exclude_patterns` instead.
.. confval:: exclude_dirnames
A list of directory names that are to be excluded from any recursive
@@ -110,15 +138,8 @@ General configuration
.. versionadded:: 0.5
.. confval:: exclude_dirs
A list of directory names, relative to the source directory, that are to be
excluded from the search for source files.
.. deprecated:: 0.5
This does not take subdirs of the excluded directories into account. Use
:confval:`exclude_trees` or :confval:`exclude_dirnames`, which match the
expectations.
.. deprecated:: 1.0
Use :confval:`exclude_patterns` instead.
.. confval:: locale_dirs
@@ -398,6 +419,9 @@ that use Sphinx' HTMLWriter class.
.. versionchanged:: 0.4
The paths in :confval:`html_static_path` can now contain subdirectories.
.. versionchanged:: 1.0
The entries in :confval:`html_static_path` can now be single files.
.. confval:: html_last_updated_fmt
If this is not the empty string, a 'Last updated on:' timestamp is inserted
@@ -421,14 +445,53 @@ that use Sphinx' HTMLWriter class.
.. confval:: html_sidebars
Custom sidebar templates, must be a dictionary that maps document names to
template names. Example::
template names.
The keys can contain glob-style patterns [1]_, in which case all matching
documents will get the specified sidebars. (A warning is emitted when a
more than one glob-style pattern matches for any document.)
The values can be either lists or single strings.
* If a value is a list, it specifies the complete list of sidebar templates
to include. If all or some of the default sidebars are to be included,
they must be put into this list as well.
The default sidebars (for documents that don't match any pattern) are:
``['localtoc.html', 'relations.html', 'sourcelink.html',
'searchbox.html']``.
* If a value is a single string, it specifies a custom sidebar to be added
between the ``'sourcelink.html'`` and ``'searchbox.html'`` entries. This
is for compatibility with Sphinx versions before 1.0.
Builtin sidebar templates that can be rendered are:
* **localtoc.html** -- a fine-grained table of contents of the current document
* **globaltoc.html** -- a coarse-grained table of contents for the whole
documentation set, collapsed
* **relations.html** -- two links to the previous and next documents
* **sourcelink.html** -- a link to the source of the current document, if
enabled in :confval:`html_show_sourcelink`
* **searchbox.html** -- the "quick search" box
Example::
html_sidebars = {
'using/windows': 'windowssidebar.html'
'**': ['globaltoc.html', 'sourcelink.html', 'searchbox.html'],
'using/windows': ['windowssidebar.html', 'searchbox.html'],
}
This will render the template ``windowssidebar.html`` within the sidebar of
the given document.
This will render the custom template ``windowssidebar.html`` and the quick
search box within the sidebar of the given document, and render the default
sidebars for all other pages (except that the local TOC is replaced by the
global TOC).
.. versionadded:: 1.0
The ability to use globbing keys and to specify multiple sidebars.
Note that this value only has no effect if the chosen theme does not possess
a sidebar, like the builtin **scrolls** and **haiku** themes.
.. confval:: html_additional_pages
@@ -554,92 +617,89 @@ that use Sphinx' HTMLWriter class.
Options for epub output
-----------------------
These options influence the epub output. As this writer derives from the
HTMLWriter the HTML options also apply where appropriate.
The actual values for some of the options is not really important,
they just have to be entered into
These options influence the epub output. As this builder derives from the HTML
builder, the HTML options also apply where appropriate. The actual values for
some of the options is not really important, they just have to be entered into
the `Dublin Core metadata <http://dublincore.org/>`_.
.. confval:: epub_basename
The basename for the epub file. It defaults to the :confval:`project` name.
The basename for the epub file. It defaults to the :confval:`project` name.
.. confval:: epub_theme
The HTML theme for the epub output. Since the default themes are not
optimized for small screen space, using the same theme for HTML and epub
output is usually not wise. This defaults to ``'epub'``, a theme designed to
save visual space.
.. confval:: epub_title
The title of the document.
It defaults to the :confval:`html_title` option
but can be set independently for epub creation.
The title of the document. It defaults to the :confval:`html_title` option
but can be set independently for epub creation.
.. confval:: epub_author
The author of the document.
This is put in the Dublin Core metadata.
The default value is ``'unknown'``.
The author of the document. This is put in the Dublin Core metadata. The
default value is ``'unknown'``.
.. confval:: epub_language
The language of the document.
This is put in the Dublin Core metadata.
The default is the :confval:`language` option or ``'en'`` if unset.
The language of the document. This is put in the Dublin Core metadata. The
default is the :confval:`language` option or ``'en'`` if unset.
.. confval:: epub_publisher
The publisher of the document.
This is put in the Dublin Core metadata.
You may use any sensible string, e.g. the project homepage.
The default value is ``'unknown'``.
The publisher of the document. This is put in the Dublin Core metadata. You
may use any sensible string, e.g. the project homepage. The default value is
``'unknown'``.
.. confval:: epub_copyright
The copyright of the document.
It defaults to the :confval:`copyright` option
but can be set independently for epub creation.
The copyright of the document. It defaults to the :confval:`copyright`
option but can be set independently for epub creation.
.. confval:: epub_identifier
An identifier for the document.
This is put in the Dublin Core metadata.
For published documents this is the ISBN number, but you can
also use an alternative scheme, e.g. the project homepage.
The default value is ``'unknown'``.
An identifier for the document. This is put in the Dublin Core metadata.
For published documents this is the ISBN number, but you can also use an
alternative scheme, e.g. the project homepage. The default value is
``'unknown'``.
.. confval:: epub_scheme
The publication scheme for the :confval:`epub_identifier`.
This is put in the Dublin Core metadata.
For published books the scheme is ``'ISBN'``.
If you use the project homepage, ``'URL'`` seems reasonable.
The publication scheme for the :confval:`epub_identifier`. This is put in
the Dublin Core metadata. For published books the scheme is ``'ISBN'``. If
you use the project homepage, ``'URL'`` seems reasonable. The default value
is ``'unknown'``.
.. confval:: epub_uid
A unique identifier for the document.
This is put in the Dublin Core metadata.
You may use a random string.
The default value is ``'unknown'``.
A unique identifier for the document. This is put in the Dublin Core
metadata. You may use a random string. The default value is ``'unknown'``.
.. confval:: epub_pre_files
Additional files that should be inserted before the text generated by
Sphinx. It is a list of tuples containing the file name and the title.
Example::
Additional files that should be inserted before the text generated by
Sphinx. It is a list of tuples containing the file name and the title.
Example::
epub_pre_files = [
('index.html', 'Welcome'),
('index.html', 'Welcome'),
]
The default value is ``[]``.
The default value is ``[]``.
.. confval:: epub_post_files
Additional files that should be inserted after the text generated by
Sphinx. It is a list of tuples containing the file name and the title.
The default value is ``[]``.
Additional files that should be inserted after the text generated by Sphinx.
It is a list of tuples containing the file name and the title. The default
value is ``[]``.
.. confval:: epub_exclude_files
A list of files that are generated/copied in the build directory
but should not be included in the epub file.
The default value is ``[]``.
A list of files that are generated/copied in the build directory but should
not be included in the epub file. The default value is ``[]``.
.. _latex-options:
@@ -810,3 +870,11 @@ These options influence LaTeX output.
.. deprecated:: 0.5
Use the ``'pointsize'`` key in the :confval:`latex_elements` value.
.. rubric:: Footnotes
.. [1] A note on available globbing syntax: you can use the standard shell
constructs ``*``, ``?``, ``[...]`` and ``[!...]`` with the feature that
these all don't match slashes. A double star ``**`` can be used to match
any sequence of characters *including* slashes.

10
doc/ext/appapi.rst
View File

@@ -56,9 +56,11 @@ the following public API:
given as keyword arguments: the keyword must be one or more of ``'html'``,
``'latex'``, ``'text'``, the value a 2-tuple of ``(visit, depart)`` methods.
``depart`` can be ``None`` if the ``visit`` function raises
:exc:`docutils.nodes.SkipNode`. Example::
:exc:`docutils.nodes.SkipNode`. Example:
class math(docutils.nodes.Element)
.. code-block:: python
class math(docutils.nodes.Element): pass
def visit_math_html(self, node):
self.body.append(self.starttag(node, 'math'))
@@ -98,7 +100,9 @@ the following public API:
support directive classes otherwise).
For example, the (already existing) :dir:`literalinclude` directive would be
added like this::
added like this:
.. code-block:: python
from docutils.parsers.rst import directives
add_directive('literalinclude', literalinclude_directive,

4
doc/ext/autosummary.rst
View File

@@ -163,6 +163,8 @@ Autosummary uses the following template files:
The following variables available in the templates:
.. currentmodule:: None
.. data:: name
Name of the documented object, excluding the module and class parts.
@@ -214,7 +216,7 @@ The following variables available in the templates:
List containing names of "public" methods in the class. Only available for
classes.
.. data:: methods
.. data:: attributes
List containing names of "public" attributes in the class. Only available
for classes.

28
doc/ext/doctest.rst
View File

@@ -87,10 +87,30 @@ names.
* ``hide``, a flag option, hides the code block in other builders. By
default it is shown as a highlighted code block.
.. note::
Code in a ``testcode`` block is always executed all at once, no matter how
many statements it contains. Therefore, output will *not* be generated
for bare expressions -- use ``print``. Example::
.. testcode::
1+1 # this will give no output!
print 2+2 # this will give output
.. testoutput::
4
Also, please be aware that since the doctest module does not support
mixing regular output and an exception message in the same snippet, this
applies to testcode/testoutput as well.
.. directive:: .. testoutput:: [group]
The corresponding output for the last :dir:`testcode` block.
The corresponding output, or the exception message, for the last
:dir:`testcode` block.
This directive supports two options:
@@ -102,6 +122,10 @@ names.
Example::
.. testcode::
print 'Output text.'
.. testoutput::
:hide:
:options: -ELLIPSIS, +NORMALIZE_WHITESPACE
@@ -111,7 +135,7 @@ names.
The following is an example for the usage of the directives. The test via
:dir:`doctest` and the test via :dir:`testcode` and :dir:`testoutput` are
completely equivalent. ::
equivalent. ::
The parrot module
=================

9
doc/ext/extlinks.rst
View File

@@ -27,11 +27,13 @@ The extension adds one new config value:
short alias names to a base URL and a *prefix*. For example, to create an
alias for the above mentioned issues, you would add ::
extlinks = {'issue': ('http://bitbucket.org/birkenfeld/sphinx/issue/',
extlinks = {'issue': ('http://bitbucket.org/birkenfeld/sphinx/issue/%s',
'issue ')}
Now, you can use the alias name as a new role, e.g. ``:issue:`123```. This
then inserts a link to http://bitbucket.org/birkenfeld/sphinx/issue/123.
As you can see, the target given in the role is substituted in the base URL
in the place of ``%s``.
The link *caption* depends on the second item in the tuple, the *prefix*:
@@ -45,3 +47,8 @@ The extension adds one new config value:
You can also use the usual "explicit title" syntax supported by other roles
that generate links, i.e. ``:issue:`this issue <123>```. In this case, the
*prefix* is not relevant.
.. note::
Since links are generated from the role in the reading stage, they appear as
ordinary links to e.g. the ``linkcheck`` builder.

19
doc/ext/graphviz.rst
View File

@@ -25,8 +25,9 @@ It adds these directives:
"bar" -> "baz";
}
In HTML output, the code will be rendered to a PNG image. In LaTeX output,
the code will be rendered to an embeddable PDF file.
In HTML output, the code will be rendered to a PNG or SVG image (see
:confval:`graphviz_output_format`). In LaTeX output, the code will be
rendered to an embeddable PDF file.
.. directive:: graph
@@ -55,6 +56,12 @@ It adds these directives:
"bar" -> "baz" -> "quux";
.. versionadded:: 1.0
All three directives support an ``alt`` option that determines the image's
alternate text for HTML output. If not given, the alternate text defaults to
the graphviz code.
There are also these new config values:
.. confval:: graphviz_dot
@@ -75,3 +82,11 @@ There are also these new config values:
Additional command-line arguments to give to dot, as a list. The default is
an empty list. This is the right place to set global graph, node or edge
attributes via dot's ``-G``, ``-N`` and ``-E`` options.
.. confval:: graphviz_output_format
The output format for Graphviz when building HTML files. This must be either
``'png'`` or ``'svg'``; the default is ``'png'``.
.. versionadded:: 1.0
Previously, output always was PNG.

4
doc/ext/math.rst
View File

@@ -191,10 +191,10 @@ value:
JSMath. There is no default.
The path can be absolute or relative; if it is relative, it is relative to
the root of the built docs.
the ``_static`` directory of the built docs.
For example, if you put JSMath into the static path of the Sphinx docs, this
value would be ``_static/jsMath/easy/load.js``. If you host more than one
value would be ``jsMath/easy/load.js``. If you host more than one
Sphinx documentation set on one server, it is advisable to install jsMath in
a shared location.

4
doc/extensions.rst
View File

@@ -61,8 +61,8 @@ There are several extensions that are not (yet) maintained in the Sphinx
distribution. The `Wiki at BitBucket`_ maintains a list of those.
If you write an extension that you think others will find useful, please write
to the project mailing list (sphinx-dev@googlegroups.com) and we'll find the
proper way of including or hosting it for the public.
to the project mailing list (`join here <http://groups.google.com/group/sphinx-dev>`_)
and we'll find the proper way of including or hosting it for the public.
.. _Wiki at BitBucket: http://www.bitbucket.org/birkenfeld/sphinx/wiki/Home

66
doc/faq.rst
View File

@@ -54,46 +54,42 @@ github pages
Sphinx HTML output.
Epub
----
.. _api role: http://git.savannah.gnu.org/cgit/kenozooid.git/tree/doc/extapi.py
.. _xhtml to reST: http://docutils.sourceforge.net/sandbox/xhtml2rest/xhtml2rest.py
The EpubBuilder is currently in an experimental stage.
It has only been tested with the Sphinx documentation itself.
If you want to create epubs, here are some notes:
* Split the text into several files. The longer the individual HTML files
are, the longer it takes the ebook reader to render them.
In extreme cases, the rendering can take up to one minute.
.. _epub-faq:
* Try to minimize the markup. This also pays in rendering time.
Epub info
---------
* For some readers you can use embedded or external fonts
using the CSS ``@font-face`` directive.
This is *extremely* useful for code listings which are often cut
at the right margin. The default Courier font (or variant) is quite
wide and you can only display up to 60 characters on a line.
If you replace it with a narrower font, you can get more characters
on a line. You may even use
`fontforge <http://fontforge.sourceforge.net/>`_
and create narrow variants
of some free font. In my case I get up to 70 characters on a line.
The epub builder is currently in an experimental stage. It has only been tested
with the Sphinx documentation itself. If you want to create epubs, here are
some notes:
* Split the text into several files. The longer the individual HTML files are,
the longer it takes the ebook reader to render them. In extreme cases, the
rendering can take up to one minute.
* Try to minimize the markup. This also pays in rendering time.
* For some readers you can use embedded or external fonts using the CSS
``@font-face`` directive. This is *extremely* useful for code listings which
are often cut at the right margin. The default Courier font (or variant) is
quite wide and you can only display up to 60 characters on a line. If you
replace it with a narrower font, you can get more characters on a line. You
may even use `FontForge <http://fontforge.sourceforge.net/>`_ and create
narrow variants of some free font. In my case I get up to 70 characters on a
line.
You may have to experiment a little until you get reasonable results.
* Test the created epubs. You can use several alternatives.
The ones I am aware of are
Epubcheck
(`http://code.google.com/p/epubcheck/
<http://code.google.com/p/epubcheck/>`_),
Calibre
(`http://calibre-ebook.com/ <http://calibre-ebook.com/>`_),
FBreader (`http://www.fbreader.org/ <http://www.fbreader.org/>`_,
although it does not render the CSS), and
Bookworm (`http://bookworm.oreilly.com/ <http://bookworm.oreilly.com/>`_).
For bookworm you can download the source from
`http://code.google.com/p/threepress/ <http://code.google.com/p/threepress/>`_
and run you own local server.
* Test the created epubs. You can use several alternatives. The ones I am aware
of are Epubcheck_, Calibre_, FBreader_ (although it does not render the CSS),
and Bookworm_. For bookworm you can download the source from
http://code.google.com/p/threepress/ and run your own local server.
.. _api role: http://git.savannah.gnu.org/cgit/kenozooid.git/tree/doc/extapi.py
.. _xhtml to reST: http://docutils.sourceforge.net/sandbox/xhtml2rest/xhtml2rest.py
.. _Epubcheck: http://code.google.com/p/epubcheck/
.. _Calibre: http://calibre-ebook.com/
.. _FBreader: http://www.fbreader.org/
.. _Bookworm: http://bookworm.oreilly.com/

5
doc/markup/code.rst
View File

@@ -103,6 +103,9 @@ Includes
is absolute (starting with ``/``), it is relative to the top source
directory.
Tabs in the input are expanded if you give a ``tab-width`` option with the
desired tab width.
The directive also supports the ``linenos`` flag option to switch on line
numbers, and a ``language`` option to select a language different from the
current file's standard language. Example with options::
@@ -153,7 +156,7 @@ Includes
The ``pyobject``, ``lines``, ``start-after`` and ``end-before`` options,
as well as support for absolute filenames.
.. versionadded:: 1.0
The ``prepend`` and ``append`` options.
The ``prepend`` and ``append`` options, as well as ``tab-width``.
.. rubric:: Footnotes

23
doc/templating.rst
View File

@@ -74,8 +74,8 @@ render the block's content in the extended template -- unless you don't want
that content to show up.
Working the the builtin templates
---------------------------------
Working with the builtin templates
----------------------------------
The builtin **basic** theme supplies the templates that all builtin Sphinx
themes are based on. It has the following elements you can override or use:
@@ -139,23 +139,36 @@ The following blocks exist in the ``layout.html`` template:
The logo location within the sidebar. Override this if you want to place
some content at the top of the sidebar.
`footer`
The block for the footer div. If you want a custom footer or markup before
or after it, override this one.
The following four blocks are *only* used for pages that do not have assigned a
list of custom sidebars in the :confval:`html_sidebars` config value. Their use
is deprecated in favor of separate sidebar templates, which can be included via
:confval:`html_sidebars`.
`sidebartoc`
The table of contents within the sidebar.
.. deprecated:: 1.0
`sidebarrel`
The relation links (previous, next document) within the sidebar.
.. deprecated:: 1.0
`sidebarsourcelink`
The "Show source" link within the sidebar (normally only shown if this is
enabled by :confval:`html_show_sourcelink`).
.. deprecated:: 1.0
`sidebarsearch`
The search box within the sidebar. Override this if you want to place some
content at the bottom of the sidebar.
`footer`
The block for the footer div. If you want a custom footer or markup before
or after it, override this one.
.. deprecated:: 1.0
Configuration Variables

BIN
doc/themes/agogo.png vendored
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 36 KiB

After

Width:  |  Height:  |  Size: 38 KiB

BIN
doc/themes/default.png vendored
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 52 KiB

After

Width:  |  Height:  |  Size: 56 KiB

BIN
doc/themes/fullsize/haiku.png vendored Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 102 KiB

BIN
doc/themes/fullsize/nature.png vendored Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 43 KiB

BIN
doc/themes/haiku.png vendored Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 53 KiB

BIN
doc/themes/nature.png vendored Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 41 KiB

BIN
doc/themes/scrolls.png vendored
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 39 KiB

After

Width:  |  Height:  |  Size: 43 KiB

BIN
doc/themes/sphinxdoc.png vendored
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 41 KiB

After

Width:  |  Height:  |  Size: 42 KiB

BIN
doc/themes/traditional.png vendored
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 45 KiB

After

Width:  |  Height:  |  Size: 45 KiB

38
doc/theming.rst
View File

@@ -65,9 +65,13 @@ Builtin themes
| | |
| *scrolls* | *agogo* |
+--------------------+--------------------+
| |traditional| | |
| |traditional| | |nature| |
| | |
| *traditional* | |
| *traditional* | *nature* |
+--------------------+--------------------+
| |haiku| | |
| | |
| *haiku* | |
+--------------------+--------------------+
.. |default| image:: themes/default.png
@@ -75,15 +79,17 @@ Builtin themes
.. |scrolls| image:: themes/scrolls.png
.. |agogo| image:: themes/agogo.png
.. |traditional| image:: themes/traditional.png
.. |nature| image:: themes/nature.png
.. |haiku| image:: themes/haiku.png
Sphinx comes with a selection of themes to choose from.
These themes are:
* **basic** -- This is a basically unstyled layout used as the base for the
*default* and *sphinxdoc* themes, and usable as the base for custom themes as
well. The HTML contains all important elements like sidebar and relation bar.
There is one option (which is inherited by *default* and *sphinxdoc*):
other themes, and usable as the base for custom themes as well. The HTML
contains all important elements like sidebar and relation bar. There is one
option (which is inherited by the other themes):
- **nosidebar** (true or false): Don't include the sidebar. Defaults to
false.
@@ -128,7 +134,7 @@ These themes are:
on the right side. There are currently no options beyond *nosidebar*.
* **scrolls** -- A more lightweight theme, based on `the Jinja documentation
<http://jinja.pocoo.org/documentation/2>`_. The following color options are
<http://jinja.pocoo.org/2/documentation/>`_. The following color options are
available:
- **headerbordercolor**
@@ -157,12 +163,26 @@ These themes are:
- **headerlinkcolor** (CSS color): Color for the backreference link in
headings.
* **nature** -- A greenish theme. There are currently no options beyond
*nosidebar*.
* **haiku** -- A theme without sidebar inspired by the `Haiku OS user guide
<http://www.haiku-os.org/docs/userguide/en/contents.html>`_. The following
options are supported:
- **full_logo** (true or false, default false): If this is true, the header
will only show the :confval:`html_logo`. Use this for large logos. If this
is false, the logo (if present) will be shown floating right, and the
documentation title will be put in the header.
- **textcolor**, **headingcolor**, **linkcolor**, **visitedlinkcolor**,
**hoverlinkcolor** (CSS colors): Colors for various body elements.
* **traditional** -- A theme resembling the old Python documentation. There are
currently no options beyond *nosidebar*.
* **epub** -- A theme for the epub formatter. There are currently no
options. This theme tries to reduce visual space which is a sparse
resource on ebook readers.
* **epub** -- A theme for the epub builder. There are currently no options.
This theme tries to save visual space which is a sparse resource on ebook
readers.
Creating themes

2
sphinx-autogen.py
View File

@@ -4,7 +4,7 @@
Sphinx - Python documentation toolchain
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
:copyright: 2007-2009 by Georg Brandl.
:copyright: 2007-2010 by Georg Brandl.
:license: BSD.
"""

2
sphinx-build.py
View File

@@ -4,7 +4,7 @@
Sphinx - Python documentation toolchain
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
:copyright: Copyright 2007-2009 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2010 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""

2
sphinx-quickstart.py
View File

@@ -4,7 +4,7 @@
Sphinx - Python documentation toolchain
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
:copyright: Copyright 2007-2009 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2010 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""

2
sphinx/__init__.py
View File

@@ -5,7 +5,7 @@
The Sphinx documentation toolchain.
:copyright: Copyright 2007-2009 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2010 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""

2
sphinx/addnodes.py
View File

@@ -5,7 +5,7 @@
Additional docutils nodes.
:copyright: Copyright 2007-2009 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2010 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""

2
sphinx/application.py
View File

@@ -7,7 +7,7 @@
Gracefully adapted from the TextPress system by Armin.
:copyright: Copyright 2007-2009 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2010 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""

8
sphinx/builders/__init__.py
View File

@@ -5,7 +5,7 @@
Builder superclass for all builders.
:copyright: Copyright 2007-2009 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2010 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
@@ -16,7 +16,7 @@ from os import path
from docutils import nodes
from sphinx import package_dir, locale
from sphinx.util import SEP, relative_uri
from sphinx.util import SEP, ENOENT, relative_uri
from sphinx.environment import BuildEnvironment
from sphinx.util.console import bold, purple, darkgreen, term_width_line
@@ -186,7 +186,7 @@ class Builder(object):
if self.translator is None:
self.translator = trans
else:
self.translator._catalog.update(trans.catalog)
self.translator._catalog.update(trans._catalog)
except Exception:
# Language couldn't be found in the specified path
pass
@@ -210,7 +210,7 @@ class Builder(object):
path.join(self.doctreedir, ENV_PICKLE_FILENAME))
self.info('done')
except Exception, err:
if type(err) is IOError and err.errno == 2:
if type(err) is IOError and err.errno == ENOENT:
self.info('not found')
else:
self.info('failed: %s' % err)

7
sphinx/builders/changes.py
View File

@@ -5,7 +5,7 @@
Changelog builder.
:copyright: Copyright 2007-2009 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2010 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
@@ -139,11 +139,10 @@ class ChangesBuilder(Builder):
self.theme.get_options({}).iteritems())
copy_static_entry(path.join(package_dir, 'themes', 'default',
'static', 'default.css_t'),
path.join(self.outdir, 'default.css_t'),
self, themectx)
self.outdir, self, themectx)
copy_static_entry(path.join(package_dir, 'themes', 'basic',
'static', 'basic.css'),
path.join(self.outdir, 'basic.css'), self)
self.outdir, self)
def hl(self, text, version):
text = escape(text)

2
sphinx/builders/devhelp.py
View File

@@ -7,7 +7,7 @@
.. _Devhelp: http://live.gnome.org/devhelp
:copyright: Copyright 2007-2009 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2010 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""

80
sphinx/builders/epub.py
View File

@@ -6,25 +6,22 @@
Build epub files.
Originally derived from qthelp.py.
:copyright: Copyright 2007-2009 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2010 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
import os
import re
import codecs
from os import path
import zipfile
from docutils import nodes
from sphinx import addnodes
from sphinx.builders.html import StandaloneHTMLBuilder
# (Fragment) templates from which the metainfo files
# content.opf, toc.ncx, mimetype, and META-INF/container.xml
# are created.
# (Fragment) templates from which the metainfo files content.opf, toc.ncx,
# mimetype, and META-INF/container.xml are created.
_mimetype_template = 'application/epub+zip' # no EOL!
@@ -118,9 +115,10 @@ _media_types = {
class EpubBuilder(StandaloneHTMLBuilder):
"""Builder that outputs epub files.
It creates the metainfo files
container.opf, toc.ncx, mimetype, and META-INF/container.xml.
Afterwards, all necessary files are zipped to an epub file.
It creates the metainfo files container.opf, toc.ncx, mimetype, and
META-INF/container.xml. Afterwards, all necessary files are zipped to an
epub file.
"""
name = 'epub'
@@ -136,18 +134,20 @@ class EpubBuilder(StandaloneHTMLBuilder):
def init(self):
StandaloneHTMLBuilder.init(self)
# the output files for HTML help must be .html only
# the output files for epub must be .html only
self.out_suffix = '.html'
self.playorder = 0
def get_theme_config(self):
return self.config.epub_theme, {}
# generic support functions
def make_id(self, name):
"""Replace all characters not allowed for (X)HTML ids"""
"""Replace all characters not allowed for (X)HTML ids."""
return name.replace('/', '_')
def esc(self, name):
"""Replace all characters not allowed in text an attribute values"""
"""Replace all characters not allowed in text an attribute values."""
# Like cgi.escape, but also replace apostrophe
name = name.replace('&', '&amp;')
name = name.replace('<', '&lt;')
@@ -157,17 +157,22 @@ class EpubBuilder(StandaloneHTMLBuilder):
return name
def collapse_text(self, doctree, result):
"""Remove all HTML markup and return only the text nodes"""
"""Remove all HTML markup and return only the text nodes."""
for c in doctree.children:
if isinstance(c, nodes.Text):
result.append(c.data)
try:
# docutils 0.4 and 0.5: Text is a UserString subclass
result.append(c.data)
except AttributeError:
# docutils 0.6: Text is a unicode subclass
result.append(c)
else:
result = self.collapse_text(c, result)
return result
def get_refnodes(self, doctree, result):
"""Collect section titles, their depth in the toc and the refuri"""
# XXX: is there a betterr way than checking the attribute
"""Collect section titles, their depth in the toc and the refuri."""
# XXX: is there a better way than checking the attribute
# toctree-l[1-6] on the parent node?
if isinstance(doctree, nodes.reference):
classes = doctree.parent.attributes['classes']
@@ -187,7 +192,8 @@ class EpubBuilder(StandaloneHTMLBuilder):
def get_toc(self):
"""Get the total table of contents, containg the master_doc
and pre and post files not managed by sphinx"""
and pre and post files not managed by sphinx.
"""
doctree = self.env.get_and_resolve_doctree(self.config.master_doc,
self, prune_toctrees=False)
self.refnodes = self.get_refnodes(doctree, [])
@@ -215,7 +221,7 @@ class EpubBuilder(StandaloneHTMLBuilder):
# Finish by building the epub file
def handle_finish(self):
"""Create the metainfo files and finally the epub"""
"""Create the metainfo files and finally the epub."""
self.get_toc()
self.build_mimetype(self.outdir, 'mimetype')
self.build_container(self.outdir, 'META-INF/container.xml')
@@ -224,7 +230,7 @@ class EpubBuilder(StandaloneHTMLBuilder):
self.build_epub(self.outdir, self.config.epub_basename + '.epub')
def build_mimetype(self, outdir, outname):
"""Write the metainfo file mimetype"""
"""Write the metainfo file mimetype."""
self.info('writing %s file...' % outname)
f = codecs.open(path.join(outdir, outname), 'w', 'utf-8')
try:
@@ -233,7 +239,7 @@ class EpubBuilder(StandaloneHTMLBuilder):
f.close()
def build_container(self, outdir, outname):
"""Write the metainfo file META-INF/cointainer.xml"""
"""Write the metainfo file META-INF/cointainer.xml."""
self.info('writing %s file...' % outname)
fn = path.join(outdir, outname)
try:
@@ -249,7 +255,8 @@ class EpubBuilder(StandaloneHTMLBuilder):
def content_metadata(self, files, spine):
"""Create a dictionary with all metadata for the content.opf
file properly escaped"""
file properly escaped.
"""
metadata = {}
metadata['title'] = self.esc(self.config.epub_title)
metadata['author'] = self.esc(self.config.epub_author)
@@ -264,9 +271,9 @@ class EpubBuilder(StandaloneHTMLBuilder):
return metadata
def build_content(self, outdir, outname):
"""Write the metainfo file content.opf
It contains bibliographic data, a file list and
the spine (the reading order)."""
"""Write the metainfo file content.opf It contains bibliographic data,
a file list and the spine (the reading order).
"""
self.info('writing %s file...' % outname)
# files
@@ -318,7 +325,7 @@ class EpubBuilder(StandaloneHTMLBuilder):
f.close()
def new_navpoint(self, node, level, incr=True):
"""Create a new entry in the toc from the node at given level"""
"""Create a new entry in the toc from the node at given level."""
# XXX Modifies the node
if incr:
self.playorder += 1
@@ -328,16 +335,19 @@ class EpubBuilder(StandaloneHTMLBuilder):
return _navpoint_template % node
def insert_subnav(self, node, subnav):
"""Insert nested navpoints for given node
The node and subnav are already rendered to text"""
"""Insert nested navpoints for given node.
The node and subnav are already rendered to text.
"""
nlist = node.split('\n')
nlist.insert(-1, subnav)
return '\n'.join(nlist)
def build_navpoints(self, nodes):
"""Create the toc navigation structure
"""Create the toc navigation structure.
Subelements of a node are nested inside the navpoint.
For nested nodes the parent node is reinserted in the subnav."""
For nested nodes the parent node is reinserted in the subnav.
"""
navstack = []
navlist = []
level = 1
@@ -373,7 +383,8 @@ class EpubBuilder(StandaloneHTMLBuilder):
def toc_metadata(self, level, navpoints):
"""Create a dictionary with all metadata for the toc.ncx
file properly escaped"""
file properly escaped.
"""
metadata = {}
metadata['uid'] = self.config.epub_uid
metadata['title'] = self.config.epub_title
@@ -382,7 +393,7 @@ class EpubBuilder(StandaloneHTMLBuilder):
return metadata
def build_toc(self, outdir, outname):
"""Write the metainfo file toc.ncx"""
"""Write the metainfo file toc.ncx."""
self.info('writing %s file...' % outname)
navpoints = self.build_navpoints(self.refnodes)
@@ -394,9 +405,11 @@ class EpubBuilder(StandaloneHTMLBuilder):
f.close()
def build_epub(self, outdir, outname):
"""Write the epub file
"""Write the epub file.
It is a zip file with the mimetype file stored uncompressed
as the first entry."""
as the first entry.
"""
self.info('writing %s file...' % outname)
projectfiles = ['META-INF/container.xml', 'content.opf', 'toc.ncx'] \
+ self.files
@@ -407,4 +420,3 @@ class EpubBuilder(StandaloneHTMLBuilder):
for file in projectfiles:
epub.write(path.join(outdir, file), file, zipfile.ZIP_DEFLATED)
epub.close()

116
sphinx/builders/html.py
View File

@@ -5,7 +5,7 @@
Several HTML builders.
:copyright: Copyright 2007-2009 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2010 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
@@ -22,14 +22,14 @@ except ImportError:
from docutils import nodes
from docutils.io import DocTreeInput, StringOutput
from docutils.core import Publisher, publish_parts
from docutils.core import Publisher
from docutils.utils import new_document
from docutils.frontend import OptionParser
from docutils.readers.doctree import Reader as DoctreeReader
from sphinx import package_dir, __version__
from sphinx.util import SEP, os_path, relative_uri, ensuredir, \
movefile, ustrftime, copy_static_entry, copyfile
from sphinx.util import SEP, os_path, relative_uri, ensuredir, patmatch, \
movefile, ustrftime, copy_static_entry, copyfile, compile_matchers, any
from sphinx.errors import SphinxError
from sphinx.search import js_index
from sphinx.theming import Theme
@@ -74,6 +74,9 @@ class StandaloneHTMLBuilder(Builder):
# Dito for this one.
css_files = []
default_sidebars = ['localtoc.html', 'relations.html',
'sourcelink.html', 'searchbox.html']
# cached publisher object for snippets
_publisher = None
@@ -101,9 +104,14 @@ class StandaloneHTMLBuilder(Builder):
if path.isfile(jsfile):
self.script_files.append('_static/translations.js')
def get_theme_config(self):
return self.config.html_theme, self.config.html_theme_options
def init_templates(self):
Theme.init_themes(self)
self.theme = Theme(self.config.html_theme)
themename, themeoptions = self.get_theme_config()
self.theme = Theme(themename)
self.theme_options = themeoptions.copy()
self.create_template_bridge()
self.templates.init(self, self.theme)
@@ -167,8 +175,7 @@ class StandaloneHTMLBuilder(Builder):
if docname not in self.env.all_docs:
yield docname
continue
targetname = self.env.doc2path(docname, self.outdir,
self.out_suffix)
targetname = self.get_outfilename(docname)
try:
targetmtime = path.getmtime(targetname)
except Exception:
@@ -279,8 +286,7 @@ class StandaloneHTMLBuilder(Builder):
if self.theme:
self.globalcontext.update(
('theme_' + key, val) for (key, val) in
self.theme.get_options(
self.config.html_theme_options).iteritems())
self.theme.get_options(self.theme_options).iteritems())
self.globalcontext.update(self.config.html_context)
def get_doc_context(self, docname, body, metatags):
@@ -435,6 +441,10 @@ class StandaloneHTMLBuilder(Builder):
else:
stripped = ''
# we stripped the whole module name
if not mn:
continue
if fl != mn[0].lower() and mn[0] != '_':
# heading
letter = mn[0].upper()
@@ -549,30 +559,39 @@ class StandaloneHTMLBuilder(Builder):
if path.isfile(jsfile):
copyfile(jsfile, path.join(self.outdir, '_static',
'translations.js'))
# then, copy over all user-supplied static files
# then, copy over theme-supplied static files
if self.theme:
staticdirnames = [path.join(themepath, 'static')
for themepath in self.theme.get_dirchain()[::-1]]
else:
staticdirnames = []
staticdirnames += [path.join(self.confdir, spath)
for spath in self.config.html_static_path]
for staticdirname in staticdirnames:
if not path.isdir(staticdirname):
self.warn('static directory %r does not exist' % staticdirname)
themeentries = [path.join(themepath, 'static')
for themepath in self.theme.get_dirchain()[::-1]]
for entry in themeentries:
copy_static_entry(entry, path.join(self.outdir, '_static'),
self, self.globalcontext)
# then, copy over all user-supplied static files
staticentries = [path.join(self.confdir, spath)
for spath in self.config.html_static_path]
matchers = compile_matchers(
self.config.exclude_patterns +
['**/' + d for d in self.config.exclude_dirnames]
)
for entry in staticentries:
if not path.exists(entry):
self.warn('html_static_path entry %r does not exist' % entry)
continue
for filename in os.listdir(staticdirname):
if filename.startswith('.'):
continue
fullname = path.join(staticdirname, filename)
targetname = path.join(self.outdir, '_static', filename)
copy_static_entry(fullname, targetname, self,
self.globalcontext)
# last, copy logo file (handled differently)
copy_static_entry(entry, path.join(self.outdir, '_static'), self,
self.globalcontext, exclude_matchers=matchers)
# copy logo and favicon files if not already in static path
if self.config.html_logo:
logobase = path.basename(self.config.html_logo)
copyfile(path.join(self.confdir, self.config.html_logo),
path.join(self.outdir, '_static', logobase))
logotarget = path.join(self.outdir, '_static', logobase)
if not path.isfile(logotarget):
copyfile(path.join(self.confdir, self.config.html_logo),
logotarget)
if self.config.html_favicon:
iconbase = path.basename(self.config.html_favicon)
icontarget = path.join(self.outdir, '_static', iconbase)
if not path.isfile(icontarget):
copyfile(path.join(self.confdir, self.config.html_favicon),
icontarget)
# write build info file
fp = open(path.join(self.outdir, '.buildinfo'), 'w')
@@ -646,6 +665,36 @@ class StandaloneHTMLBuilder(Builder):
def get_outfilename(self, pagename):
return path.join(self.outdir, os_path(pagename) + self.out_suffix)
def add_sidebars(self, pagename, ctx):
def has_wildcard(pattern):
return any(char in pattern for char in '*?[')
sidebars = None
matched = None
customsidebar = None
for pattern, patsidebars in self.config.html_sidebars.iteritems():
if patmatch(pagename, pattern):
if matched:
if has_wildcard(pattern):
# warn if both patterns contain wildcards
if has_wildcard(matched):
self.warn('page %s matches two patterns in '
'html_sidebars: %r and %r' %
(pagename, matched, pattern))
# else the already matched pattern is more specific
# than the present one, because it contains no wildcard
continue
matched = pattern
sidebars = patsidebars
if sidebars is None:
# keep defaults
pass
elif isinstance(sidebars, basestring):
# 0.x compatible mode: insert custom sidebar before searchbox
customsidebar = sidebars
sidebars = None
ctx['sidebars'] = sidebars
ctx['customsidebar'] = customsidebar
# --------- these are overwritten by the serialization builder
def get_target_uri(self, docname, typ=None):
@@ -661,12 +710,13 @@ class StandaloneHTMLBuilder(Builder):
baseuri=self.get_target_uri(pagename)):
if not resource:
otheruri = self.get_target_uri(otheruri)
return relative_uri(baseuri, otheruri)
uri = relative_uri(baseuri, otheruri) or '#'
return uri
ctx['pathto'] = pathto
ctx['hasdoc'] = lambda name: name in self.env.all_docs
ctx['customsidebar'] = self.config.html_sidebars.get(pagename)
ctx['encoding'] = encoding = self.config.html_output_encoding
ctx['toctree'] = lambda **kw: self._get_local_toctree(pagename, **kw)
self.add_sidebars(pagename, ctx)
ctx.update(addctx)
self.app.emit('html-page-context', pagename, templatename,
@@ -781,9 +831,7 @@ class SerializingHTMLBuilder(StandaloneHTMLBuilder):
def handle_page(self, pagename, ctx, templatename='page.html',
outfilename=None, event_arg=None):
ctx['current_page_name'] = pagename
sidebarfile = self.config.html_sidebars.get(pagename)
if sidebarfile:
ctx['customsidebar'] = sidebarfile
self.add_sidebars(pagename, ctx)
if not outfilename:
outfilename = path.join(self.outdir,

2
sphinx/builders/htmlhelp.py
View File

@@ -6,7 +6,7 @@
Build HTML help support files.
Parts adapted from Python's Doc/tools/prechm.py.
:copyright: Copyright 2007-2009 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2010 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""

2
sphinx/builders/latex.py
View File

@@ -5,7 +5,7 @@
LaTeX builder.
:copyright: Copyright 2007-2009 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2010 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""

4
sphinx/builders/linkcheck.py
View File

@@ -5,7 +5,7 @@
The CheckExternalLinksBuilder class.
:copyright: Copyright 2007-2009 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2010 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
@@ -70,6 +70,8 @@ class CheckExternalLinksBuilder(Builder):
lineno = node.line
if uri[0:5] == 'http:' or uri[0:6] == 'https:':
if lineno:
self.info('(line %3d) ' % lineno, nonl=1)
self.info(uri, nonl=1)
if uri in self.broken:

2
sphinx/builders/qthelp.py
View File

@@ -5,7 +5,7 @@
Build input files for the Qt collection generator.
:copyright: Copyright 2007-2009 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2010 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""

2
sphinx/builders/text.py
View File

@@ -5,7 +5,7 @@
Plain-text Sphinx builder.
:copyright: Copyright 2007-2009 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2010 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""

6
sphinx/cmdline.py
View File

@@ -5,7 +5,7 @@
sphinx-build command-line handling.
:copyright: Copyright 2007-2009 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2010 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
@@ -96,7 +96,6 @@ def main(argv):
error = sys.stderr
warnfile = None
confoverrides = {}
htmlcontext = {}
tags = []
doctreedir = path.join(outdir, '.doctrees')
for opt, val in opts:
@@ -142,7 +141,7 @@ def main(argv):
val = int(val)
except ValueError:
pass
htmlcontext[key] = val
confoverrides['html_context.%s' % key] = val
elif opt == '-N':
nocolor()
elif opt == '-E':
@@ -158,7 +157,6 @@ def main(argv):
warnfile = val
elif opt == '-P':
use_pdb = True
confoverrides['html_context'] = htmlcontext
if warning and warnfile:
warnfp = open(warnfile, 'w')

34
sphinx/config.py
View File

@@ -5,7 +5,7 @@
Build configuration file handling.
:copyright: Copyright 2007-2009 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2010 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
@@ -38,8 +38,9 @@ class Config(object):
master_doc = ('contents', 'env'),
source_suffix = ('.rst', 'env'),
source_encoding = ('utf-8-sig', 'env'),
exclude_patterns = ([], 'env'),
# the next three are all deprecated now
unused_docs = ([], 'env'),
exclude_dirs = ([], 'env'),
exclude_trees = ([], 'env'),
exclude_dirnames = ([], 'env'),
default_role = (None, 'env'),
@@ -97,6 +98,21 @@ class Config(object):
# Devhelp only options
devhelp_basename = (lambda self: make_filename(self.project), None),
# Epub options
epub_basename = (lambda self: make_filename(self.project), None),
epub_theme = ('epub', 'html'),
epub_title = (lambda self: self.html_title, 'html'),
epub_author = ('unknown', 'html'),
epub_language = (lambda self: self.language or 'en', 'html'),
epub_publisher = ('unknown', 'html'),
epub_copyright = (lambda self: self.copyright, 'html'),
epub_identifier = ('unknown', 'html'),
epub_scheme = ('unknown', 'html'),
epub_uid = ('unknown', 'env'),
epub_pre_files = ([], 'env'),
epub_post_files = ([], 'env'),
epub_exclude_files = ([], 'env'),
# LaTeX options
latex_documents = ([], None),
latex_logo = (None, None),
@@ -112,20 +128,6 @@ class Config(object):
latex_docclass = ({}, None),
# now deprecated - use latex_elements
latex_preamble = ('', None),
# Epub options
epub_basename = (lambda self: make_filename(self.project), None),
epub_title = (lambda self: self.html_title, 'html'),
epub_author = ('unknown', 'html'),
epub_language = (lambda self: self.language or 'en', 'html'),
epub_publisher = ('unknown', 'html'),
epub_copyright = (lambda self: self.copyright, 'html'),
epub_identifier = ('unknown', 'html'),
epub_scheme = ('unknown', 'html'),
epub_uid = ('unknown', 'env'),
epub_pre_files = ([], 'env'),
epub_post_files = ([], 'env'),
epub_exclude_files = ([], 'env'),
)
def __init__(self, dirname, filename, overrides, tags):

2
sphinx/directives/__init__.py
View File

@@ -5,7 +5,7 @@
Handlers for additional ReST directives.
:copyright: Copyright 2007-2009 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2010 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""

5
sphinx/directives/code.py
View File

@@ -3,7 +3,7 @@
sphinx.directives.code
~~~~~~~~~~~~~~~~~~~~~~
:copyright: Copyright 2007-2009 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2010 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
@@ -81,6 +81,7 @@ class LiteralInclude(Directive):
final_argument_whitespace = False
option_spec = {
'linenos': directives.flag,
'tab-width': int,
'language': directives.unchanged_required,
'encoding': directives.encoding,
'pyobject': directives.unchanged_required,
@@ -174,6 +175,8 @@ class LiteralInclude(Directive):
lines.append(append + '\n')
text = ''.join(lines)
if self.options.get('tab-width'):
text = text.expandtabs(self.options['tab-width'])
retnode = nodes.literal_block(text, text, source=fn)
retnode.line = 1
if self.options.get('language', ''):

2
sphinx/directives/desc.py
View File

@@ -3,7 +3,7 @@
sphinx.directives.desc
~~~~~~~~~~~~~~~~~~~~~~
:copyright: Copyright 2007-2009 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2010 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""

10
sphinx/directives/other.py
View File

@@ -3,7 +3,7 @@
sphinx.directives.other
~~~~~~~~~~~~~~~~~~~~~~~
:copyright: Copyright 2007-2009 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2010 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
@@ -100,7 +100,9 @@ class TocTree(Directive):
subnode['hidden'] = 'hidden' in self.options
subnode['numbered'] = 'numbered' in self.options
subnode['titlesonly'] = 'titlesonly' in self.options
ret.append(subnode)
wrappernode = nodes.compound(classes=['toctree-wrapper'])
wrappernode.append(subnode)
ret.append(wrappernode)
return ret
@@ -238,7 +240,7 @@ class Index(Directive):
option_spec = {}
indextypes = [
'single', 'pair', 'triple',
'single', 'pair', 'double', 'triple',
]
def run(self):
@@ -262,6 +264,8 @@ class Index(Directive):
for type in self.indextypes:
if entry.startswith(type+':'):
value = entry[len(type)+1:].strip()
if type == 'double':
type = 'pair'
ne.append((type, value, targetid, value))
break
# shorthand notation for single entries

48
sphinx/environment.py
View File

@@ -5,7 +5,7 @@
Global creation environment.
:copyright: Copyright 2007-2009 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2010 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
@@ -35,7 +35,7 @@ from docutils.transforms.parts import ContentsFilter
from sphinx import addnodes
from sphinx.util import movefile, get_matching_docs, SEP, ustrftime, \
docname_join, FilenameUniqDict, url_re
docname_join, FilenameUniqDict, url_re, clean_astext, compile_matchers
from sphinx.errors import SphinxError
from sphinx.directives import additional_xref_types
@@ -51,7 +51,7 @@ default_settings = {
# This is increased every time an environment attribute is added
# or changed to properly invalidate pickle files.
ENV_VERSION = 30
ENV_VERSION = 31
default_substitutions = set([
@@ -393,14 +393,15 @@ class BuildEnvironment:
"""
Find all source files in the source dir and put them in self.found_docs.
"""
exclude_dirs = [d.replace(SEP, path.sep) for d in config.exclude_dirs]
exclude_trees = [d.replace(SEP, path.sep) for d in config.exclude_trees]
matchers = compile_matchers(
config.exclude_patterns[:] +
config.exclude_trees +
[d + config.source_suffix for d in config.unused_docs] +
['**/' + d for d in config.exclude_dirnames] +
['**/_sources']
)
self.found_docs = set(get_matching_docs(
self.srcdir, config.source_suffix,
exclude_docs=set(config.unused_docs),
exclude_dirs=exclude_dirs,
exclude_trees=exclude_trees,
exclude_dirnames=['_sources'] + config.exclude_dirnames))
self.srcdir, config.source_suffix, exclude_matchers=matchers))
def get_outdated_files(self, config_changed):
"""
@@ -821,11 +822,11 @@ class BuildEnvironment:
node.line)
self.anonlabels[name] = docname, labelid
if node.tagname == 'section':
sectname = node[0].astext() # node[0] == title node
sectname = clean_astext(node[0]) # node[0] == title node
elif node.tagname == 'figure':
for n in node:
if n.tagname == 'caption':
sectname = n.astext()
sectname = clean_astext(n)
break
else:
continue
@@ -931,7 +932,7 @@ class BuildEnvironment:
"""Return a TOC nodetree -- for use on the same page only!"""
toc = self.tocs[docname].deepcopy()
for node in toc.traverse(nodes.reference):
node['refuri'] = node['anchorname']
node['refuri'] = node['anchorname'] or '#'
return toc
def get_toctree_for(self, docname, builder, collapse):
@@ -1075,7 +1076,7 @@ class BuildEnvironment:
# toctree originates
ref = toctreenode['parent']
if not title:
title = self.titles[ref].astext()
title = clean_astext(self.titles[ref])
reference = nodes.reference('', '',
refuri=ref,
anchorname='',
@@ -1180,7 +1181,7 @@ class BuildEnvironment:
docname, labelid = self.anonlabels.get(target, ('',''))
sectname = node.astext()
if not docname:
self.warn(fromdocname, 'undefined label: %s' %
self.warn(node['refdoc'], 'undefined label: %s' %
target, node.line)
else:
# reference to the named label; the final node will
@@ -1189,7 +1190,7 @@ class BuildEnvironment:
('','',''))
if not docname:
self.warn(
fromdocname,
node['refdoc'],
'undefined label: %s' % target + ' -- if you '
'don\'t give a link caption the label must '
'precede a section header.', node.line)
@@ -1215,17 +1216,17 @@ class BuildEnvironment:
elif typ == 'doc':
# directly reference to document by source name;
# can be absolute or relative
docname = docname_join(fromdocname, target)
docname = docname_join(node['refdoc'], target)
if docname not in self.all_docs:
self.warn(fromdocname, 'unknown document: %s' % docname,
node.line)
self.warn(node['refdoc'],
'unknown document: %s' % docname, node.line)
newnode = contnode
else:
if node['refcaption']:
# reference with explicit title
caption = node.astext()
else:
caption = self.titles[docname].astext()
caption = clean_astext(self.titles[docname])
innernode = nodes.emphasis(caption, caption)
newnode = nodes.reference('', '')
newnode['refuri'] = builder.get_relative_uri(
@@ -1235,7 +1236,8 @@ class BuildEnvironment:
# keywords are referenced by named labels
docname, labelid, _ = self.labels.get(target, ('','',''))
if not docname:
#self.warn(fromdocname, 'unknown keyword: %s' % target)
#self.warn(node['refdoc'],
# 'unknown keyword: %s' % target)
newnode = contnode
else:
newnode = nodes.reference('', '')
@@ -1264,11 +1266,11 @@ class BuildEnvironment:
('', ''))
if not docname:
if typ == 'term':
self.warn(fromdocname,
self.warn(node['refdoc'],
'term not in glossary: %s' % target,
node.line)
elif typ == 'citation':
self.warn(fromdocname,
self.warn(node['refdoc'],
'citation not found: %s' % target,
node.line)
newnode = contnode

2
sphinx/errors.py
View File

@@ -6,7 +6,7 @@
Contains SphinxError and a few subclasses (in an extra module to avoid
circular import problems).
:copyright: Copyright 2007-2009 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2010 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""

2
sphinx/ext/__init__.py
View File

@@ -5,6 +5,6 @@
Contains Sphinx features not activated by default.
:copyright: Copyright 2007-2009 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2010 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""

53
sphinx/ext/autodoc.py
View File

@@ -7,7 +7,7 @@
the doctree, thus avoiding duplication between docstrings and documentation
for those who like elaborate docstrings.
:copyright: Copyright 2007-2009 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2010 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
@@ -72,6 +72,7 @@ class Options(dict):
ALL = object()
INSTANCEATTR = object()
def members_option(arg):
"""Used to convert the :members: option to auto directives."""
@@ -474,19 +475,30 @@ class Documenter(object):
self.directive.warn('missing attribute %s in object %s'
% (mname, self.fullname))
return False, ret
elif self.options.inherited_members:
if self.options.inherited_members:
# safe_getmembers() uses dir() which pulls in members from all
# base classes
return False, safe_getmembers(self.object)
members = safe_getmembers(self.object)
else:
# __dict__ contains only the members directly defined in
# the class (but get them via getattr anyway, to e.g. get
# unbound method objects instead of function objects);
# using keys() because apparently there are objects for which
# __dict__ changes while getting attributes
return False, sorted([
(mname, self.get_attr(self.object, mname, None))
for mname in self.get_attr(self.object, '__dict__').keys()])
obj_dict = self.get_attr(self.object, '__dict__')
members = [(mname, self.get_attr(self.object, mname, None))
for mname in obj_dict.keys()]
membernames = set(m[0] for m in members)
# add instance attributes from the analyzer
if self.analyzer:
attr_docs = self.analyzer.find_attr_docs()
namespace = '.'.join(self.objpath)
for item in attr_docs.iteritems():
if item[0][0] == namespace:
if item[0][1] not in membernames:
members.append((item[0][1], INSTANCEATTR))
return False, sorted(members)
def filter_members(self, members, want_all):
"""
@@ -1036,6 +1048,34 @@ class AttributeDocumenter(ClassLevelDocumenter):
pass
class InstanceAttributeDocumenter(AttributeDocumenter):
"""
Specialized Documenter subclass for attributes that cannot be imported
because they are instance attributes (e.g. assigned in __init__).
"""
objtype = 'instanceattribute'
directivetype = 'attribute'
member_order = 60
# must be higher than AttributeDocumenter
priority = 11
@classmethod
def can_document_member(cls, member, membername, isattr, parent):
"""This documents only INSTANCEATTR members."""
return isattr and (member is INSTANCEATTR)
def import_object(self):
"""Never import anything."""
# disguise as an attribute
self.objtype = 'attribute'
return True
def add_content(self, more_content, no_docstring=False):
"""Never try to get a docstring from the object."""
AttributeDocumenter.add_content(self, more_content, no_docstring=True)
class AutoDirective(Directive):
"""
The AutoDirective class is used for all autodoc directives. It dispatches
@@ -1132,6 +1172,7 @@ def setup(app):
app.add_autodocumenter(FunctionDocumenter)
app.add_autodocumenter(MethodDocumenter)
app.add_autodocumenter(AttributeDocumenter)
app.add_autodocumenter(InstanceAttributeDocumenter)
app.add_config_value('autoclass_content', 'class', True)
app.add_config_value('autodoc_member_order', 'alphabetic', True)

2
sphinx/ext/autosummary/__init__.py
View File

@@ -49,7 +49,7 @@
resolved to a Python object, and otherwise it becomes simple emphasis.
This can be used as the default role to make links 'smart'.
:copyright: Copyright 2007-2009 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2010 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""

2
sphinx/ext/autosummary/generate.py
View File

@@ -14,7 +14,7 @@
generate:
sphinx-autogen source/*.rst source/generated
:copyright: Copyright 2007-2009 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2010 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
import os

2
sphinx/ext/coverage.py
View File

@@ -6,7 +6,7 @@
Check Python modules and C API for coverage. Mostly written by Josip
Dzolonga for the Google Highly Open Participation contest.
:copyright: Copyright 2007-2009 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2010 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""

9
sphinx/ext/doctest.py
View File

@@ -6,7 +6,7 @@
Mimic doctest by automatically executing code snippets and checking
their results.
:copyright: Copyright 2007-2009 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2010 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
@@ -355,7 +355,14 @@ Doctest summary
options = code[1] and code[1].options or {}
# disable <BLANKLINE> processing as it is not needed
options[doctest.DONT_ACCEPT_BLANKLINE] = True
# find out if we're testing an exception
m = parser._EXCEPTION_RE.match(output)
if m:
exc_msg = m.group('msg')
else:
exc_msg = None
example = doctest.Example(code[0].code, output,
exc_msg=exc_msg,
lineno=code[0].lineno,
options=options)
test = doctest.DocTest([example], {}, group.name,

21
sphinx/ext/extlinks.py
View File

@@ -8,10 +8,10 @@
This adds a new config value called ``extlinks`` that is created like this::
extlinks = {'exmpl': ('http://example.com/', prefix), ...}
extlinks = {'exmpl': ('http://example.com/%s.html', prefix), ...}
Now you can use e.g. :exmpl:`foo` in your documents. This will create a
link to ``http://example.com/foo``. The link caption depends on the
link to ``http://example.com/foo.html``. The link caption depends on the
*prefix* value given:
- If it is ``None``, the caption will be the full URL.
@@ -20,7 +20,7 @@
You can also give an explicit caption, e.g. :exmpl:`Foo <foo>`.
:copyright: Copyright 2007-2009 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2010 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
@@ -32,15 +32,20 @@ from sphinx.util import split_explicit_title
def make_link_role(base_url, prefix):
def role(typ, rawtext, text, lineno, inliner, options={}, content=[]):
text = utils.unescape(text)
has_explicit_title, title, url = split_explicit_title(text)
# NOTE: not using urlparse.urljoin() here, to allow something like
# base_url = 'bugs.python.org/issue' and url = '1024'
full_url = base_url + url
has_explicit_title, title, part = split_explicit_title(text)
try:
full_url = base_url % part
except (TypeError, ValueError):
env = inliner.document.settings.env
env.warn(env.docname, 'unable to expand %s extlink with base '
'URL %r, please make sure the base contains \'%%s\' '
'exactly once' % (typ, base_url))
full_url = base_url + part
if not has_explicit_title:
if prefix is None:
title = full_url
else:
title = prefix + url
title = prefix + part
pnode = nodes.reference(title, title, refuri=full_url)
return [pnode], []
return role

100
sphinx/ext/graphviz.py
View File

@@ -6,13 +6,14 @@
Allow graphviz-formatted graphs to be included in Sphinx-generated
documents inline.
:copyright: Copyright 2007-2009 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2010 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
import re
import posixpath
from os import path
from math import ceil
from subprocess import Popen, PIPE
try:
from hashlib import sha1 as sha
@@ -20,13 +21,15 @@ except ImportError:
from sha import sha
from docutils import nodes
from docutils.parsers.rst import directives
from sphinx.errors import SphinxError
from sphinx.util import ensuredir
from sphinx.util import ensuredir, ENOENT
from sphinx.util.compat import Directive
mapname_re = re.compile(r'<map id="(.*?)"')
svg_dim_re = re.compile(r'<svg\swidth="(\d+)pt"\sheight="(\d+)pt"', re.M)
class GraphvizError(SphinxError):
@@ -45,7 +48,9 @@ class Graphviz(Directive):
required_arguments = 0
optional_arguments = 0
final_argument_whitespace = False
option_spec = {}
option_spec = {
'alt': directives.unchanged,
}
def run(self):
dotcode = '\n'.join(self.content)
@@ -56,6 +61,8 @@ class Graphviz(Directive):
node = graphviz()
node['code'] = dotcode
node['options'] = []
if 'alt' in self.options:
node['alt'] = self.options['alt']
return [node]
@@ -67,13 +74,17 @@ class GraphvizSimple(Directive):
required_arguments = 1
optional_arguments = 0
final_argument_whitespace = False
option_spec = {}
option_spec = {
'alt': directives.unchanged,
}
def run(self):
node = graphviz()
node['code'] = '%s %s {\n%s\n}\n' % \
(self.name, self.arguments[0], '\n'.join(self.content))
node['options'] = []
if 'alt' in self.options:
node['alt'] = self.options['alt']
return [node]
@@ -111,7 +122,7 @@ def render_dot(self, code, options, format, prefix='graphviz'):
try:
p = Popen(dot_args, stdout=PIPE, stdin=PIPE, stderr=PIPE)
except OSError, err:
if err.errno != 2: # No such file or directory
if err.errno != ENOENT: # No such file or directory
raise
self.builder.warn('dot command %r cannot be run (needed for graphviz '
'output), check the graphviz_dot setting' %
@@ -128,9 +139,45 @@ def render_dot(self, code, options, format, prefix='graphviz'):
return relfn, outfn
def render_dot_html(self, node, code, options, prefix='graphviz', imgcls=None):
def get_svg_tag(svgref, svgfile, imgcls=None):
# Webkit can't figure out svg dimensions when using object tag
# so we need to get it from the svg file
fp = open(svgfile, 'r')
try:
fname, outfn = render_dot(self, code, options, 'png', prefix)
for line in fp:
match = svg_dim_re.match(line)
if match:
dimensions = match.groups()
break
else:
dimensions = None
finally:
fp.close()
# We need this hack to make WebKit show our object tag properly
def pt2px(x):
return int(ceil((96.0/72.0) * float(x)))
if dimensions:
style = ' width="%s" height="%s"' % tuple(map(pt2px, dimensions))
else:
style = ''
# The object tag works fine on Firefox and WebKit
# Besides it's a hack, this strategy does not mess with templates.
imgcss = imgcls and ' class="%s"' % imgcls or ''
return '<object type="image/svg+xml" data="%s"%s%s/>\n' % \
(svgref, imgcss, style)
def render_dot_html(self, node, code, options, prefix='graphviz',
imgcls=None, alt=None):
format = self.builder.config.graphviz_output_format
try:
if format not in ('png', 'svg'):
raise GraphvizError("graphviz_output_format must be one of 'png', "
"'svg', but is %r" % format)
fname, outfn = render_dot(self, code, options, format, prefix)
except GraphvizError, exc:
self.builder.warn('dot code %r: ' % code + str(exc))
raise nodes.SkipNode
@@ -139,23 +186,29 @@ def render_dot_html(self, node, code, options, prefix='graphviz', imgcls=None):
if fname is None:
self.body.append(self.encode(code))
else:
mapfile = open(outfn + '.map', 'rb')
try:
imgmap = mapfile.readlines()
finally:
mapfile.close()
imgcss = imgcls and 'class="%s"' % imgcls or ''
if len(imgmap) == 2:
# nothing in image map (the lines are <map> and </map>)
self.body.append('<img src="%s" alt="%s" %s/>\n' %
(fname, self.encode(code).strip(), imgcss))
if alt is None:
alt = node.get('alt', self.encode(code).strip())
if format == 'svg':
svgtag = get_svg_tag(fname, outfn, imgcls)
self.body.append(svgtag)
else:
# has a map: get the name of the map and connect the parts
mapname = mapname_re.match(imgmap[0]).group(1)
self.body.append('<img src="%s" alt="%s" usemap="#%s" %s/>\n' %
(fname, self.encode(code).strip(),
mapname, imgcss))
self.body.extend(imgmap)
mapfile = open(outfn + '.map', 'rb')
try:
imgmap = mapfile.readlines()
finally:
mapfile.close()
imgcss = imgcls and 'class="%s"' % imgcls or ''
if len(imgmap) == 2:
# nothing in image map (the lines are <map> and </map>)
self.body.append('<img src="%s" alt="%s" %s/>\n' %
(fname, alt, imgcss))
else:
# has a map: get the name of the map and connect the parts
mapname = mapname_re.match(imgmap[0]).group(1)
self.body.append('<img src="%s" alt="%s" usemap="#%s" %s/>\n' %
(fname, alt, mapname, imgcss))
self.body.extend(imgmap)
self.body.append('</p>\n')
raise nodes.SkipNode
@@ -188,3 +241,4 @@ def setup(app):
app.add_directive('digraph', GraphvizSimple)
app.add_config_value('graphviz_dot', 'dot', 'html')
app.add_config_value('graphviz_dot_args', [], 'html')
app.add_config_value('graphviz_output_format', 'png', 'html')

2
sphinx/ext/ifconfig.py
View File

@@ -16,7 +16,7 @@
namespace of the project configuration (that is, all variables from
``conf.py`` are available.)
:copyright: Copyright 2007-2009 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2010 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""

7
sphinx/ext/inheritance_diagram.py
View File

@@ -32,7 +32,7 @@
The graph is inserted as a PNG+image map into HTML and a PDF in
LaTeX.
:copyright: Copyright 2007-2009 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2010 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
@@ -301,7 +301,7 @@ class InheritanceDiagram(Directive):
node['graph'] = graph
# Store the original content for use as a hash
node['parts'] = self.options.get('parts', 0)
node['content'] = ' '.join(class_names)
node['content'] = ', '.join(class_names)
return [node]
@@ -329,7 +329,8 @@ def html_visit_inheritance_diagram(self, node):
urls[child['reftitle']] = '#' + child.get('refid')
dotcode = graph.generate_dot(name, parts, urls, env=self.builder.env)
render_dot_html(self, node, dotcode, [], 'inheritance', 'inheritance')
render_dot_html(self, node, dotcode, [], 'inheritance', 'inheritance',
alt='Inheritance diagram of ' + node['content'])
raise nodes.SkipNode

2
sphinx/ext/intersphinx.py
View File

@@ -20,7 +20,7 @@
also be specified individually, e.g. if the docs should be buildable
without Internet access.
:copyright: Copyright 2007-2009 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2010 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""

2
sphinx/ext/jsmath.py
View File

@@ -6,7 +6,7 @@
Set up everything for use of JSMath to display math in HTML
via JavaScript.
:copyright: Copyright 2007-2009 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2010 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""

2
sphinx/ext/mathbase.py
View File

@@ -5,7 +5,7 @@
Set up math support in source files and LaTeX/text output.
:copyright: Copyright 2007-2009 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2010 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""

8
sphinx/ext/pngmath.py
View File

@@ -5,7 +5,7 @@
Render math in HTML via dvipng.
:copyright: Copyright 2007-2009 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2010 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
@@ -23,7 +23,7 @@ except ImportError:
from docutils import nodes
from sphinx.errors import SphinxError
from sphinx.util import ensuredir
from sphinx.util import ensuredir, ENOENT
from sphinx.util.png import read_png_depth, write_png_depth
from sphinx.ext.mathbase import setup_math as mathbase_setup, wrap_displaymath
@@ -119,7 +119,7 @@ def render_math(self, math):
try:
p = Popen(ltx_args, stdout=PIPE, stderr=PIPE)
except OSError, err:
if err.errno != 2: # No such file or directory
if err.errno != ENOENT: # No such file or directory
raise
self.builder.warn('LaTeX command %r cannot be run (needed for math '
'display), check the pngmath_latex setting' %
@@ -147,7 +147,7 @@ def render_math(self, math):
try:
p = Popen(dvipng_args, stdout=PIPE, stderr=PIPE)
except OSError, err:
if err.errno != 2: # No such file or directory
if err.errno != ENOENT: # No such file or directory
raise
self.builder.warn('dvipng command %r cannot be run (needed for math '
'display), check the pngmath_dvipng setting' %

2
sphinx/ext/refcounting.py
View File

@@ -9,7 +9,7 @@
Usage: Set the `refcount_file` config value to the path to the reference
count data file.
:copyright: Copyright 2007-2009 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2010 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""

30
sphinx/ext/todo.py
View File

@@ -8,7 +8,7 @@
all todos of your project and lists them along with a backlink to the
original location.
:copyright: Copyright 2007-2009 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2010 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
@@ -42,20 +42,31 @@ class Todo(Directive):
ad = make_admonition(todo_node, self.name, [_('Todo')], self.options,
self.content, self.lineno, self.content_offset,
self.block_text, self.state, self.state_machine)
ad[0].line = self.lineno
return [targetnode] + ad
# Attach a list of all todos to the environment,
# the todolist works with the collected todo nodes
if not hasattr(env, 'todo_all_todos'):
env.todo_all_todos = []
def process_todos(app, doctree):
# collect all todos in the environment
# this is not done in the directive itself because it some transformations
# must have already been run, e.g. substitutions
env = app.builder.env
if not hasattr(env, 'todo_all_todos'):
env.todo_all_todos = []
for node in doctree.traverse(todo_node):
try:
targetnode = node.parent[node.parent.index(node) - 1]
if not isinstance(targetnode, nodes.target):
raise IndexError
except IndexError:
targetnode = None
env.todo_all_todos.append({
'docname': env.docname,
'lineno': self.lineno,
'todo': ad[0].deepcopy(),
'lineno': node.line,
'todo': node.deepcopy(),
'target': targetnode,
})
return [targetnode] + ad
class TodoList(Directive):
"""
@@ -152,6 +163,7 @@ def setup(app):
app.add_directive('todo', Todo)
app.add_directive('todolist', TodoList)
app.connect('doctree-read', process_todos)
app.connect('doctree-resolved', process_todo_nodes)
app.connect('env-purge-doc', purge_todos)

11
sphinx/highlighting.py
View File

@@ -5,7 +5,7 @@
Highlight code blocks using Pygments.
:copyright: Copyright 2007-2009 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2010 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
@@ -20,7 +20,7 @@ except ImportError:
# parser is not available on Jython
parser = None
from sphinx.util.texescape import tex_hl_escape_map
from sphinx.util.texescape import tex_hl_escape_map_old, tex_hl_escape_map_new
try:
import pygments
@@ -130,7 +130,7 @@ class PygmentsBridge(object):
# first, escape highlighting characters like Pygments does
source = source.translate(escape_hl_chars)
# then, escape all characters nonrepresentable in LaTeX
source = source.translate(tex_hl_escape_map)
source = source.translate(tex_hl_escape_map_old)
return '\\begin{Verbatim}[commandchars=@\\[\\]]\n' + \
source + '\\end{Verbatim}\n'
@@ -215,7 +215,10 @@ class PygmentsBridge(object):
return highlight(source, lexer, self.fmter[bool(linenos)])
else:
hlsource = highlight(source, lexer, self.fmter[bool(linenos)])
return hlsource.translate(tex_hl_escape_map)
if hlsource.startswith(r'\begin{Verbatim}[commandchars=\\\{\}'):
# Pygments >= 1.2
return hlsource.translate(tex_hl_escape_map_new)
return hlsource.translate(tex_hl_escape_map_old)
except ErrorToken:
# this is most probably not the selected language,
# so let it pass unhighlighted

2
sphinx/jinja2glue.py
View File

@@ -5,7 +5,7 @@
Glue code for the jinja2 templating engine.
:copyright: Copyright 2007-2009 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2010 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""

2
sphinx/locale/__init__.py
View File

@@ -5,7 +5,7 @@
Locale utilities.
:copyright: Copyright 2007-2009 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2010 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""

41
sphinx/pycode/__init__.py
View File

@@ -5,7 +5,7 @@
Utilities parsing and analyzing Python code.
:copyright: Copyright 2007-2009 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2010 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
@@ -45,22 +45,33 @@ _eq = nodes.Leaf(token.EQUAL, '=')
class AttrDocVisitor(nodes.NodeVisitor):
"""
Visitor that collects docstrings for attribute assignments on toplevel and
in classes.
in classes (class attributes and attributes set in __init__).
The docstrings can either be in special '#:' comments before the assignment
or in a docstring after it.
"""
def init(self, scope, encoding):
self.scope = scope
self.in_init = 0
self.encoding = encoding
self.namespace = []
self.collected = {}
def visit_classdef(self, node):
"""Visit a class."""
self.namespace.append(node[1].value)
self.generic_visit(node)
self.namespace.pop()
def visit_funcdef(self, node):
"""Visit a function (or method)."""
# usually, don't descend into functions -- nothing interesting there
if node[1].value == '__init__':
# however, collect attributes set in __init__ methods
self.in_init += 1
self.generic_visit(node)
self.in_init -= 1
def visit_expr_stmt(self, node):
"""Visit an assignment which may have a special comment before it."""
if _eq not in node.children:
@@ -97,20 +108,32 @@ class AttrDocVisitor(nodes.NodeVisitor):
docstring = prepare_docstring(docstring)
self.add_docstring(prev[0], docstring)
def visit_funcdef(self, node):
# don't descend into functions -- nothing interesting there
return
def add_docstring(self, node, docstring):
# add an item for each assignment target
for i in range(0, len(node) - 1, 2):
target = node[i]
if target.type != token.NAME:
# don't care about complex targets
if self.in_init and self.number2name[target.type] == 'power':
# maybe an attribute assignment -- check necessary conditions
if (# node must have two children
len(target) != 2 or
# first child must be "self"
target[0].type != token.NAME or target[0].value != 'self' or
# second child must be a "trailer" with two children
self.number2name[target[1].type] != 'trailer' or
len(target[1]) != 2 or
# first child must be a dot, second child a name
target[1][0].type != token.DOT or
target[1][1].type != token.NAME):
continue
name = target[1][1].value
elif target.type != token.NAME:
# don't care about other complex targets
continue
else:
name = target.value
namespace = '.'.join(self.namespace)
if namespace.startswith(self.scope):
self.collected[namespace, target.value] = docstring
self.collected[namespace, name] = docstring
class PycodeError(Exception):

2
sphinx/pycode/nodes.py
View File

@@ -5,7 +5,7 @@
Parse tree node implementations.
:copyright: Copyright 2007-2009 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2010 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""

41
sphinx/quickstart.py
View File

@@ -5,7 +5,7 @@
Quickly setup documentation source to work with Sphinx.
:copyright: Copyright 2007-2009 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2010 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
@@ -84,12 +84,9 @@ release = '%(release_str)s'
# Else, today_fmt is used as the format for a strftime call.
#today_fmt = '%%B %%d, %%Y'
# List of documents that shouldn't be included in the build.
#unused_docs = []
# List of directories, relative to source directory, that shouldn't be searched
# for source files.
exclude_trees = [%(exclude_trees)s]
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
exclude_patterns = [%(exclude_patterns)s]
# The reST default role (used for this markup: `text`) to use for all documents.
#default_role = None
@@ -227,39 +224,23 @@ latex_documents = [
# -- Options for Epub output ---------------------------------------------------
# Please also set the html_theme to 'epub' or any other approriate theme.
# The display size is quite small for ebook readers.
# The default themes may take too much space.
# bibliographic Dublin Core description of the content.opf and
# in the toc.ncx file. It defaults to the html_title option.
# Bibliographic Dublin Core info.
#epub_title = ''
# The author of the text. The author is inserted into the
# bibliographic Dublin Core description of the content.opf file.
#epub_author = ''
#epub_publisher = ''
#epub_copyright = ''
# The language of the text. It defaults to the language option
# or en if the language is not set.
#epub_language = ''
# The publisher of the text. The publisher is inserted into the
# bibliographic Dublin Core description of the content.opf file.
# You may use the project homepage.
#epub_publisher = ''
# The copyright of the text. The copyright is inserted into the
# bibliographci Dublin Core description of the content.opf file.
# It defaults to the copyright option.
#epub_copyright = ''
# The scheme of the identifier. Typical schemes are ISBN or URL.
#epub_scheme = ''
# The unique identifier of the text. This can be a ISBN number
# or the project homepage.
#epub_identifier = ''
# The scheme of the identifier. Typical schemes are ISBN or URL.
#epub_scheme = ''
# A unique identification for the text.
#epub_uid = ''
@@ -759,10 +740,10 @@ directly.'''
mkdir_p(srcdir)
if d['sep']:
builddir = path.join(d['path'], 'build')
d['exclude_trees'] = ''
d['exclude_patterns'] = ''
else:
builddir = path.join(srcdir, d['dot'] + 'build')
d['exclude_trees'] = repr(d['dot'] + 'build')
d['exclude_patterns'] = repr(d['dot'] + 'build')
mkdir_p(builddir)
mkdir_p(path.join(srcdir, d['dot'] + 'templates'))
mkdir_p(path.join(srcdir, d['dot'] + 'static'))

3
sphinx/roles.py
View File

@@ -5,7 +5,7 @@
Handlers for additional ReST roles.
:copyright: Copyright 2007-2009 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2010 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
@@ -190,6 +190,7 @@ def xfileref_role(typ, rawtext, text, lineno, inliner, options={}, content=[]):
else:
# remove all whitespace to avoid referencing problems
target = ws_re.sub('', target)
pnode['refdoc'] = env.docname
pnode['reftarget'] = target
pnode += innernodetypes.get(typ, nodes.literal)(rawtext, title,
classes=['xref'])

2
sphinx/search.py
View File

@@ -5,7 +5,7 @@
Create a search index for offline search.
:copyright: Copyright 2007-2009 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2010 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
import re

2
sphinx/setup_command.py
View File

@@ -8,7 +8,7 @@
:author: Sebastian Wiesner
:contact: basti.wiesner@gmx.net
:copyright: Copyright 2007-2009 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2010 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""

10
sphinx/themes/agogo/layout.html
View File

@@ -1,3 +1,13 @@
{#
agogo/layout.html
~~~~~~~~~~~~~~~~~
Sphinx layout template for the agogo theme, originally written
by Andi Albrecht.
:copyright: Copyright 2007-2010 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
#}
{% extends "basic/layout.html" %}
{% block header %}

25
sphinx/themes/agogo/static/agogo.css_t
View File

@@ -1,3 +1,14 @@
/*
* agogo.css_t
* ~~~~~~~~~~~
*
* Sphinx stylesheet -- agogo theme.
*
* :copyright: Copyright 2007-2010 by the Sphinx team, see AUTHORS.
* :license: BSD, see LICENSE for details.
*
*/
* {
margin: 0px;
padding: 0px;
@@ -44,6 +55,18 @@ a {
float: right;
}
.line-block {
display: block;
margin-top: 1em;
margin-bottom: 1em;
}
.line-block .line-block {
margin-top: 0;
margin-bottom: 0;
margin-left: 1.5em;
}
h1, h2, h3, h4 {
font-family: {{ theme_headerfont }};
font-weight: normal;
@@ -257,7 +280,7 @@ div.footer .left {
}
/* Styles copied form basic theme */
/* Styles copied from basic theme */
/* -- search page ----------------------------------------------------------- */

9
sphinx/themes/basic/defindex.html
View File

@@ -1,3 +1,12 @@
{#
basic/defindex.html
~~~~~~~~~~~~~~~~~~~
Default template for the "index" page.
:copyright: Copyright 2007-2010 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
#}
{% extends "layout.html" %}
{% set title = _('Overview') %}
{% block body %}

46
sphinx/themes/basic/genindex-single.html
View File

@@ -1,36 +1,38 @@
{#
basic/genindex-single.html
~~~~~~~~~~~~~~~~~~~~~~~~~~
Template for a "single" page of a split index.
:copyright: Copyright 2007-2010 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
#}
{% extends "layout.html" %}
{% set title = _('Index') %}
{% block body %}
<h1 id="index">{% trans key=key %}Index &ndash; {{ key }}{% endtrans %}</h1>
<table width="100%" class="indextable"><tr><td width="33%" valign="top">
<dl>
{%- set breakat = count // 2 %}
{%- set numcols = 1 %}
{%- set numitems = 0 %}
{% for entryname, (links, subitems) in entries %}
<dt>{%- if links -%}<a href="{{ links[0] }}">{{ entryname|e }}</a>
{%- for link in links[1:] %}, <a href="{{ link }}">[{{ loop.index }}]</a>{% endfor -%}
{%- else -%}
{{ entryname|e }}
{%- endif -%}</dt>
{%- if subitems %}
<dd><dl>
<table width="100%" class="indextable"><tr>
{%- for column in entries|slice(2) if column %}
<td width="33%" valign="top"><dl>
{%- for entryname, (links, subitems) in column %}
<dt>{% if links %}<a href="{{ links[0] }}">{{ entryname|e }}</a>
{%- for link in links[1:] %}, <a href="{{ link }}">[{{ loop.index }}]</a>{% endfor %}
{%- else %}{{ entryname|e }}{% endif %}</dt>
{%- if subitems %}
<dd><dl>
{%- for subentryname, subentrylinks in subitems %}
<dt><a href="{{ subentrylinks[0] }}">{{ subentryname|e }}</a>
{%- for link in subentrylinks[1:] %}, <a href="{{ link }}">[{{ loop.index }}]</a>{% endfor -%}
</dt>
<dt><a href="{{ subentrylinks[0] }}">{{ subentryname|e }}</a>
{%- for link in subentrylinks[1:] %}, <a href="{{ link }}">[{{ loop.index }}]</a>{% endfor -%}
</dt>
{%- endfor %}
</dl></dd>
{%- endif -%}
{%- set numitems = numitems + 1 + (subitems|length) -%}
{%- if numcols < 2 and numitems > breakat -%}
{%- set numcols = numcols+1 -%}
</dl></td><td width="33%" valign="top"><dl>
{%- endif -%}
{%- endfor %}
</dl></td></tr></table>
</dl></td>
{%- endfor %}
</tr></table>
{% endblock %}

11
sphinx/themes/basic/genindex-split.html
View File

@@ -1,3 +1,12 @@
{#
basic/genindex-split.html
~~~~~~~~~~~~~~~~~~~~~~~~~
Template for a "split" index overview page.
:copyright: Copyright 2007-2010 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
#}
{% extends "layout.html" %}
{% set title = _('Index') %}
{% block body %}
@@ -6,6 +15,7 @@
<p>{{ _('Index pages by letter') }}:</p>
<div class="genindex-jumpbox">
<p>{% for key, dummy in genindexentries -%}
<a href="{{ pathto('genindex-' + key) }}"><strong>{{ key }}</strong></a>
{% if not loop.last %}| {% endif %}
@@ -13,6 +23,7 @@
<p><a href="{{ pathto('genindex-all') }}"><strong>{{ _('Full index on one page') }}</strong>
({{ _('can be huge') }})</a></p>
</div>
{% endblock %}

52
sphinx/themes/basic/genindex.html
View File

@@ -1,44 +1,46 @@
{#
basic/genindex.html
~~~~~~~~~~~~~~~~~~~
Template for an "all-in-one" index.
:copyright: Copyright 2007-2010 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
#}
{% extends "layout.html" %}
{% set title = _('Index') %}
{% block body %}
<h1 id="index">{{ _('Index') }}</h1>
<div class="genindex-jumpbox">
{% for key, dummy in genindexentries -%}
<a href="#{{ key }}"><strong>{{ key }}</strong></a> {% if not loop.last %}| {% endif %}
{%- endfor %}
</div>
<hr />
{% for key, entries in genindexentries %}
{%- for key, entries in genindexentries %}
<h2 id="{{ key }}">{{ key }}</h2>
<table width="100%" class="indextable"><tr><td width="33%" valign="top">
<dl>
{%- set breakat = genindexcounts[loop.index0] // 2 %}
{%- set numcols = 1 %}
{%- set numitems = 0 %}
{% for entryname, (links, subitems) in entries %}
<dt>{%- if links -%}<a href="{{ links[0] }}">{{ entryname|e }}</a>
{%- for link in links[1:] %}, <a href="{{ link }}">[{{ loop.index }}]</a>{% endfor -%}
{%- else -%}
{{ entryname|e }}
{%- endif -%}</dt>
{%- if subitems %}
<dd><dl>
<table width="100%" class="indextable genindextable"><tr>
{%- for column in entries|slice(2) if column %}
<td width="33%" valign="top"><dl>
{%- for entryname, (links, subitems) in column %}
<dt>{% if links %}<a href="{{ links[0] }}">{{ entryname|e }}</a>
{%- for link in links[1:] %}, <a href="{{ link }}">[{{ loop.index }}]</a>{% endfor %}
{%- else %}{{ entryname|e }}{% endif %}</dt>
{%- if subitems %}
<dd><dl>
{%- for subentryname, subentrylinks in subitems %}
<dt><a href="{{ subentrylinks[0] }}">{{ subentryname|e }}</a>
{%- for link in subentrylinks[1:] %}, <a href="{{ link }}">[{{ loop.index }}]</a>{% endfor -%}
</dt>
<dt><a href="{{ subentrylinks[0] }}">{{ subentryname|e }}</a>
{%- for link in subentrylinks[1:] %}, <a href="{{ link }}">[{{ loop.index }}]</a>{% endfor -%}
</dt>
{%- endfor %}
</dl></dd>
{%- endif -%}
{%- set numitems = numitems + 1 + (subitems|length) -%}
{%- if numcols < 2 and numitems > breakat -%}
{%- set numcols = numcols+1 -%}
</dl></td><td width="33%" valign="top"><dl>
{%- endif -%}
{%- endfor %}
</dl></td></tr></table>
</dl></td>
{%- endfor %}
</tr></table>
{% endfor %}
{% endblock %}

13
sphinx/themes/basic/globaltoc.html Normal file
View File

@@ -0,0 +1,13 @@
{#
basic/globaltoc.html
~~~~~~~~~~~~~~~~~~~~
Sphinx sidebar template: global table of contents.
:copyright: Copyright 2007-2010 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
#}
{%- if display_toc %}
<h3><a href="{{ pathto(master_doc) }}">{{ _('Table Of Contents') }}</a></h3>
{{ toctree() }}
{%- endif %}

77
sphinx/themes/basic/layout.html
View File

@@ -1,3 +1,12 @@
{#
basic/layout.html
~~~~~~~~~~~~~~~~~
Master layout template for Sphinx themes.
:copyright: Copyright 2007-2010 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
#}
{%- block doctype -%}
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
@@ -37,53 +46,29 @@
</a></p>
{%- endif %}
{%- endblock %}
{%- block sidebartoc %}
{%- if display_toc %}
<h3><a href="{{ pathto(master_doc) }}">{{ _('Table Of Contents') }}</a></h3>
{{ toc }}
{%- if sidebars %}
{#- new style sidebar: explicitly include/exclude templates #}
{%- for sidebartemplate in sidebars %}
{%- include sidebartemplate %}
{%- endfor %}
{%- else %}
{#- old style sidebars: using blocks -- should be deprecated #}
{%- block sidebartoc %}
{%- include "localtoc.html" %}
{%- endblock %}
{%- block sidebarrel %}
{%- include "relations.html" %}
{%- endblock %}
{%- block sidebarsourcelink %}
{%- include "sourcelink.html" %}
{%- endblock %}
{%- if customsidebar %}
{%- include customsidebar %}
{%- endif %}
{%- block sidebarsearch %}
{%- include "searchbox.html" %}
{%- endblock %}
{%- endif %}
{%- endblock %}
{%- block sidebarrel %}
{%- if prev %}
<h4>{{ _('Previous topic') }}</h4>
<p class="topless"><a href="{{ prev.link|e }}"
title="{{ _('previous chapter') }}">{{ prev.title }}</a></p>
{%- endif %}
{%- if next %}
<h4>{{ _('Next topic') }}</h4>
<p class="topless"><a href="{{ next.link|e }}"
title="{{ _('next chapter') }}">{{ next.title }}</a></p>
{%- endif %}
{%- endblock %}
{%- block sidebarsourcelink %}
{%- if show_source and has_source and sourcename %}
<h3>{{ _('This Page') }}</h3>
<ul class="this-page-menu">
<li><a href="{{ pathto('_sources/' + sourcename, true)|e }}"
rel="nofollow">{{ _('Show Source') }}</a></li>
</ul>
{%- endif %}
{%- endblock %}
{%- if customsidebar %}
{% include customsidebar %}
{%- endif %}
{%- block sidebarsearch %}
{%- if pagename != "search" %}
<div id="searchbox" style="display: none">
<h3>{{ _('Quick search') }}</h3>
<form class="search" action="{{ pathto('search') }}" method="get">
<input type="text" name="q" size="18" />
<input type="submit" value="{{ _('Go') }}" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
<p class="searchtip" style="font-size: 90%">
{{ _('Enter search terms or a module, class or function name.') }}
</p>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
{%- endif %}
{%- endblock %}
</div>
</div>
{%- endif %}{% endif %}

13
sphinx/themes/basic/localtoc.html Normal file
View File

@@ -0,0 +1,13 @@
{#
basic/localtoc.html
~~~~~~~~~~~~~~~~~~~
Sphinx sidebar template: local table of contents.
:copyright: Copyright 2007-2010 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
#}
{%- if display_toc %}
<h3><a href="{{ pathto(master_doc) }}">{{ _('Table Of Contents') }}</a></h3>
{{ toc }}
{%- endif %}

14
sphinx/themes/basic/modindex.html
View File

@@ -1,3 +1,12 @@
{#
basic/modindex.html
~~~~~~~~~~~~~~~~~~~
Template for the module index.
:copyright: Copyright 2007-2010 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
#}
{% extends "layout.html" %}
{% set title = _('Global Module Index') %}
{% block extrahead %}
@@ -12,12 +21,13 @@
<h1 id="global-module-index">{{ _('Global Module Index') }}</h1>
<div class="modindex-jumpbox">
{%- for letter in letters %}
<a href="#cap-{{ letter }}"><strong>{{ letter }}</strong></a> {% if not loop.last %}| {% endif %}
{%- endfor %}
<hr/>
</div>
<table width="100%" class="indextable" cellspacing="0" cellpadding="2">
<table class="indextable modindextable" cellspacing="0" cellpadding="2">
{%- for modname, collapse, cgroup, indent, fname, synops, pform, dep, stripped in modindexentries %}
{%- if not modname -%}
<tr class="pcap"><td></td><td>&nbsp;</td><td></td></tr>

9
sphinx/themes/basic/page.html
View File

@@ -1,3 +1,12 @@
{#
basic/page.html
~~~~~~~~~~~~~~~
Master template for simple pages.
:copyright: Copyright 2007-2010 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
#}
{% extends "layout.html" %}
{% block body %}
{{ body }}

19
sphinx/themes/basic/relations.html Normal file
View File

@@ -0,0 +1,19 @@
{#
basic/relations.html
~~~~~~~~~~~~~~~~~~~~
Sphinx sidebar template: relation links.
:copyright: Copyright 2007-2010 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
#}
{%- if prev %}
<h4>{{ _('Previous topic') }}</h4>
<p class="topless"><a href="{{ prev.link|e }}"
title="{{ _('previous chapter') }}">{{ prev.title }}</a></p>
{%- endif %}
{%- if next %}
<h4>{{ _('Next topic') }}</h4>
<p class="topless"><a href="{{ next.link|e }}"
title="{{ _('next chapter') }}">{{ next.title }}</a></p>
{%- endif %}

11
sphinx/themes/basic/search.html
View File

@@ -1,3 +1,12 @@
{#
basic/search.html
~~~~~~~~~~~~~~~~~
Template for the search page.
:copyright: Copyright 2007-2010 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
#}
{% extends "layout.html" %}
{% set title = _('Search') %}
{% set script_files = script_files + ['_static/searchtools.js'] %}
@@ -41,5 +50,5 @@
{% endblock %}
{% block footer %}
{{ super() }}
<script type="text/javascript" src="searchindex.js"></script>
<script type="text/javascript" src="{{ pathto('searchindex.js', 1) }}"></script>
{% endblock %}

24
sphinx/themes/basic/searchbox.html Normal file
View File

@@ -0,0 +1,24 @@
{#
basic/searchbox.html
~~~~~~~~~~~~~~~~~~~~
Sphinx sidebar template: quick search box.
:copyright: Copyright 2007-2010 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
#}
{%- if pagename != "search" %}
<div id="searchbox" style="display: none">
<h3>{{ _('Quick search') }}</h3>
<form class="search" action="{{ pathto('search') }}" method="get">
<input type="text" name="q" size="18" />
<input type="submit" value="{{ _('Go') }}" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
<p class="searchtip" style="font-size: 90%">
{{ _('Enter search terms or a module, class or function name.') }}
</p>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
{%- endif %}

16
sphinx/themes/basic/sourcelink.html Normal file
View File

@@ -0,0 +1,16 @@
{#
basic/sourcelink.html
~~~~~~~~~~~~~~~~~~~~~
Sphinx sidebar template: "show source" link.
:copyright: Copyright 2007-2010 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
#}
{%- if show_source and has_source and sourcename %}
<h3>{{ _('This Page') }}</h3>
<ul class="this-page-menu">
<li><a href="{{ pathto('_sources/' + sourcename, true)|e }}"
rel="nofollow">{{ _('Show Source') }}</a></li>
</ul>
{%- endif %}

42
sphinx/themes/basic/static/basic.css
View File

@@ -1,6 +1,12 @@
/**
* Sphinx stylesheet -- basic theme
* ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
/*
* basic.css
* ~~~~~~~~~
*
* Sphinx stylesheet -- basic theme.
*
* :copyright: Copyright 2007-2010 by the Sphinx team, see AUTHORS.
* :license: BSD, see LICENSE for details.
*
*/
/* -- main layout ----------------------------------------------------------- */
@@ -127,6 +133,10 @@ span.linkdescr {
/* -- general index --------------------------------------------------------- */
table.indextable {
width: 100%;
}
table.indextable td {
text-align: left;
vertical-align: top;
@@ -152,6 +162,20 @@ img.toggler {
cursor: pointer;
}
div.modindex-jumpbox {
border-top: 1px solid #ddd;
border-bottom: 1px solid #ddd;
margin: 1em 0 1em 0;
padding: 0.4em;
}
div.genindex-jumpbox {
border-top: 1px solid #ddd;
border-bottom: 1px solid #ddd;
margin: 1em 0 1em 0;
padding: 0.4em;
}
/* -- general body styles --------------------------------------------------- */
a.headerlink {
@@ -332,6 +356,18 @@ dl.glossary dt {
background-color: #ffa
}
.line-block {
display: block;
margin-top: 1em;
margin-bottom: 1em;
}
.line-block .line-block {
margin-top: 0;
margin-bottom: 0;
margin-left: 1.5em;
}
/* -- code displays --------------------------------------------------------- */
pre {

11
sphinx/themes/basic/static/doctools.js
View File

@@ -1,4 +1,13 @@
/// XXX: make it cross browser
/*
* doctools.js
* ~~~~~~~~~~~
*
* Sphinx JavaScript utilties for all documentation.
*
* :copyright: Copyright 2007-2010 by the Sphinx team, see AUTHORS.
* :license: BSD, see LICENSE for details.
*
*/
/**
* make the code below compatible with browsers without

11
sphinx/themes/basic/static/searchtools.js
View File

@@ -1,3 +1,14 @@
/*
* searchtools.js
* ~~~~~~~~~~~~~~
*
* Sphinx JavaScript utilties for the full-text search.
*
* :copyright: Copyright 2007-2010 by the Sphinx team, see AUTHORS.
* :license: BSD, see LICENSE for details.
*
*/
/**
* helper function to return a node containing the
* search summary for a given text. keywords is a list

20
sphinx/themes/default/static/default.css_t
View File

@@ -1,6 +1,12 @@
/**
* Sphinx stylesheet -- default theme
* ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
/*
* default.css_t
* ~~~~~~~~~~~~~
*
* Sphinx stylesheet -- default theme.
*
* :copyright: Copyright 2007-2010 by the Sphinx team, see AUTHORS.
* :license: BSD, see LICENSE for details.
*
*/
@import url("basic.css");
@@ -250,3 +256,11 @@ tt {
th {
background-color: #ede;
}
.warning tt {
background: #efc2c2;
}
.note tt {
background: #d6d6d6;
}

9
sphinx/themes/epub/layout.html
View File

@@ -1,3 +1,12 @@
{#
epub/layout.html
~~~~~~~~~~~~~~~~
Sphinx layout template for the epub theme.
:copyright: Copyright 2007-2010 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
#}
{% extends "basic/layout.html" %}
{# add only basic navigation links #}

Some files were not shown because too many files have changed in this diff Show More