diff --git a/.hgignore b/.hgignore index 813a703f9..b3df24f47 100644 --- a/.hgignore +++ b/.hgignore @@ -1,6 +1,10 @@ .*\.pyc .*\.egg +.*\.so build/ dist/ +tests/.coverage +sphinx/pycode/Grammar.*pickle Sphinx.egg-info/ doc/_build/ +TAGS diff --git a/AUTHORS b/AUTHORS index e5a737733..73ec5ed23 100644 --- a/AUTHORS +++ b/AUTHORS @@ -1,8 +1,31 @@ -The doctools are written and maintained by Georg Brandl . -Substantial parts of the templates and the web application were written by -Armin Ronacher . +Sphinx is written and maintained by Georg Brandl . -Other contributors are noted in the :copyright: fields within the docstrings -of the respective files. +Substantial parts of the templates were written by Armin Ronacher +. + +Other contributors, listed alphabetically, are: + +* Daniel Bültmann -- todo extension +* Michael Droettboom -- inheritance_diagram extension +* Charles Duffy -- original graphviz extension +* Josip Dzolonga -- coverage builder +* Horst Gutmann -- internationalization support +* Martin Hans -- autodoc improvements +* Dave Kuhlman -- original LaTeX writer +* Thomas Lamb -- linkcheck builder +* Will Maier -- directory HTML builder +* Benjamin Peterson -- unittests +* Stefan Seefeld -- toctree improvements +* Antonio Valentino -- qthelp builder +* Pauli Virtanen -- autodoc improvements +* Sebastian Wiesner -- image handling, distutils support Many thanks for all contributions! + +There are also a few modules or functions incorporated from other +authors and projects: + +* sphinx.util.jsdump uses the basestring encoding from simplejson, + written by Bob Ippolito, released under the MIT license +* sphinx.util.stemmer was written by Vivake Gupta, placed in the + Public Domain diff --git a/CHANGES b/CHANGES index e1fd96a2b..cd0c82fb5 100644 --- a/CHANGES +++ b/CHANGES @@ -1,9 +1,292 @@ -Release 0.5 (in development) +Release 0.6 (in development) ============================ New features added ------------------ +* Incompatible changes: + + - Templating now requires the Jinja2 library, which is an enhanced + version of the old Jinja1 engine. Since the syntax and semantic + is largely the same, very few fixes should be necessary in + custom templates. + + - The "document" div tag has been moved out of the ``layout.html`` + template's "document" block, because the closing tag was already + outside. If you overwrite this block, you need to remove your + "document" div tag as well. + + - The ``autodoc_skip_member`` event now also gets to decide + whether to skip members whose name starts with underscores. + Previously, these members were always automatically skipped. + Therefore, if you handle this event, add something like this + to your event handler to restore the old behavior:: + + if name.startswith('_'): + return True + +* Theming support, see the new section in the documentation. + +* Markup: + + - Due to popular demand, added a ``:doc:`` role which directly + links to another document without the need of creating a + label to which a ``:ref:`` could link to. + + - #4: Added a ``:download:`` role that marks a non-document file + for inclusion into the HTML output and links to it. + + - Added an ``only`` directive that can selectively include text + based on enabled "tags". Tags can be given on the command + line. Also, the current builder output format (e.g. "html" or + "latex") is always a defined tag. + + - #10: Added HTML section numbers, enabled by giving a + ``:numbered:`` flag to the ``toctree`` directive. + + - #114: Added an ``abbr`` role to markup abbreviations and + acronyms. + + - The ``literalinclude`` directive now supports several more + options, to include only parts of a file. + + - The ``toctree`` directive now supports a ``:hidden:`` flag, + which will prevent links from being generated in place of + the directive -- this allows you to define your document + structure, but place the links yourself. + + - Paths to images, literal include files and download files + can now be absolute (like ``/images/foo.png``). They are + treated as relative to the top source directory. + + - #52: There is now a ``hlist`` directive, creating a compact + list by placing distributing items into multiple columns. + + - #77: If a description environment with info field list only + contains one ``:param:`` entry, no bullet list is generated. + + - #6: Don't generate redundant ``
    `` for top-level TOC tree + items, which leads to a visual separation of TOC entries. + + - #23: Added a ``classmethod`` directive along with ``method`` + and ``staticmethod``. + + - Scaled images now get a link to the unscaled version. + + - SVG images are now supported in HTML (via ```` and + ```` tags). + + - Added a ``toctree`` callable to the templates, and the ability + to include external links in toctrees. The 'collapse' keyword + argument indicates whether or not to only display subitems of + the current page. (Defaults to True.) + +* Configuration: + + - The new config value ``rst_epilog`` can contain reST that is + appended to each source file that is read. This is the right + place for global substitutions. + + - The new ``html_add_permalinks`` config value can be used to + switch off the generated "paragraph sign" permalinks for each + heading and definition environment. + + - The new ``html_show_sourcelink`` config value can be used to + switch off the links to the reST sources in the sidebar. + + - The default value for ``htmlhelp_basename`` is now the project + title, cleaned up as a filename. + + - The new ``modindex_common_prefix`` config value can be used to + ignore certain package names for module index sorting. + + - The new ``trim_footnote_reference_space`` config value mirrors + the docutils config value of the same name and removes the + space before a footnote reference that is necessary for reST + to recognize the reference. + + - The new ``latex_additional_files`` config value can be used to + copy files (that Sphinx doesn't copy automatically, e.g. if they + are referenced in custom LaTeX added in ``latex_elements``) to + the build directory. + +* Builders: + + - The HTML builder now stores a small file named ``.buildinfo`` in + its output directory. It stores a hash of config values that + can be used to determine if a full rebuild needs to be done (e.g. + after changing ``html_theme``). + + - New builder for Qt help collections, by Antonio Valentino. + + - The new ``DirectoryHTMLBuilder`` (short name ``dirhtml``) creates + a separate directory for every page, and places the page there + in a file called ``index.html``. Therefore, page URLs and links + don't need to contain ``.html``. + + - The new ``html_link_suffix`` config value can be used to select + the suffix of generated links between HTML files. + + - #96: The LaTeX builder now supports figures wrapped by text, when + using the ``figwidth`` option and right/left alignment. + +* New translations: + + - Italian by Sandro Dentella. + + - Ukrainian by Petro Sasnyk. + + - Finnish by Jukka Inkeri. + +* Extensions and API: + + - New ``graphviz`` extension to embed graphviz graphs. + + - New ``inheritance_diagram`` extension to embed... inheritance + diagrams! + + - Autodoc now has a reusable Python API, which can be used to + create custom types of objects to auto-document (e.g. Zope + interfaces). See also ``Sphinx.add_autodocumenter()``. + + - Autodoc now handles documented attributes. + + - Autodoc now handles inner classes and their methods. + + - Autodoc can document classes as functions now if explicitly + marked with `autofunction`. + + - Autodoc can now order members either alphabetically (like + previously) or by member type; configurable either with the + config value ``autodoc_member_order`` or a ``member-order`` + option per directive. + + - The function ``Sphinx.add_directive()`` now also supports + docutils 0.5-style directive classes. If they inherit from + ``sphinx.util.compat.Directive``, they also work with + docutils 0.4. + + - There is now a ``Sphinx.add_lexer()`` method to be able to use + custom Pygments lexers easily. + + - There is now ``Sphinx.add_generic_role()`` to mirror the + docutils' own function. + +* Other changes: + + - Config overrides for single dict keys can now be given on the + command line. + + - There is now a ``doctest_global_setup`` config value that can + be used to give setup code for all doctests in the documentation. + + - Source links in HTML are now generated with ``rel="nofollow"``. + + - Quickstart can now generate a Windows ``make.bat`` file. + + - #62: There is now a ``-w`` option for sphinx-build that writes + warnings to a file, in addition to stderr. + + - There is now a ``-W`` option for sphinx-build that turns warnings + into errors. + + +Release 0.5.2 (in development) +============================== + +* Properly escape ``|`` in LaTeX output. + +* #71: If a decoding error occurs in source files, print a + warning and replace the characters by "?". + +* Fix a problem in the HTML search if the index takes too long + to load. + +* Don't output system messages while resolving, because they + would stay in the doctrees even if keep_warnings is false. + +* #82: Determine the correct path for dependencies noted by + docutils. This fixes behavior where a source with dependent + files was always reported as changed. + +* Recognize toctree directives that are not on section toplevel, + but within block items, such as tables. + +* Use a new RFC base URL, since rfc.org seems down. + +* Fix a crash in the todolist directive when no todo items are + defined. + +* Don't call LaTeX or dvipng over and over again if it was not + found once, and use text-only latex as a substitute in that case. + +* Fix problems with footnotes in the LaTeX output. + +* Prevent double hyphens becoming en-dashes in literal code in + the LaTeX output. + +* Open literalinclude files in universal newline mode to allow + arbitrary newline conventions. + +* Actually make the ``-Q`` option work. + +* #86: Fix explicit document titles in toctrees. + +* #81: Write environment and search index in a manner that is safe + from exceptions that occur during dumping. + +* #80: Fix UnicodeErrors when a locale is set with setlocale(). + + +Release 0.5.1 (Dec 15, 2008) +============================ + +* #67: Output warnings about failed doctests in the doctest extension + even when running in quiet mode. + +* #72: In pngmath, make it possible to give a full path to LaTeX and + dvipng on Windows. For that to work, the ``pngmath_latex`` and + ``pngmath_dvipng`` options are no longer split into command and + additional arguments; use ``pngmath_latex_args`` and + ``pngmath_dvipng_args`` to give additional arguments. + +* Don't crash on failing doctests with non-ASCII characters. + +* Don't crash on writing status messages and warnings containing + unencodable characters. + +* Warn if a doctest extension block doesn't contain any code. + +* Fix the handling of ``:param:`` and ``:type:`` doc fields when + they contain markup (especially cross-referencing roles). + +* #65: Fix storage of depth information for PNGs generated by the + pngmath extension. + +* Fix autodoc crash when automethod is used outside a class context. + +* #68: Fix LaTeX writer output for images with specified height. + +* #60: Fix wrong generated image path when including images in sources + in subdirectories. + +* Fix the JavaScript search when html_copy_source is off. + +* Fix an indentation problem in autodoc when documenting classes + with the option ``autoclass_content = "both"`` set. + +* Don't crash on empty index entries, only emit a warning. + +* Fix a typo in the search JavaScript code, leading to unusable + search function in some setups. + + +Release 0.5 (Nov 23, 2008) -- Birthday release! +=============================================== + +New features added +------------------ + * Markup features: - Citations are now global: all citation defined in any file can be @@ -31,6 +314,9 @@ New features added - The ``seealso`` directive can now also be given arguments, as a short form. + - You can now document several programs and their options with the + new ``program`` directive. + * HTML output and templates: - Incompatible change: The "root" relation link (top left in the @@ -42,6 +328,12 @@ New features added - The JavaScript search now searches for objects before searching in the full text. + - TOC tree entries now have CSS classes that make it possible to + style them depending on their depth. + + - Highlighted code blocks now have CSS classes that make it possible + to style them depending on their language. + - HTML ```` tags via the docutils ``meta`` directive are now supported. @@ -76,6 +368,10 @@ New features added * Michał Kandulski -- Polish * Yasushi Masuda -- Japanese * Guillem Borrell -- Spanish + * Luc Saffre and Peter Bertels -- Dutch + * Fred Lin -- Traditional Chinese + * Roger Demetrescu -- Brazilian Portuguese + * Rok Garbas -- Slovenian - The new config value ``highlight_language`` set a global default for highlighting. When ``'python3'`` is selected, console output blocks @@ -100,6 +396,10 @@ New features added creates links to Sphinx documentation of Python objects in other projects. + - The new extension ``sphinx.ext.todo`` allows the insertion of + "To do" directives whose visibility in the output can be toggled. + It also adds a directive to compile a list of all todo items. + - sphinx.ext.autodoc has a new event ``autodoc-process-signature`` that allows tuning function signature introspection. @@ -121,7 +421,7 @@ New features added default HTML template. - Added new events: ``source-read``, ``env-updated``, - ``missing-reference``, ``build-finished``. + ``env-purge-doc``, ``missing-reference``, ``build-finished``. * Other changes: @@ -130,6 +430,9 @@ New features added - Added a command-line switch ``-A``: it can be used to supply additional values into the HTML templates. + - Added a command-line switch ``-C``: if it is given, no configuration + file ``conf.py`` is required. + - Added a distutils command `build_sphinx`: When Sphinx is installed, you can call ``python setup.py build_sphinx`` for projects that have Sphinx documentation, which will build the docs and place them in @@ -141,16 +444,33 @@ New features added Bugs fixed ---------- -* Support option lists in the text writer. Make sure that dashes +* #51: Escape configuration values placed in HTML templates. + +* #44: Fix small problems in HTML help index generation. + +* Fix LaTeX output for line blocks in tables. + +* #38: Fix "illegal unit" error when using pixel image widths/heights. + +* Support table captions in LaTeX output. + +* #39: Work around a bug in Jinja that caused "" to be + emitted in HTML output. + +* Fix a problem with module links not being generated in LaTeX output. + +* Fix the handling of images in different directories. + +* #29: Support option lists in the text writer. Make sure that dashes introducing long option names are not contracted to en-dashes. * Support the "scale" option for images in HTML output. -* Properly escape quotes in HTML help attribute values. +* #25: Properly escape quotes in HTML help attribute values. * Fix LaTeX build for some description environments with ``:noindex:``. -* Don't crash on weird casing of role names (like ``:Class:``). +* #24: Don't crash on uncommon casing of role names (like ``:Class:``). * Only output ANSI colors on color terminals. diff --git a/EXAMPLES b/EXAMPLES index ea0274c75..9eb0b0ce7 100644 --- a/EXAMPLES +++ b/EXAMPLES @@ -1,37 +1,71 @@ Projects using Sphinx ===================== -This is an (incomplete) 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 `_. -* Sphinx: http://sphinx.pocoo.org/ -* Python: http://docs.python.org/dev/ -* NumPy: http://mentat.za.net/numpy/refguide/ -* Matplotlib: http://matplotlib.sourceforge.net/ -* Pylons: http://docs.pylonshq.com/ -* Django: http://docs.djangoproject.com/ -* Grok: http://grok.zope.org/doc/current/ -* TurboGears: http://turbogears.org/2.0/docs/ -* Jinja: http://jinja.pocoo.org/2/documentation/ -* Cython: http://docs.cython.org/ -* F2py: http://www.f2py.org/html/ -* zc.async: http://packages.python.org/zc.async/1.5.0/ -* Mayavi: http://code.enthought.com/projects/mayavi/docs/development/html/mayavi -* Chaco: http://code.enthought.com/projects/chaco/docs/html/ -* Paver: http://www.blueskyonmars.com/projects/paver/ -* Satchmo: http://www.satchmoproject.com/docs/svn/ -* PyEphem: http://rhodesmill.org/pyephem/ -* Paste: http://pythonpaste.org/script/ -* Director: http://packages.python.org/director/ +* APSW: http://apsw.googlecode.com/svn/publish/index.html +* boostmpi: http://documen.tician.de/boostmpi/ * Calibre: http://calibre.kovidgoyal.net/user_manual/ -* PyUblas: http://tiker.net/doc/pyublas/ -* Py on Windows: http://timgolden.me.uk/python-on-windows/ -* mpmath: http://mpmath.googlecode.com/svn/trunk/doc/build/index.html -* Zope 3: e.g. http://docs.carduner.net/z3c-tutorial/ -* Glashammer: http://glashammer.org/ -* SymPy: http://docs.sympy.org/ +* 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/ +* Django: http://docs.djangoproject.com/ +* F2py: http://www.f2py.org/html/ * GeoDjango: http://geodjango.org/docs/ +* Glashammer: http://glashammer.org/ +* Grok: http://grok.zope.org/doc/current/ +* Hedge: http://documen.tician.de/hedge/ +* IFM: http://fluffybunny.memebot.com/ifm-docs/index.html +* Jinja: http://jinja.pocoo.org/2/documentation/ +* MapServer: http://mapserver.osgeo.org/ +* Matplotlib: http://matplotlib.sourceforge.net/ +* Mayavi: http://code.enthought.com/projects/mayavi/docs/development/html/mayavi +* MeshPy: http://documen.tician.de/meshpy/ * 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/ +* NumPy: http://docs.scipy.org/doc/numpy/reference/ +* ObjectListView: http://objectlistview.sourceforge.net/python +* OpenLayers: http://docs.openlayers.org/ +* 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/ +* 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/ +* PyUblas: http://documen.tician.de/pyublas/ +* Quex: http://quex.sourceforge.net/ +* Reteisi: http://docs.argolinux.org/reteisi/ +* Roundup: http://www.roundup-tracker.org/ +* Satchmo: http://www.satchmoproject.com/docs/svn/ +* Scapy: http://www.secdev.org/projects/scapy/doc/ +* 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/ +* SymPy: http://docs.sympy.org/ +* tinyTiM: http://tinytim.sourceforge.net/docs/2.0/ +* TurboGears: http://turbogears.org/2.0/docs/ +* VOR: http://www.vor-cycling.be/ +* 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/ diff --git a/LICENSE b/LICENSE index 2db70e5f1..fb2049a8a 100644 --- a/LICENSE +++ b/LICENSE @@ -1,30 +1,219 @@ -Copyright (c) 2007-2008 by the respective authors (see AUTHORS file). -All rights reserved. - -Redistribution and use in source and binary forms, with or without -modification, are permitted provided that the following conditions are -met: - - * Redistributions of source code must retain the above copyright - notice, this list of conditions and the following disclaimer. - - * Redistributions in binary form must reproduce the above - copyright notice, this list of conditions and the following - disclaimer in the documentation and/or other materials provided - with the distribution. - - * The names of the contributors may not be used to endorse or - promote products derived from this software without specific - prior written permission. - -THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +License for Sphinx +================== + +Copyright (c) 2007-2009 by the Sphinx team (see AUTHORS file). +All rights reserved. + +Redistribution and use in source and binary forms, with or without +modification, are permitted provided that the following conditions are +met: + +* Redistributions of source code must retain the above copyright + notice, this list of conditions and the following disclaimer. + +* Redistributions in binary form must reproduce the above copyright + notice, this list of conditions and the following disclaimer in the + documentation and/or other materials provided with the distribution. + +THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + + +Licenses for incorporated software +================================== + +The pgen2 package, included in this distribution under the name +sphinx.pycode.pgen2, is available in the Python 2.6 distribution under +the PSF license agreement for Python: + +---------------------------------------------------------------------- +Copyright © 2001-2008 Python Software Foundation; All Rights Reserved. + +PYTHON SOFTWARE FOUNDATION LICENSE VERSION 2 +-------------------------------------------- + +1. This LICENSE AGREEMENT is between the Python Software Foundation + ("PSF"), and the Individual or Organization ("Licensee") accessing + and otherwise using Python 2.6 software in source or binary form + and its associated documentation. + +2. Subject to the terms and conditions of this License Agreement, PSF + hereby grants Licensee a nonexclusive, royalty-free, world-wide + license to reproduce, analyze, test, perform and/or display + publicly, prepare derivative works, distribute, and otherwise use + Python 2.6 alone or in any derivative version, provided, however, + that PSF's License Agreement and PSF's notice of copyright, i.e., + "Copyright © 2001-2008 Python Software Foundation; All Rights + Reserved" are retained in Python 2.6 alone or in any derivative + version prepared by Licensee. + +3. In the event Licensee prepares a derivative work that is based on + or incorporates Python 2.6 or any part thereof, and wants to make + the derivative work available to others as provided herein, then + Licensee hereby agrees to include in any such work a brief summary + of the changes made to Python 2.6. + +4. PSF is making Python 2.6 available to Licensee on an "AS IS" basis. + PSF MAKES NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED. BY + WAY OF EXAMPLE, BUT NOT LIMITATION, PSF MAKES NO AND DISCLAIMS ANY + REPRESENTATION OR WARRANTY OF MERCHANTABILITY OR FITNESS FOR ANY + PARTICULAR PURPOSE OR THAT THE USE OF PYTHON 2.6 WILL NOT INFRINGE + ANY THIRD PARTY RIGHTS. + +5. PSF SHALL NOT BE LIABLE TO LICENSEE OR ANY OTHER USERS OF PYTHON + 2.6 FOR ANY INCIDENTAL, SPECIAL, OR CONSEQUENTIAL DAMAGES OR LOSS + AS A RESULT OF MODIFYING, DISTRIBUTING, OR OTHERWISE USING PYTHON + 2.6, OR ANY DERIVATIVE THEREOF, EVEN IF ADVISED OF THE POSSIBILITY + THEREOF. + +6. This License Agreement will automatically terminate upon a material + breach of its terms and conditions. + +7. Nothing in this License Agreement shall be deemed to create any + relationship of agency, partnership, or joint venture between PSF + and Licensee. This License Agreement does not grant permission to + use PSF trademarks or trade name in a trademark sense to endorse or + promote products or services of Licensee, or any third party. + +8. By copying, installing or otherwise using Python 2.6, Licensee + agrees to be bound by the terms and conditions of this License + Agreement. +---------------------------------------------------------------------- + +The included smartypants module, included as sphinx.util.smartypants, +is available under the following license: + +---------------------------------------------------------------------- +SmartyPants_ license:: + + Copyright (c) 2003 John Gruber + (http://daringfireball.net/) + All rights reserved. + + Redistribution and use in source and binary forms, with or without + modification, are permitted provided that the following conditions + are met: + + * Redistributions of source code must retain the above copyright + notice, this list of conditions and the following disclaimer. + + * Redistributions in binary form must reproduce the above + copyright notice, this list of conditions and the following + disclaimer in the documentation and/or other materials + provided with the distribution. + + * Neither the name "SmartyPants" nor the names of its + contributors may be used to endorse or promote products + derived from this software without specific prior written + permission. + + This software is provided by the copyright holders and + contributors "as is" and any express or implied warranties, + including, but not limited to, the implied warranties of + merchantability and fitness for a particular purpose are + disclaimed. In no event shall the copyright owner or contributors + be liable for any direct, indirect, incidental, special, + exemplary, or consequential damages (including, but not limited + to, procurement of substitute goods or services; loss of use, + data, or profits; or business interruption) however caused and on + any theory of liability, whether in contract, strict liability, or + tort (including negligence or otherwise) arising in any way out of + the use of this software, even if advised of the possibility of + such damage. + + +smartypants.py license:: + + smartypants.py is a derivative work of SmartyPants. + + Redistribution and use in source and binary forms, with or without + modification, are permitted provided that the following conditions + are met: + + * Redistributions of source code must retain the above copyright + notice, this list of conditions and the following disclaimer. + + * Redistributions in binary form must reproduce the above + copyright notice, this list of conditions and the following + disclaimer in the documentation and/or other materials + provided with the distribution. + + This software is provided by the copyright holders and + contributors "as is" and any express or implied warranties, + including, but not limited to, the implied warranties of + merchantability and fitness for a particular purpose are + disclaimed. In no event shall the copyright owner or contributors + be liable for any direct, indirect, incidental, special, + exemplary, or consequential damages (including, but not limited + to, procurement of substitute goods or services; loss of use, + data, or profits; or business interruption) however caused and on + any theory of liability, whether in contract, strict liability, or + tort (including negligence or otherwise) arising in any way out of + the use of this software, even if advised of the possibility of + such damage. +---------------------------------------------------------------------- + +The ElementTree package, included in this distribution in +test/etree13, is available under the following license: + +---------------------------------------------------------------------- +The ElementTree toolkit is + +Copyright (c) 1999-2007 by Fredrik Lundh + +By obtaining, using, and/or copying this software and/or its +associated documentation, you agree that you have read, understood, +and will comply with the following terms and conditions: + +Permission to use, copy, modify, and distribute this software and its +associated documentation for any purpose and without fee is hereby +granted, provided that the above copyright notice appears in all +copies, and that both that copyright notice and this permission notice +appear in supporting documentation, and that the name of Secret Labs +AB or the author not be used in advertising or publicity pertaining to +distribution of the software without specific, written prior +permission. + +SECRET LABS AB AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO +THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANT- ABILITY +AND FITNESS. IN NO EVENT SHALL SECRET LABS AB OR THE AUTHOR BE LIABLE +FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT +OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +---------------------------------------------------------------------- + +The included JQuery JavaScript library is available under the MIT +license: + +---------------------------------------------------------------------- +Copyright (c) 2008 John Resig, http://jquery.com/ + +Permission is hereby granted, free of charge, to any person obtaining +a copy of this software and associated documentation files (the +"Software"), to deal in the Software without restriction, including +without limitation the rights to use, copy, modify, merge, publish, +distribute, sublicense, and/or sell copies of the Software, and to +permit persons to whom the Software is furnished to do so, subject to +the following conditions: + +The above copyright notice and this permission notice shall be +included in all copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, +EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND +NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE +LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION +OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION +WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. +---------------------------------------------------------------------- diff --git a/MANIFEST.in b/MANIFEST.in index d87a881ef..e1f0b575c 100644 --- a/MANIFEST.in +++ b/MANIFEST.in @@ -12,11 +12,11 @@ include sphinx-build.py include sphinx-quickstart.py recursive-include sphinx/texinputs * -recursive-include sphinx/templates *.html *.xml -recursive-include sphinx/static * +recursive-include sphinx/themes * recursive-include sphinx/locale * recursive-include tests * recursive-include utils * +include sphinx/pycode/Grammar.txt recursive-include doc * prune doc/_build diff --git a/Makefile b/Makefile index 721986b2f..108ed96dc 100644 --- a/Makefile +++ b/Makefile @@ -7,7 +7,9 @@ export PYTHONPATH = $(shell echo "$$PYTHONPATH"):./sphinx all: clean-pyc check test check: - @$(PYTHON) utils/check_sources.py -i sphinx/style/jquery.js sphinx + @$(PYTHON) utils/check_sources.py -i sphinx/style/jquery.js \ + -i sphinx/pycode/pgen2 -i sphinx/util/smartypants.py \ + -i doc/_build -i ez_setup.py -i tests/path.py . clean: clean-pyc clean-patchfiles @@ -28,3 +30,6 @@ reindent: test: @cd tests; $(PYTHON) run.py -d -m '^[tT]est' $(TEST) + +covertest: + @cd tests; $(PYTHON) run.py -d -m '^[tT]est' --with-coverage --cover-package=sphinx $(TEST) diff --git a/README b/README index df09bc001..bb2dea9d6 100644 --- a/README +++ b/README @@ -1,3 +1,5 @@ +.. -*- restructuredtext -*- + ================= README for Sphinx ================= @@ -17,9 +19,9 @@ Reading the docs After installing:: cd doc - mkdir -p _build/html sphinx-build . _build/html - browser _build/index.html + +Then, direct your browser to ``_build/html/index.html``. Or read them online at . @@ -27,4 +29,4 @@ Or read them online at . Contributing ============ -Send wishes, comments, patches, etc. to georg@python.org. +Send wishes, comments, patches, etc. to sphinx-dev@googlegroups.com. diff --git a/babel.cfg b/babel.cfg index 5f5188b18..e53a462d3 100644 --- a/babel.cfg +++ b/babel.cfg @@ -1,6 +1,4 @@ -[extractors] -jinja = sphinx._jinja.babel_extract [python: **.py] -[jinja: **/templates/**.html] -[jinja: **/templates/**.xml] +[jinja2: **/templates/**.html] +[jinja2: **/templates/**.xml] [javascript: **.js] diff --git a/doc/Makefile b/doc/Makefile index cb5fc645c..07cee7449 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -11,12 +11,13 @@ PAPEROPT_letter = -D latex_paper_size=letter ALLSPHINXOPTS = -d _build/doctrees $(PAPEROPT_$(PAPER)) \ $(SPHINXOPTS) . -.PHONY: help clean html web htmlhelp latex changes linkcheck +.PHONY: help clean html dirhtml pickle htmlhelp qthelp latex changes linkcheck doctest help: @echo "Please use \`make ' where is one of" @echo " html to make standalone HTML files" - @echo " web to make files usable by Sphinx.web" + @echo " dirhtml to make HTML files called index.html in directories" + @echo " pickle to make pickle files" @echo " htmlhelp to make HTML files and a HTML help project" @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" @echo " changes to make an overview over all changed/added/deprecated items" @@ -31,13 +32,21 @@ html: @echo @echo "Build finished. The HTML pages are in _build/html." +dirhtml: + mkdir -p _build/dirhtml _build/doctrees + $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) _build/dirhtml + @echo + @echo "Build finished. The HTML pages are in _build/dirhtml." + +text: + mkdir -p _build/text _build/doctrees + $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) _build/text + @echo + @echo "Build finished." + pickle: mkdir -p _build/pickle _build/doctrees $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) _build/pickle - @echo - @echo "Build finished; now you can run" - @echo " python -m sphinx.web _build/pickle" - @echo "to start the server." htmlhelp: mkdir -p _build/htmlhelp _build/doctrees @@ -46,6 +55,16 @@ htmlhelp: @echo "Build finished; now you can run HTML Help Workshop with the" \ ".hhp project file in _build/htmlhelp." +qthelp: + mkdir -p _build/qthelp _build/doctrees + $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) _build/qthelp + @echo + @echo "Build finished; now you can run qcollectiongenerator with the" \ + ".qhcp project file in build/qthelp." + @echo "# qcollectiongenerator _build/qthelp/Sphinx.qhcp" + @echo "To view the help collection:" + @echo "# assistant -collectionFile _build/qthelp/Sphinx.qhc" + latex: mkdir -p _build/latex _build/doctrees $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) _build/latex diff --git a/doc/_templates/index.html b/doc/_templates/index.html index dd34b6343..1c399f926 100644 --- a/doc/_templates/index.html +++ b/doc/_templates/index.html @@ -3,17 +3,22 @@ {% block body %}

    Welcome

    +
    +

    What users say:

    +

    “Cheers for a great tool that actually makes programmers want + to write documentation!”

    +
    +

    Sphinx is a tool that makes it easy to create intelligent and beautiful - documentation for Python projects, written by Georg Brandl and licensed - under the BSD license.

    + documentation, written by Georg Brandl and licensed under the BSD license.

    It was originally created to translate the - new Python documentation, but has now been cleaned up in the hope that - it will be useful to many other projects. (Of course, this site is also - created from reStructuredText sources using Sphinx!) + new Python documentation, and it has excellent support for the documentation + of Python projects, but other documents can be written with it too. Of course, + this site is also created from reStructuredText sources using Sphinx!

    - Although it is still under constant development, the following features are + It is still under constant development, and the following features are already present, work fine and can be seen “in action” in the Python docs:

    @@ -76,5 +81,5 @@

    The code can be found in a Mercurial repository, at http://bitbucket.org/birkenfeld/sphinx/.

    - + {% endblock %} diff --git a/doc/_templates/indexsidebar.html b/doc/_templates/indexsidebar.html index 01d94d124..c738aeec2 100644 --- a/doc/_templates/indexsidebar.html +++ b/doc/_templates/indexsidebar.html @@ -10,7 +10,7 @@

    Current version: {{ version }}

    Get Sphinx from the Python Package Index, or install it with:

    -
    easy_install Sphinx
    +
    easy_install -U Sphinx
    {% endif %}

    Questions? Suggestions?

    @@ -23,4 +23,4 @@ Index, or install it with:

    or come to the #python-docs channel on FreeNode.

    You can also open an issue at the - tracker.

    + tracker.

    diff --git a/doc/_templates/layout.html b/doc/_templates/layout.html index 2cc154504..080c0935a 100644 --- a/doc/_templates/layout.html +++ b/doc/_templates/layout.html @@ -1,17 +1,12 @@ {% extends "!layout.html" %} {% block rootrellink %} -
  • Sphinx home | 
    • -
  • Documentation »
    • +
  • Sphinx home | 
    • +
  • Documentation»
    • {% endblock %} -{% block relbar1 %} +{% block header %}
    Sphinx logo
    -{{ super() }} {% endblock %} - -{# put the sidebar before the body #} -{% block sidebar1 %}{{ sidebar() }}{% endblock %} -{% block sidebar2 %}{% endblock %} diff --git a/doc/builders.rst b/doc/builders.rst index 21780806f..bee0094c6 100644 --- a/doc/builders.rst +++ b/doc/builders.rst @@ -3,7 +3,7 @@ Available builders ================== -.. module:: sphinx.builder +.. module:: sphinx.builders :synopsis: Available built-in builder classes. These are the built-in Sphinx builders. More builders can be added by @@ -13,6 +13,7 @@ The builder's "name" must be given to the **-b** command-line option of :program:`sphinx-build` to select a builder. +.. module:: sphinx.builders.html .. class:: StandaloneHTMLBuilder This is the standard HTML builder. Its output is a directory with HTML @@ -22,13 +23,106 @@ The builder's "name" must be given to the **-b** command-line option of Its name is ``html``. +.. class:: DirectoryHTMLBuilder + + This is a subclass of the standard HTML builder. Its output is a directory + with HTML files, where each file is called ``index.html`` and placed in a + subdirectory named like its page name. For example, the document + ``markup/rest.rst`` will not result in an output file ``markup/rest.html``, + but ``markup/rest/index.html``. When generating links between pages, the + ``index.html`` is omitted, so that the URL would look like ``markup/rest/``. + + Its name is ``dirhtml``. + + .. versionadded:: 0.6 + .. class:: HTMLHelpBuilder This builder produces the same output as the standalone HTML builder, but also generates HTML Help support files that allow the Microsoft HTML Help Workshop to compile them into a CHM file. - Its name is ``htmlhelp``. + Its name is ``htmlhelp``. + +.. module:: sphinx.builders.latex +.. class:: LaTeXBuilder + + This builder produces a bunch of LaTeX files in the output directory. You + have to specify which documents are to be included in which LaTeX files via + the :confval:`latex_documents` configuration value. There are a few + configuration values that customize the output of this builder, see the + chapter :ref:`latex-options` for details. + + .. note:: + + The produced LaTeX file uses several LaTeX packages that may not be + present in a "minimal" TeX distribution installation. For TeXLive, + the following packages need to be installed: + + * latex-recommended + * latex-extra + * fonts-recommended + + Its name is ``latex``. + +.. module:: sphinx.builders.text +.. class:: TextBuilder + + This builder produces a text file for each reST file -- this is almost the + same as the reST source, but with much of the markup stripped for better + readability. + + Its name is ``text``. + + .. versionadded:: 0.4 + +.. currentmodule:: sphinx.builders.html +.. class:: SerializingHTMLBuilder + + This builder uses a module that implements the Python serialization API + (`pickle`, `simplejson`, `phpserialize`, and others) to dump the generated + HTML documentation. The pickle builder is a subclass of it. + + A concreate subclass of this builder serializing to the `PHP serialization`_ + format could look like this:: + + import phpserialize + + class PHPSerializedBuilder(SerializingHTMLBuilder): + name = 'phpserialized' + implementation = phpserialize + out_suffix = '.file.phpdump' + globalcontext_filename = 'globalcontext.phpdump' + searchindex_filename = 'searchindex.phpdump' + + .. _PHP serialization: http://pypi.python.org/pypi/phpserialize + + .. attribute:: implementation + + A module that implements `dump()`, `load()`, `dumps()` and `loads()` + functions that conform to the functions with the same names from the + pickle module. Known modules implementing this interface are + `simplejson` (or `json` in Python 2.6), `phpserialize`, `plistlib`, + and others. + + .. attribute:: out_suffix + + The suffix for all regular files. + + .. attribute:: globalcontext_filename + + The filename for the file that contains the "global context". This + is a dict with some general configuration values such as the name + of the project. + + .. attribute:: searchindex_filename + + The filename for the search index Sphinx generates. + + + See :ref:`serialization-details` for details about the output format. + + .. versionadded:: 0.5 .. class:: PickleHTMLBuilder @@ -58,73 +152,7 @@ The builder's "name" must be given to the **-b** command-line option of .. versionadded:: 0.5 -.. class:: LaTeXBuilder - - This builder produces a bunch of LaTeX files in the output directory. You - have to specify which documents are to be included in which LaTeX files via - the :confval:`latex_documents` configuration value. There are a few - configuration values that customize the output of this builder, see the - chapter :ref:`latex-options` for details. - - Its name is ``latex``. - -.. class:: TextBuilder - - This builder produces a text file for each reST file -- this is almost the - same as the reST source, but with much of the markup stripped for better - readability. - - Its name is ``text``. - - .. versionadded:: 0.4 - -.. class:: SerializingHTMLBuilder - - This builder uses a module that implements the Python serialization API - (`pickle`, `simplejson`, `phpserialize`, and others) to dump the generated - HTML documentation. The pickle builder is a subclass of it. - - A concreate subclass of this builder serializing to the `PHP serialization`_ - format could look like this:: - - import phpserialize - - class PHPSerializedBuilder(SerializingHTMLBuilder): - name = 'phpserialized' - implementation = phpserialize - out_suffix = '.file.phpdump' - globalcontext_filename = 'globalcontext.phpdump' - searchindex_filename = 'searchindex.phpdump' - - .. _PHP serialization: http://pypi.python.org/pypi/phpserialize - - .. attribute:: implementation - - A module that implements `dump()`, `load()`, `dumps()` and `loads()` - functions that conform to the functions with the same names from the - pickle module. Known modules implementing this interface are - `simplejson` (or `json` in Python 2.6), `phpserialize`, `plistlib`, - and others. - - .. attribute:: out_suffix - - The suffix for all regular files. - - .. attribute:: globalcontext_filename - - The filename for the file that contains the "global context". This - is a dict with some general configuration values such as the name - of the project. - - .. attribute:: searchindex_filename - - The filename for the search index Sphinx generates. - - - See :ref:`serialization-details` for details about the output format. - - .. versionadded:: 0.5 - +.. module:: sphinx.builders.changes .. class:: ChangesBuilder This builder produces an HTML overview of all :dir:`versionadded`, @@ -134,6 +162,7 @@ The builder's "name" must be given to the **-b** command-line option of Its name is ``changes``. +.. module:: sphinx.builders.linkcheck .. class:: CheckExternalLinksBuilder This builder scans all documents for external links, tries to open them with diff --git a/doc/concepts.rst b/doc/concepts.rst index ca7aaf7c4..e6d5fa026 100644 --- a/doc/concepts.rst +++ b/doc/concepts.rst @@ -16,6 +16,9 @@ directory`, the extension is stripped, and path separators are converted to slashes. All values, parameters and suchlike referring to "documents" expect such a document name. +Examples for document names are ``index``, ``library/zipfile``, or +``reference/datamodel/types``. Note that there is no leading slash. + The TOC tree ------------ @@ -55,22 +58,37 @@ tables of contents. The ``toctree`` directive is the central element. ``strings`` and so forth, and it knows that they are children of the shown document, the library index. From this information it generates "next chapter", "previous chapter" and "parent chapter" links. - + Document titles in the :dir:`toctree` will be automatically read from the - title of the referenced document. If that isn't what you want, you can give - the specify an explicit title and target using a similar syntax to reST + title of the referenced document. If that isn't what you want, you can + specify an explicit title and target using a similar syntax to reST hyperlinks (and Sphinx's :ref:`cross-referencing syntax `). This looks like:: - + .. toctree:: - + intro All about strings datatypes - + The second line above will link to the ``strings`` document, but will use the title "All about strings" instead of the title of the ``strings`` document. + You can also add external links, by giving an HTTP URL instead of a document + name. + + If you want to have section numbers even in HTML output, give the toctree a + ``numbered`` flag option. For example:: + + .. toctree:: + :numbered: + + foo + bar + + Numbering then starts at the heading of ``foo``. Sub-toctrees are + automatically numbered (don't give the ``numbered`` flag to those). + You can use "globbing" in toctree directives, by giving the ``glob`` flag option. All entries are then matched against the list of available documents, and matches are inserted into the list alphabetically. Example:: @@ -85,7 +103,24 @@ tables of contents. The ``toctree`` directive is the central element. This includes first all documents whose names start with ``intro``, then all documents in the ``recipe`` folder, then all remaining documents (except the one containing the directive, of course.) [#]_ - + + The special entry name ``self`` stands for the document containing the + toctree directive. This is useful if you want to generate a "sitemap" from + the toctree. + + You can also give a "hidden" option to the directive, like this:: + + .. toctree:: + :hidden: + + doc_1 + doc_2 + + This will still notify Sphinx of the document hierarchy, but not insert links + into the document at the location of the directive -- this makes sense if you + intend to insert these links yourself, in a different style, or in the HTML + sidebar. + 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 @@ -100,6 +135,10 @@ tables of contents. The ``toctree`` directive is the central element. .. versionchanged:: 0.3 Added "globbing" option. + .. versionchanged:: 0.6 + Added "numbered" and "hidden" options as well as external links and + support for "self" references. + Special names ------------- diff --git a/doc/conf.py b/doc/conf.py index ca30ad91d..e1a48aa20 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -1,27 +1,12 @@ # -*- coding: utf-8 -*- # -# Sphinx documentation build configuration file, created by -# sphinx-quickstart.py on Sat Mar 8 21:47:50 2008. -# -# This file is execfile()d with the current directory set to its containing dir. -# -# The contents of this file are pickled, so don't put values in the namespace -# that aren't pickleable (module imports are okay, they're removed automatically). -# -# All configuration values have a default value; values that are commented out -# serve to show the default value. +# Sphinx documentation build configuration file import sys, os, re -# If your extensions are in another directory, add it here. -#sys.path.append(os.path.dirname(__file__)) - -# General configuration -# --------------------- - # Add any Sphinx extension module names here, as strings. They can be extensions # coming with Sphinx (named 'sphinx.addons.*') or your custom ones. -extensions = ['sphinx.ext.autodoc', 'sphinx.ext.doctest'] +extensions = ['sphinx.ext.autodoc', 'sphinx.ext.doctest', 'sphinx.ext.todo'] # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] @@ -34,46 +19,22 @@ master_doc = 'contents' # General substitutions. project = 'Sphinx' -copyright = '2008, Georg Brandl' +copyright = '2007-2009, Georg Brandl' # The default replacements for |version| and |release|, also used in various # other places throughout the built documents. -# -# The short X.Y version. import sphinx version = sphinx.__released__ -# The full version, including alpha/beta/rc tags. release = version -# There are two options for replacing |today|: either, you set today to some -# non-false value, then it is used: -#today = '' -# 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 = [] - -# If true, '()' will be appended to :func: etc. cross-reference text. -#add_function_parentheses = True - -# If true, the current module name will be prepended to all description -# unit titles (such as .. function::). -#add_module_names = True - +# Show author directives in the output. show_authors = True -# The name of the Pygments (syntax highlighting) style to use. -pygments_style = 'friendly' +# The HTML template theme. +html_theme = 'sphinxdoc' - -# Options for HTML output -# ----------------------- - -# The style sheet to use for HTML and HTML Help pages. A file of that name -# must exist either in Sphinx' static/ path, or in one of the custom paths -# given in html_static_path. -html_style = 'sphinxdoc.css' +# A list of ignored prefixes names for module index sorting. +modindex_common_prefix = ['sphinx.'] # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, @@ -84,10 +45,6 @@ html_static_path = ['_static'] # using the given strftime format. html_last_updated_fmt = '%b %d, %Y' -# If true, SmartyPants will be used to convert quotes and dashes to -# typographically correct entities. -#html_use_smartypants = True - # Content template for the index page. html_index = 'index.html' @@ -98,44 +55,30 @@ html_sidebars = {'index': 'indexsidebar.html'} # templates. html_additional_pages = {'index': 'index.html'} -# If true, the reST sources are included in the HTML build as _sources/. -#html_copy_source = True - +# Generate an OpenSearch description with that URL as the base. html_use_opensearch = 'http://sphinx.pocoo.org' # Output file base name for HTML help builder. htmlhelp_basename = 'Sphinxdoc' - -# Options for LaTeX output -# ------------------------ - -# The paper size ('letter' or 'a4'). -#latex_paper_size = 'letter' - -# The font size ('10pt', '11pt' or '12pt'). -#latex_font_size = '10pt' - # Grouping the document tree into LaTeX files. List of tuples -# (source start file, target name, title, author, document class [howto/manual]). +# (source start file, target name, title, author, documentclass [howto/manual]). latex_documents = [('contents', 'sphinx.tex', 'Sphinx Documentation', 'Georg Brandl', 'manual', 1)] +# Add our logo to the LaTeX file. latex_logo = '_static/sphinx.png' -#latex_use_parts = True - # Additional stuff for the LaTeX preamble. latex_elements = { 'fontpkg': '\\usepackage{palatino}' } -# Documents to append as an appendix to all manuals. -#latex_appendices = [] +# Put TODOs into the output. +todo_include_todos = True -# Extension interface -# ------------------- +# -- Extension interface ------------------------------------------------------- from sphinx import addnodes @@ -182,7 +125,9 @@ def parse_event(env, sig, signode): def setup(app): from sphinx.ext.autodoc import cut_lines app.connect('autodoc-process-docstring', cut_lines(4, what=['module'])) - app.add_description_unit('directive', 'dir', 'pair: %s; directive', parse_directive) + app.add_description_unit('directive', 'dir', 'pair: %s; directive', + parse_directive) app.add_description_unit('role', 'role', 'pair: %s; role', parse_role) - app.add_description_unit('confval', 'confval', 'pair: %s; configuration value') + app.add_description_unit('confval', 'confval', + 'pair: %s; configuration value') app.add_description_unit('event', 'event', 'pair: %s; event', parse_event) diff --git a/doc/config.rst b/doc/config.rst index ed5133672..54303bbb0 100644 --- a/doc/config.rst +++ b/doc/config.rst @@ -22,8 +22,8 @@ Important points to note: * The term "fully-qualified name" refers to a string that names an importable Python object inside a module; for example, the FQN - ``"sphinx.builder.Builder"`` means the ``Builder`` class in the - ``sphinx.builder`` module. + ``"sphinx.builders.Builder"`` means the ``Builder`` class in the + ``sphinx.builders`` module. * Remember that document names use ``/`` as the path separator and don't contain the file name extension. @@ -38,6 +38,11 @@ Important points to note: delete them from the namespace with ``del`` if appropriate. Modules are removed automatically, so you don't need to ``del`` your imports after use. +* There is a special object named ``tags`` available in the config file. + It can be used to query and change the tags (see :ref:`tags`). Use + ``tags.has('tag')`` to query, ``tags.add('tag')`` and ``tags.remove('tag')`` + to change. + General configuration --------------------- @@ -45,7 +50,7 @@ General configuration .. confval:: extensions A list of strings that are module names of Sphinx extensions. These can be - extensions coming with Sphinx (named ``sphinx.addons.*``) or custom ones. + extensions coming with Sphinx (named ``sphinx.ext.*``) or custom ones. Note that you can extend :data:`sys.path` within the conf file if your extensions live in another directory -- but make sure you use absolute paths. @@ -76,7 +81,7 @@ General configuration .. versionadded:: 0.5 Previously, Sphinx accepted only UTF-8 encoded sources. - + .. confval:: master_doc The document name of the "master" document, that is, the document that @@ -131,18 +136,35 @@ General configuration .. confval:: templates_path A list of paths that contain extra templates (or templates that overwrite - builtin templates). Relative paths are taken as relative to the - configuration directory. + builtin/theme-specific templates). Relative paths are taken as relative to + the configuration directory. .. confval:: template_bridge A string with the fully-qualified name of a callable (or simply a class) that returns an instance of :class:`~sphinx.application.TemplateBridge`. This instance is then used to render HTML documents, and possibly the output of - other builders (currently the changes builder). + other builders (currently the changes builder). (Note that the template + bridge must be made theme-aware if HTML themes are to be used.) + +.. confval:: rst_epilog + + .. index:: pair: global; substitutions + + A string of reStructuredText that will be included at the end of every source + file that is read. This is the right place to add substitutions that should + be available in every file. An example:: + + rst_epilog = """ + .. |psf| replace:: Python Software Foundation + """ + + .. versionadded:: 0.6 .. confval:: default_role + .. index:: default; role + The name of a reST role (builtin or Sphinx extension) to use as the default role, that is, for text marked up ```like this```. This can be set to ``'obj'`` to make ```filter``` a cross-reference to the function "filter". @@ -164,9 +186,19 @@ General configuration .. versionadded:: 0.5 +.. confval:: modindex_common_prefix + + A list of prefixes that are ignored for sorting the module index (e.g., + if this is set to ``['foo.']``, then ``foo.bar`` is shown under ``B``, not + ``F``). This can be handy if you document a project that consists of a single + package. Works only for the HTML builder currently. Default is ``[]``. + + .. versionadded:: 0.6 + + Project information ------------------- - + .. confval:: project The documented project's name. @@ -203,8 +235,16 @@ Project information * ``cs`` -- Czech * ``de`` -- German * ``en`` -- English + * ``es`` -- Spanish + * ``fi`` -- Finnish * ``fr`` -- French + * ``it`` -- Italian + * ``nl`` -- Dutch * ``pl`` -- Polish + * ``pt_BR`` -- Brazilian Portuguese + * ``sl`` -- Slovenian + * ``uk_UA`` -- Ukrainian + * ``zh_TW`` -- Traditional Chinese .. confval:: today today_fmt @@ -227,7 +267,7 @@ Project information :ref:`code-examples` for more details. .. versionadded:: 0.5 - + .. confval:: pygments_style The style name to use for Pygments highlighting of source code. Default is @@ -255,6 +295,13 @@ Project information A boolean that decides whether :dir:`moduleauthor` and :dir:`sectionauthor` directives produce any output in the built files. +.. confval:: trim_footnote_reference_space + + Trim spaces before footnote references that are necessary for the reST parser + to recognize the footnote, but do not look too nice in the output. + + .. versionadded:: 0.6 + .. _html-options: @@ -264,6 +311,37 @@ Options for HTML output These options influence HTML as well as HTML Help output, and other builders that use Sphinx' HTMLWriter class. +.. confval:: html_theme + + The "theme" that the HTML output should use. See the :doc:`section about + theming `. The default is ``'default'``. + + .. versionadded:: 0.6 + +.. confval:: html_theme_options + + A dictionary of options that influence the look and feel of the selected + theme. These are theme-specific. For the options understood by the builtin + themes, see :ref:`this section `. + + .. versionadded:: 0.6 + +.. confval:: html_theme_path + + A list of paths that contain custom themes, either as subdirectories or as + zip files. Relative paths are taken as relative to the configuration + directory. + + .. versionadded:: 0.6 + +.. confval:: html_style + + The style sheet to use for HTML pages. A file of that name must exist either + in Sphinx' :file:`static/` path, or in one of the custom paths given in + :confval:`html_static_path`. Default is the stylesheet given by the selected + theme. If you only want to add or override a few things compared to the + theme's stylesheet, use CSS ``@import`` to import the theme's stylesheet. + .. confval:: html_title The "title" for HTML documentation generated with Sphinx' own templates. @@ -280,12 +358,6 @@ that use Sphinx' HTMLWriter class. .. versionadded:: 0.4 -.. confval:: html_style - - The style sheet to use for HTML pages. A file of that name must exist either - in Sphinx' :file:`static/` path, or in one of the custom paths given in - :confval:`html_static_path`. Default is ``'default.css'``. - .. confval:: html_logo If given, this must be the name of an image file that is the logo of the @@ -309,8 +381,8 @@ that use Sphinx' HTMLWriter class. A list of paths that contain custom static files (such as style sheets or script files). Relative paths are taken as relative to the configuration - directory. They are copied to the output directory after the builtin static - files, so a file named :file:`default.css` will overwrite the builtin + directory. They are copied to the output directory after the theme's static + files, so a file named :file:`default.css` will overwrite the theme's :file:`default.css`. .. versionchanged:: 0.4 @@ -327,6 +399,15 @@ that use Sphinx' HTMLWriter class. If true, *SmartyPants* will be used to convert quotes and dashes to typographically correct entities. Default: ``True``. +.. confval:: html_add_permalinks + + If true, Sphinx will add "permalinks" for each heading and description + environment as paragraph signs that become visible when the mouse hovers over + them. Default: ``True``. + + .. versionadded:: 0.6 + Previously, this was always activated. + .. confval:: html_sidebars Custom sidebar templates, must be a dictionary that maps document names to @@ -388,6 +469,19 @@ that use Sphinx' HTMLWriter class. If true, the reST sources are included in the HTML build as :file:`_sources/{name}`. The default is ``True``. + .. warning:: + + If this config value is set to ``False``, the JavaScript search function + will only display the titles of matching documents, and no excerpt from + the matching contents. + +.. confval:: html_show_sourcelink + + If true (and :confval:`html_copy_source` is true as well), links to the + reST sources will be added to the sidebar. The default is ``True``. + + .. versionadded:: 0.6 + .. confval:: html_use_opensearch If nonempty, an `OpenSearch ` description file will be @@ -404,10 +498,18 @@ that use Sphinx' HTMLWriter class. .. versionadded:: 0.4 +.. confval:: html_link_suffix + + Suffix for generated links to HTML files. The default is whatever + :confval:`html_file_suffix` is set to; it can be set differently (e.g. to + support different web server setups). + + .. versionadded:: 0.6 + .. confval:: html_translator_class A string with the fully-qualified name of a HTML Translator class, that is, a - subclass of Sphinx' :class:`~sphinx.htmlwriter.HTMLTranslator`, that is used + subclass of Sphinx' :class:`~sphinx.writers.html.HTMLTranslator`, that is used to translate document trees to HTML. Default is ``None`` (use the builtin translator). @@ -491,7 +593,7 @@ These options influence LaTeX output. avoid interpretation as escape sequences. * Keys that you may want to override include: - + ``'papersize'`` Paper size option of the document class (``'a4paper'`` or ``'letterpaper'``), default ``'letterpaper'``. @@ -515,9 +617,9 @@ These options influence LaTeX output. Additional preamble content, default empty. ``'footer'``` Additional footer content (before the indices), default empty. - + * Keys that don't need be overridden unless in special cases are: - + ``'inputenc'`` "inputenc" package inclusion, default ``'\\usepackage[utf8]{inputenc}'``. @@ -534,9 +636,9 @@ These options influence LaTeX output. "printindex" call, the last thing in the file, default ``'\\printindex'``. Override if you want to generate the index differently or append some content after the index. - + * Keys that are set by other options and therefore should not be overridden are: - + ``'docclass'`` ``'classoptions'`` ``'title'`` @@ -549,7 +651,20 @@ These options influence LaTeX output. ``'makemodindex'`` ``'shorthandoff'`` ``'printmodindex'`` - + +.. confval:: latex_additional_files + + A list of file names, relative to the configuration directory, to copy to the + build directory when building LaTeX output. This is useful to copy files + that Sphinx doesn't copy automatically, e.g. if they are referenced in custom + LaTeX added in ``latex_elements``. Image files that are referenced in source + files (e.g. via ``.. image::``) are copied automatically. + + You have to make sure yourself that the filenames don't collide with those of + any automatically copied files. + + .. versionadded:: 0.6 + .. confval:: latex_preamble Additional LaTeX markup for the preamble. diff --git a/doc/contents.rst b/doc/contents.rst index 6ddbcbcbb..1f3860ea8 100644 --- a/doc/contents.rst +++ b/doc/contents.rst @@ -12,9 +12,11 @@ Sphinx documentation contents markup/index builders config + theming templating extensions - + + faq glossary changes examples diff --git a/doc/ext/appapi.rst b/doc/ext/appapi.rst index bb8ff7dd4..fba1d9457 100644 --- a/doc/ext/appapi.rst +++ b/doc/ext/appapi.rst @@ -13,22 +13,31 @@ the following public API: .. method:: Sphinx.add_builder(builder) Register a new builder. *builder* must be a class that inherits from - :class:`~sphinx.builder.Builder`. + :class:`~sphinx.builders.Builder`. -.. method:: Sphinx.add_config_value(name, default, rebuild_env) +.. method:: Sphinx.add_config_value(name, default, rebuild) Register a configuration value. This is necessary for Sphinx to recognize new values and set default values accordingly. The *name* should be prefixed with the extension name, to avoid clashes. The *default* value can be any - Python object. The boolean value *rebuild_env* must be ``True`` if a change - in the setting only takes effect when a document is parsed -- this means that - the whole environment must be rebuilt. + Python object. The string value *rebuild* must be one of those values: + + * ``'env'`` if a change in the setting only takes effect when a document is + parsed -- this means that the whole environment must be rebuilt. + * ``'html'`` if a change in the setting needs a full rebuild of HTML + documents. + * ``''`` if a change in the setting will not need any special rebuild. .. versionchanged:: 0.4 If the *default* value is a callable, it will be called with the config object as its argument in order to get the default value. This can be used to implement config values whose default depends on other values. + .. versionchanged:: 0.6 + Changed *rebuild* from a simple boolean (equivalent to ``''`` or + ``'env'``) to a string. However, booleans are still accepted and + converted internally. + .. method:: Sphinx.add_event(name) Register an event called *name*. @@ -45,12 +54,12 @@ the following public API: :exc:`docutils.nodes.SkipNode`. Example:: class math(docutils.nodes.Element) - + def visit_math_html(self, node): self.body.append(self.starttag(node, 'math')) def depart_math_html(self, node): self.body.append('') - + app.add_node(math, html=(visit_math_html, depart_math_html)) Obviously, translators for which you don't specify visitor methods will choke @@ -59,16 +68,42 @@ the following public API: .. versionchanged:: 0.5 Added the support for keyword arguments giving visit functions. -.. method:: Sphinx.add_directive(name, cls, content, arguments, **options) +.. method:: Sphinx.add_directive(name, func, content, arguments, **options) + Sphinx.add_directive(name, directiveclass) Register a Docutils directive. *name* must be the prospective directive - name, *func* the directive function for details about the signature and - return value. *content*, *arguments* and *options* are set as attributes on - the function and determine whether the directive has content, arguments and - options, respectively. For their exact meaning, please consult the Docutils - documentation. + name. There are two possible ways to write a directive: - .. XXX once we target docutils 0.5, update this + * In the docutils 0.4 style, *func* is the directive function. *content*, + *arguments* and *options* are set as attributes on the function and + determine whether the directive has content, arguments and options, + respectively. + + * In the docutils 0.5 style, *directiveclass* is the directive class. It + must already have attributes named *has_content*, *required_arguments*, + *optional_arguments*, *final_argument_whitespace* and *option_spec* that + correspond to the options for the function way. See `the Docutils docs + `_ for + details. + + The directive class normally must inherit from the class + ``docutils.parsers.rst.Directive``. When writing a directive for usage in + a Sphinx extension, you inherit from ``sphinx.util.compat.Directive`` + instead which does the right thing even on docutils 0.4 (which doesn't + support directive classes otherwise). + + For example, the (already existing) :dir:`literalinclude` directive would be + added like this:: + + from docutils.parsers.rst import directives + add_directive('literalinclude', literalinclude_directive, + content = 0, arguments = (1, 0, 0), + linenos = directives.flag, + language = direcitves.unchanged, + encoding = directives.encoding) + + .. versionchanged:: 0.6 + Docutils 0.5-style directive classes are now supported. .. method:: Sphinx.add_role(name, role) @@ -76,6 +111,13 @@ the following public API: source, *role* the role function (see the `Docutils documentation `_ on details). +.. method:: Sphinx.add_generic_role(name, nodeclass) + + Register a Docutils role that does nothing but wrap its contents in the + node given by *nodeclass*. + + .. versionadded:: 0.6 + .. method:: Sphinx.add_description_unit(directivename, rolename, indextemplate='', parse_node=None, ref_nodeclass=None) This method is a very convenient way to add a new type of information that @@ -157,7 +199,32 @@ the following public API: :confval:`the docs for the config value `. .. versionadded:: 0.5 - + +.. method:: Sphinx.add_lexer(alias, lexer) + + Use *lexer*, which must be an instance of a Pygments lexer class, to + highlight code blocks with the given language *alias*. + + .. versionadded:: 0.6 + +.. method:: Sphinx.add_autodocumenter(cls) + + Add *cls* as a new documenter class for the :mod:`sphinx.ext.autodoc` + extension. It must be a subclass of :class:`sphinx.ext.autodoc.Documenter`. + This allows to auto-document new types of objects. See the source of the + autodoc module for examples on how to subclass :class:`Documenter`. + + .. versionadded:: 0.6 + +.. method:: Sphinx.add_autodoc_attrgetter(type, getter) + + Add *getter*, which must be a function with an interface compatible to the + :func:`getattr` builtin, as the autodoc attribute getter for objects that are + instances of *type*. All cases where autodoc needs to get an attribute of a + type are then handled by this function instead of :func:`getattr`. + + .. versionadded:: 0.6 + .. method:: Sphinx.connect(event, callback) Register *callback* to be called when *event* is emitted. For details on @@ -208,14 +275,31 @@ registered event handlers. Emitted when the builder object has been created. It is available as ``app.builder``. +.. event:: env-purge-doc (app, env, docname) + + Emitted when all traces of a source file should be cleaned from the + environment, that is, if the source file is removed or before it is freshly + read. This is for extensions that keep their own caches in attributes of the + environment. + + For example, there is a cache of all modules on the environment. When a + source file has been changed, the cache's entries for the file are cleared, + since the module declarations could have been removed from the file. + + .. versionadded:: 0.5 + .. event:: source-read (app, docname, source) Emitted when a source file has been read. The *source* argument is a list whose single element is the contents of the source file. You can process the contents and replace this item to implement source-level transformations. + For example, if you want to use ``$`` signs to delimit inline math, like in + LaTeX, you can use a regular expression to replace ``$...$`` by + ``:math:`...```. + .. versionadded:: 0.5 - + .. event:: doctree-read (app, doctree) Emitted when a doctree has been parsed and read by the environment, and is @@ -237,11 +321,15 @@ registered event handlers. future reference and should be a child of the returned reference node. .. versionadded:: 0.5 - + .. event:: doctree-resolved (app, doctree, docname) Emitted when a doctree has been "resolved" by the environment, that is, all - references have been resolved and TOCs have been inserted. + references have been resolved and TOCs have been inserted. The *doctree* can + be modified in place. + + Here is the place to replace custom nodes that don't have visitor methods in + the writers, so that they don't cause errors when the writers encounter them. .. event:: env-updated (app, env) @@ -249,7 +337,7 @@ registered event handlers. completed, that is, the environment and all doctrees are now up-to-date. .. versionadded:: 0.5 - + .. event:: page-context (app, pagename, templatename, context, doctree) Emitted when the HTML builder has created a context dictionary to render a @@ -280,7 +368,7 @@ registered event handlers. cleanup actions depending on the exception status. .. versionadded:: 0.5 - + .. _template-bridge: diff --git a/doc/ext/autodoc.rst b/doc/ext/autodoc.rst index 993f971ae..17a2766b2 100644 --- a/doc/ext/autodoc.rst +++ b/doc/ext/autodoc.rst @@ -12,6 +12,13 @@ This extension can import the modules you are documenting, and pull in documentation from docstrings in a semi-automatic way. +.. note:: + + For Sphinx (actually, the Python interpreter that executes Sphinx) to find + your module, it must be importable. That means that the module or the + package must be in one of the directories on :data:`sys.path` -- adapt your + :data:`sys.path` in the configuration file accordingly. + For this to work, the docstrings must of course be written in correct reStructuredText. You can then use all of the usual Sphinx markup in the docstrings, and it will end up correctly in the documentation. Together with @@ -61,7 +68,7 @@ directive. Boil the noodle *time* minutes. **Options and advanced usage** - + * If you want to automatically document members, there's a ``members`` option:: @@ -108,9 +115,11 @@ directive. .. versionadded:: 0.4 - * The :dir:`autoclass` and :dir:`autoexception` directives also support a - flag option called ``show-inheritance``. When given, a list of base - classes will be inserted just below the class signature. + * The :dir:`automodule`, :dir:`autoclass` and :dir:`autoexception` directives + also support a flag option called ``show-inheritance``. When given, a list + of base classes will be inserted just below the class signature (when used + with :dir:`automodule`, this will be inserted for every class that is + documented in the module). .. versionadded:: 0.4 @@ -126,6 +135,12 @@ directive. .. versionadded:: 0.5 + * :dir:`automodule` and :dir:`autoclass` also has an ``member-order`` option + that can be used to override the global value of + :confval:`autodoc_member_order` for one directive. + + .. versionadded:: 0.6 + .. note:: In an :dir:`automodule` directive with the ``members`` option set, only @@ -135,12 +150,30 @@ directive. .. directive:: autofunction + autodata automethod autoattribute These work exactly like :dir:`autoclass` etc., but do not offer the options used for automatic member documentation. + For module data members and class attributes, documentation can either be put + into a special-formatted comment *before* the attribute definition, or in a + docstring *after* the definition. This means that in the following class + definition, both attributes can be autodocumented:: + + class Foo: + """Docstring for class Foo.""" + + #: Doc comment for attribute Foo.bar. + bar = 1 + + baz = 2 + """Docstring for attribute Foo.baz.""" + + .. versionchanged:: 0.6 + :dir:`autodata` and :dir:`autoattribute` can now extract docstrings. + .. note:: If you document decorated functions or methods, keep in mind that autodoc @@ -155,19 +188,6 @@ directive. There are also new config values that you can set: -.. confval:: automodule_skip_lines - - This value (whose default is ``0``) can be used to skip an amount of lines in - every module docstring that is processed by an :dir:`automodule` directive. - This is provided because some projects like to put headings in the module - docstring, which would then interfere with your sectioning, or automatic - fields with version control tags, that you don't want to put in the generated - documentation. - - .. deprecated:: 0.4 - Use the more versatile docstring processing provided by - :event:`autodoc-process-docstring`. - .. confval:: autoclass_content This value selects what content will be inserted into the main body of an @@ -185,6 +205,14 @@ There are also new config values that you can set: .. versionadded:: 0.3 +.. confval:: autodoc_member_order + + This value selects if automatically documented members are sorted + alphabetical (value ``'alphabetical'``) or by member type (value + ``'groupwise'``). The default is alphabetical. + + .. versionadded:: 0.6 + Docstring preprocessing ----------------------- diff --git a/doc/ext/builderapi.rst b/doc/ext/builderapi.rst index fb2b7ea4b..bb11bfe2f 100644 --- a/doc/ext/builderapi.rst +++ b/doc/ext/builderapi.rst @@ -3,9 +3,9 @@ Writing new builders ==================== -XXX to be expanded. +.. todo:: Expand this. -.. currentmodule:: sphinx.builder +.. currentmodule:: sphinx.builders .. class:: Builder @@ -20,7 +20,7 @@ XXX to be expanded. .. automethod:: build_update .. automethod:: build - These methods must be overridden in concrete builder classes: + These methods can be overridden in concrete builder classes: .. automethod:: init .. automethod:: get_outdated_docs @@ -28,3 +28,4 @@ XXX to be expanded. .. automethod:: prepare_writing .. automethod:: write_doc .. automethod:: finish + diff --git a/doc/ext/coverage.rst b/doc/ext/coverage.rst index 2f1e00ecc..13294f8bc 100644 --- a/doc/ext/coverage.rst +++ b/doc/ext/coverage.rst @@ -12,7 +12,7 @@ This extension features one additional builder, the :class:`CoverageBuilder`. To use this builder, activate the coverage extension in your configuration file and give ``-b coverage`` on the command line. -XXX to be expanded. +.. todo:: Write this section. Several new configuration values can be used to specify what the builder should check: diff --git a/doc/ext/doctest.rst b/doc/ext/doctest.rst index 9de6ba9e9..19905dc7d 100644 --- a/doc/ext/doctest.rst +++ b/doc/ext/doctest.rst @@ -131,7 +131,7 @@ completely equivalent. :: Test-Output example: - .. testcode:: + .. testcode:: parrot.voom(3000) @@ -149,6 +149,14 @@ There are also these config values for customizing the doctest extension: A list of directories that will be added to :data:`sys.path` when the doctest builder is used. (Make sure it contains absolute paths.) +.. confval:: doctest_global_setup + + Python code that is treated like it were put in a ``testsetup`` directive for + *every* file that is tested, and for every group. You can use this to + e.g. import modules you will always need in your doctests. + + .. versionadded:: 0.6 + .. confval:: doctest_test_doctest_blocks If this is a nonempty string (the default is ``'default'``), standard reST @@ -179,7 +187,7 @@ There are also these config values for customizing the doctest extension: >>> print 1 1 - Some more documentation text. + Some more documentation text. This feature makes it easy for you to test doctests in docstrings included with the :mod:`~sphinx.ext.autodoc` extension without marking them up with a diff --git a/doc/ext/graphviz.rst b/doc/ext/graphviz.rst new file mode 100644 index 000000000..d007bf258 --- /dev/null +++ b/doc/ext/graphviz.rst @@ -0,0 +1,77 @@ +.. highlight:: rest + +:mod:`sphinx.ext.graphviz` -- Add Graphviz graphs +================================================= + +.. module:: sphinx.ext.graphviz + :synopsis: Support for Graphviz graphs. + +.. versionadded:: 0.6 + +This extension allows you to embed `Graphviz `_ graphs in +your documents. + +It adds these directives: + + +.. directive:: graphviz + + Directive to embed graphviz code. The input code for ``dot`` is given as the + content. For example:: + + .. graphviz:: + + digraph foo { + "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. + + +.. directive:: graph + + Directive for embedding a single undirected graph. The name is given as a + directive argument, the contents of the graph are the directive content. + This is a convenience directive to generate ``graph { }``. + + For example:: + + .. graph:: foo + + "bar" -- "baz"; + + +.. directive:: digraph + + Directive for embedding a single directed graph. The name is given as a + directive argument, the contents of the graph are the directive content. + This is a convenience directive to generate ``digraph { }``. + + For example:: + + .. digraph:: foo + + "bar" -> "baz" -> "quux"; + + +There are also these new config values: + +.. confval:: graphviz_dot + + The command name with which to invoke ``dot``. The default is ``'dot'``; you + may need to set this to a full path if ``dot`` is not in the executable + search path. + + Since this setting is not portable from system to system, it is normally not + useful to set it in ``conf.py``; rather, giving it on the + :program:`sphinx-build` command line via the :option:`-D` option should be + preferable, like this:: + + sphinx-build -b html -D graphviz_dot=C:\graphviz\bin\dot.exe . _build/html + +.. confval:: graphviz_dot_args + + 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. diff --git a/doc/ext/inheritance.rst b/doc/ext/inheritance.rst new file mode 100644 index 000000000..fe6d636d3 --- /dev/null +++ b/doc/ext/inheritance.rst @@ -0,0 +1,46 @@ +.. highlight:: rest + +:mod:`sphinx.ext.inheritance_diagram` -- Include inheritance diagrams +===================================================================== + +.. module:: sphinx.ext.inheritance_diagram + :synopsis: Support for displaying inheritance diagrams via graphviz. + +.. versionadded:: 0.6 + +This extension allows you to include inheritance diagrams, rendered via the +:mod:`Graphviz extension `. + +It adds this directive: + +.. directive:: inheritance-diagram + + This directive has one or more arguments, each giving a module or class + name. Class names can be unqualified; in that case they are taken to exist + in the currently described module (see :dir:`module`). + + For each given class, and each class in each given module, the base classes + are determined. Then, from all classes and their base classes, a graph is + generated which is then rendered via the graphviz extension to a directed + graph. + + This directive supports an option called ``parts`` that, if given, must be an + integer, advising the directive to remove that many parts of module names + from the displayed names. (For example, if all your class names start with + ``lib.``, you can give ``:parts: 1`` to remove that prefix from the displayed + node names.) + + +New config values are: + +.. confval:: inheritance_graph_attrs + + A dictionary of graphviz graph attributes for inheritance diagrams. + +.. confval:: inheritance_node_attrs + + A dictionary of graphviz node attributes for inheritance diagrams. + +.. confval:: inheritance_edge_attrs + + A dictionary of graphviz edge attributes for inheritance diagrams. diff --git a/doc/ext/intersphinx.rst b/doc/ext/intersphinx.rst index befae2c07..302ab6a32 100644 --- a/doc/ext/intersphinx.rst +++ b/doc/ext/intersphinx.rst @@ -49,7 +49,7 @@ linking: This will download the corresponding :file:`objects.inv` file from the Internet and generate links to the pages under the given URI. The downloaded inventory is cached in the Sphinx environment, so it must be redownloaded - whenever you do a full rebuild. + whenever you do a full rebuild. A second example, showing the meaning of a non-``None`` value:: diff --git a/doc/ext/math.rst b/doc/ext/math.rst index 325dfd3a9..a214b41e3 100644 --- a/doc/ext/math.rst +++ b/doc/ext/math.rst @@ -12,8 +12,14 @@ Since mathematical notation isn't natively supported by HTML in any way, Sphinx supports math in documentation with two extensions. The basic math support that is common to both extensions is contained in -:mod:`sphinx.ext.mathbase`. Other math support extensions should, if possible, -reuse that support too. +:mod:`sphinx.ext.mathbase`. Other math support extensions should, +if possible, reuse that support too. + +.. note:: + + :mod:`sphinx.ext.mathbase` is not meant to be added to the + :confval:`extensions` config value, instead, use either + :mod:`sphinx.ext.pngmath` or :mod:`sphinx.ext.jsmath` as described below. The input language for mathematics is LaTeX markup. This is the de-facto standard for plain-text math notation and has the added advantage that no @@ -85,7 +91,7 @@ further translation is necessary when building LaTeX output. Euler's identity, equation :eq:`euler`, was elected one of the most beautiful mathematical formulas. - + :mod:`sphinx.ext.pngmath` -- Render math as PNG images ------------------------------------------------------ @@ -102,11 +108,8 @@ There are various config values you can set to influence how the images are buil .. confval:: pngmath_latex The command name with which to invoke LaTeX. The default is ``'latex'``; you - may need to set this to a full path if ``latex`` not in the executable search - path. - - This string is split into words with :func:`shlex.split`, so that you can - include arguments as well if needed. + may need to set this to a full path if ``latex`` is not in the executable + search path. Since this setting is not portable from system to system, it is normally not useful to set it in ``conf.py``; rather, giving it on the @@ -115,12 +118,23 @@ There are various config values you can set to influence how the images are buil sphinx-build -b html -D pngmath_latex=C:\tex\latex.exe . _build/html + .. versionchanged:: 0.5.1 + This value should only contain the path to the latex executable, not + further arguments; use :confval:`pngmath_latex_args` for that purpose. + .. confval:: pngmath_dvipng The command name with which to invoke ``dvipng``. The default is ``'dvipng'``; you may need to set this to a full path if ``dvipng`` is not in the executable search path. +.. confval:: pngmath_latex_args + + Additional arguments to give to latex, as a list. The default is an empty + list. + + .. versionadded:: 0.5.1 + .. confval:: pngmath_latex_preamble Additional LaTeX code to put into the preamble of the short LaTeX files that @@ -129,11 +143,21 @@ There are various config values you can set to influence how the images are buil .. confval:: pngmath_dvipng_args - Additional arguments to give to dvipng, as a list. This is empty by default. - Arguments you might want to add here are e.g. ``['-bg', 'Transparent']``, + Additional arguments to give to dvipng, as a list. The default value is + ``['-gamma 1.5', '-D 110']`` which makes the image a bit darker and larger + then it is by default. + + An arguments you might want to add here is e.g. ``'-bg Transparent'``, which produces PNGs with a transparent background. This is not enabled by default because some Internet Explorer versions don't like transparent PNGs. + .. note:: + + When you "add" an argument, you need to reproduce the default arguments if + you want to keep them; that is, like this:: + + pngmath_dvipng_args = ['-gamma 1.5', '-D 110', '-bg Transparent'] + .. confval:: pngmath_use_preview ``dvipng`` has the ability to determine the "depth" of the rendered text: for diff --git a/doc/ext/refcounting.rst b/doc/ext/refcounting.rst index 225a898b9..e2f338710 100644 --- a/doc/ext/refcounting.rst +++ b/doc/ext/refcounting.rst @@ -4,4 +4,4 @@ .. module:: sphinx.ext.refcounting :synopsis: Keep track of reference counting behavior. -XXX to be written. +.. todo:: Write this section. diff --git a/doc/ext/todo.rst b/doc/ext/todo.rst new file mode 100644 index 000000000..4f5a379dc --- /dev/null +++ b/doc/ext/todo.rst @@ -0,0 +1,30 @@ +:mod:`sphinx.ext.todo` -- Support for todo items +================================================ + +.. module:: sphinx.ext.todo + :synopsis: Allow inserting todo items into documents. +.. moduleauthor:: Daniel Bültmann + +.. versionadded:: 0.5 + +There are two additional directives when using this extension: + +.. directive:: todo + + Use this directive like, for example, :dir:`note`. + + It will only show up in the output if :confval:`todo_include_todos` is true. + + +.. directive:: todolist + + This directive is replaced by a list of all todo directives in the whole + documentation, if :confval:`todo_include_todos` is true. + + +There is also an additional config value: + +.. confval:: todo_include_todos + + If this is ``True``, :dir:`todo` and :dir:`todolist` produce output, else + they produce nothing. The default is ``False``. diff --git a/doc/ext/tutorial.rst b/doc/ext/tutorial.rst new file mode 100644 index 000000000..c44748d23 --- /dev/null +++ b/doc/ext/tutorial.rst @@ -0,0 +1,343 @@ +.. _exttut: + +Tutorial: Writing a simple extension +==================================== + +This section is intended as a walkthrough for the creation of custom extensions. +It covers the basics of writing and activating an extensions, as well as +commonly used features of extensions. + +As an example, we will cover a "todo" extension that adds capabilities to +include todo entries in the documentation, and collecting these in a central +place. (A similar "todo" extension is distributed with Sphinx.) + + +Build Phases +------------ + +One thing that is vital in order to understand extension mechanisms is the way +in which a Sphinx project is built: this works in several phases. + +**Phase 0: Initialization** + + In this phase, almost nothing interesting for us happens. The source + directory is searched for source files, and extensions are initialized. + Should a stored build environment exist, it is loaded, otherwise a new one is + created. + +**Phase 1: Reading** + + In Phase 1, all source files (and on subsequent builds, those that are new or + changed) are read and parsed. This is the phase where directives and roles + are encountered by the docutils, and the corresponding functions are called. + The output of this phase is a *doctree* for each source files, that is a tree + of docutils nodes. For document elements that aren't fully known until all + existing files are read, temporary nodes are created. + + During reading, the build environment is updated with all meta- and cross + reference data of the read documents, such as labels, the names of headings, + described Python objects and index entries. This will later be used to + replace the temporary nodes. + + The parsed doctrees are stored on the disk, because it is not possible to + hold all of them in memory. + +**Phase 2: Consistency checks** + + Some checking is done to ensure no surprises in the built documents. + +**Phase 3: Resolving** + + Now that the metadata and cross-reference data of all existing documents is + known, all temporary nodes are replaced by nodes that can be converted into + output. For example, links are created for object references that exist, and + simple literal nodes are created for those that don't. + +**Phase 4: Writing** + + This phase converts the resolved doctrees to the desired output format, such + as HTML or LaTeX. This happens via a so-called docutils writer that visits + the individual nodes of each doctree and produces some output in the process. + +.. note:: + + Some builders deviate from this general build plan, for example, the builder + that checks external links does not need anything more than the parsed + doctrees and therefore does not have phases 2--4. + + +Extension Design +---------------- + +We want the extension to add the following to Sphinx: + +* A "todo" directive, containing some content that is marked with "TODO", and + only shown in the output if a new config value is set. (Todo entries should + not be in the output by default.) + +* A "todolist" directive that creates a list of all todo entries throughout the + documentation. + +For that, we will need to add the following elements to Sphinx: + +* New directives, called ``todo`` and ``todolist``. +* New document tree nodes to represent these directives, conventionally also + called ``todo`` and ``todolist``. We wouldn't need new nodes if the new + directives only produced some content representable by existing nodes. +* A new config value ``todo_include_todos`` (config value names should start + with the extension name, in order to stay unique) that controls whether todo + entries make it into the output. +* New event handlers: one for the :event:`doctree-resolved` event, to replace + the todo and todolist nodes, and one for :event:`env-purge-doc` (the reason + for that will be covered later). + + +The Setup Function +------------------ + +.. currentmodule:: sphinx.application + +The new elements are added in the extension's setup function. Let us create a +new Python module called :file:`todo.py` and add the setup function:: + + def setup(app): + app.add_config_value('todo_include_todos', False, False) + + app.add_node(todolist) + app.add_node(todo, + html=(visit_todo_node, depart_todo_node), + latex=(visit_todo_node, depart_todo_node), + text=(visit_todo_node, depart_todo_node)) + + app.add_directive('todo', TodoDirective) + app.add_directive('todolist', TodolistDirective) + app.connect('doctree-resolved', process_todo_nodes) + app.connect('env-purge-doc', purge_todos) + +The calls in this function refer to classes and functions not yet written. What +the individual calls do is the following: + +* :meth:`~Sphinx.add_config_value` lets Sphinx know that it should recognize the + new *config value* ``todo_include_todos``, whose default value should be + ``False`` (this also tells Sphinx that it is a boolean value). + + If the third argument was ``True``, all documents would be re-read if the + config value changed its value. This is needed for config values that + influence reading (build phase 1). + +* :meth:`~Sphinx.add_node` adds a new *node class* to the build system. It also + can specify visitor functions for each supported output format. These visitor + functions are needed when the new nodes stay until phase 4 -- since the + ``todolist`` node is always replaced in phase 3, it doesn't need any. + + We need to create the two node classes ``todo`` and ``todolist`` later. + +* :meth:`~Sphinx.add_directive` adds a new *directive*, given by name and class. + + The handler functions are created later. + +* Finally, :meth:`~Sphinx.connect` adds an *event handler* to the event whose + name is given by the first argument. The event handler function is called + with several arguments which are documented with the event. + + +The Node Classes +---------------- + +Let's start with the node classes:: + + from docutils import nodes + + class todo(nodes.Admonition, nodes.Element): + pass + + class todolist(nodes.General, nodes.Element): + pass + + def visit_todo_node(self, node): + self.visit_admonition(node) + + def depart_todo_node(self, node): + self.depart_admonition(node) + +Node classes usually don't have to do anything except inherit from the standard +docutils classes defined in :mod:`docutils.nodes`. ``todo`` inherits from +``Admonition`` because it should be handled like a note or warning, ``todolist`` +is just a "general" node. + + +The Directive Classes +--------------------- + +A directive class is a class deriving usually from +``docutils.parsers.rst.Directive``. Since the class-based directive interface +doesn't exist yet in Docutils 0.4, Sphinx has another base class called +``sphinx.util.compat.Directive`` that you can derive your directive from, and it +will work with both Docutils 0.4 and 0.5 upwards. The directive interface is +covered in detail in the docutils documentation; the important thing is that the +class has a method ``run`` that returns a list of nodes. + +The ``todolist`` directive is quite simple:: + + from sphinx.util.compat import Directive + + class TodolistDirective(Directive): + + def run(self): + return [todolist('')] + +An instance of our ``todolist`` node class is created and returned. The +todolist directive has neither content nor arguments that need to be handled. + +The ``todo`` directive function looks like this:: + + from sphinx.util.compat import make_admonition + + class TodoDirective(Directive): + + # this enables content in the directive + has_content = True + + def run(self): + env = self.state.document.settings.env + + targetid = "todo-%s" % env.index_num + env.index_num += 1 + targetnode = nodes.target('', '', ids=[targetid]) + + ad = make_admonition(todo, self.name, [_('Todo')], self.options, + self.content, self.lineno, self.content_offset, + self.block_text, self.state, self.state_machine) + + if not hasattr(env, 'todo_all_todos'): + env.todo_all_todos = [] + env.todo_all_todos.append({ + 'docname': env.docname, + 'lineno': self.lineno, + 'todo': ad[0].deepcopy(), + 'target': targetnode, + }) + + return [targetnode] + ad + +Several important things are covered here. First, as you can see, you can refer +to the build environment instance using ``self.state.document.settings.env``. + +Then, to act as a link target (from the todolist), the todo directive needs to +return a target node in addition to the todo node. The target ID (in HTML, this +will be the anchor name) is generated by using ``env.index_num`` which is +persistent between directive calls and therefore leads to unique target names. +The target node is instantiated without any text (the first two arguments). + +An admonition is created using a standard docutils function (wrapped in Sphinx +for docutils cross-version compatibility). The first argument gives the node +class, in our case ``todo``. The third argument gives the admonition title (use +``arguments`` here to let the user specify the title). A list of nodes is +returned from ``make_admonition``. + +Then, the todo node is added to the environment. This is needed to be able to +create a list of all todo entries throughout the documentation, in the place +where the author puts a ``todolist`` directive. For this case, the environment +attribute ``todo_all_todos`` is used (again, the name should be unique, so it is +prefixed by the extension name). It does not exist when a new environment is +created, so the directive must check and create it if necessary. Various +information about the todo entry's location are stored along with a copy of the +node. + +In the last line, the nodes that should be put into the doctree are returned: +the target node and the admonition node. + +The node structure that the directive returns looks like this:: + + +--------------------+ + | target node | + +--------------------+ + +--------------------+ + | todo node | + +--------------------+ + \__+--------------------+ + | admonition title | + +--------------------+ + | paragraph | + +--------------------+ + | ... | + +--------------------+ + + +The Event Handlers +------------------ + +Finally, let's look at the event handlers. First, the one for the +:event:`env-purge-doc` event:: + + def purge_todos(app, env, docname): + if not hasattr(env, 'todo_all_todos'): + return + env.todo_all_todos = [todo for todo in env.todo_all_todos + if todo['docname'] != docname] + +Since we store information from source files in the environment, which is +persistent, it may become out of date when the source file changes. Therefore, +before each source file is read, the environment's records of it are cleared, +and the :event:`env-purge-doc` event gives extensions a chance to do the same. +Here we clear out all todos whose docname matches the given one from the +``todo_all_todos`` list. If there are todos left in the document, they will be +added again during parsing. + +The other handler belongs to the :event:`doctree-resolved` event. This event is +emitted at the end of phase 3 and allows custom resolving to be done:: + + def process_todo_nodes(app, doctree, fromdocname): + if not app.config.todo_include_todos: + for node in doctree.traverse(todo): + node.parent.remove(node) + + # Replace all todolist nodes with a list of the collected todos. + # Augment each todo with a backlink to the original location. + env = app.builder.env + + for node in doctree.traverse(todolist): + if not app.config.todo_include_todos: + node.replace_self([]) + continue + + content = [] + + for todo_info in env.todo_all_todos: + para = nodes.paragraph() + filename = env.doc2path(todo_info['docname'], base=None) + description = ( + _('(The original entry is located in %s, line %d and can be found ') % + (filename, todo_info['lineno'])) + para += nodes.Text(description, description) + + # Create a reference + newnode = nodes.reference('', '') + innernode = nodes.emphasis(_('here'), _('here')) + newnode['refdocname'] = todo_info['docname'] + newnode['refuri'] = app.builder.get_relative_uri( + fromdocname, todo_info['docname']) + newnode['refuri'] += '#' + todo_info['target']['refid'] + newnode.append(innernode) + para += newnode + para += nodes.Text('.)', '.)') + + # Insert into the todolist + content.append(todo_info['todo']) + content.append(para) + + node.replace_self(content) + +It is a bit more involved. If our new "todo_include_todos" config value is +false, all todo and todolist nodes are removed from the documents. + +If not, todo nodes just stay where and how they are. Todolist nodes are +replaced by a list of todo entries, complete with backlinks to the location +where they come from. The list items are composed of the nodes from the todo +entry and docutils nodes created on the fly: a paragraph for each entry, +containing text that gives the location, and a link (reference node containing +an italic node) with the backreference. The reference URI is built by +``app.builder.get_relative_uri`` which creates a suitable URI depending on the +used builder, and appending the todo node's (the target's) ID as the anchor +name. + diff --git a/doc/extensions.rst b/doc/extensions.rst index 3f63c64f6..21ba0fd80 100644 --- a/doc/extensions.rst +++ b/doc/extensions.rst @@ -9,17 +9,25 @@ Sphinx Extensions Since many projects will need special features in their documentation, Sphinx is designed to be extensible on several levels. -First, you can add new :term:`builder`\s to support new output formats or -actions on the parsed documents. Then, it is possible to register custom -reStructuredText roles and directives, extending the markup. And finally, there -are so-called "hook points" at strategic places throughout the build process, -where an extension can register a hook and run specialized code. +This is what you can do in an extension: First, you can add new +:term:`builder`\s to support new output formats or actions on the parsed +documents. Then, it is possible to register custom reStructuredText roles and +directives, extending the markup. And finally, there are so-called "hook +points" at strategic places throughout the build process, where an extension can +register a hook and run specialized code. -The configuration file itself can be an extension, see the :confval:`extensions` -configuration value docs. +An extension is simply a Python module. When an extension is loaded, Sphinx +imports this module and executes its ``setup()`` function, which in turn +notifies Sphinx of everything the extension offers -- see the extension tutorial +for examples. + +The configuration file itself can be treated as an extension if it contains a +``setup()`` function. All other extensions to load must be listed in the +:confval:`extensions` configuration value. .. toctree:: + ext/tutorial ext/appapi ext/builderapi @@ -36,6 +44,41 @@ These extensions are built in and can be activated by respective entries in the ext/doctest ext/intersphinx ext/math + ext/graphviz + ext/inheritance ext/refcounting ext/ifconfig ext/coverage + ext/todo + + +Third-party extensions +---------------------- + +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. + +.. _Wiki at BitBucket: http://www.bitbucket.org/birkenfeld/sphinx/wiki/Home + + +Where to put your own extensions? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Extensions local to a project should be put within the project's directory +structure. Set Python's module search path, ``sys.path``, accordingly so that +Sphinx can find them. +E.g., if your extension ``foo.py`` lies in the ``exts`` subdirectory of the +project root, put into :file:`conf.py`:: + + import sys, os + + sys.path.append(os.path.abspath('exts')) + + extensions = ['foo'] + +You can also install extensions anywhere else on ``sys.path``, e.g. in the +``site-packages`` directory. diff --git a/doc/faq.rst b/doc/faq.rst new file mode 100644 index 000000000..ae12cdad7 --- /dev/null +++ b/doc/faq.rst @@ -0,0 +1,30 @@ +.. _faq: + +Sphinx FAQ +========== + +This is a list of Frequently Asked Questions about Sphinx. Feel free to +suggest new entries! + +How do I... +----------- + +... get section numbers? + They are automatic in LaTeX output; for HTML, give a ``:numbered:`` option to + the :dir:`toctree` directive where you want to start numbering. + +... customize the look of the built HTML files? + Use themes, see :doc:`theming`. + +... add global substitutions or includes? + Add them in the :confval:`rst_epilog` config value. + +... write my own extension? + See the :ref:`extension tutorial `. + +... use Sphinx with Epydoc? + There's a third-party extension providing an `api role`_ which refers to + Epydoc's API docs for a given identifier. + + +.. _api role: http://git.savannah.gnu.org/cgit/kenozooid.git/tree/doc/extapi.py diff --git a/doc/glossary.rst b/doc/glossary.rst index 6a80ad361..7ec787ff5 100644 --- a/doc/glossary.rst +++ b/doc/glossary.rst @@ -6,7 +6,7 @@ Glossary .. glossary:: builder - A class (inheriting from :class:`~sphinx.builder.Builder`) that takes + A class (inheriting from :class:`~sphinx.builders.Builder`) that takes parsed documents and performs an action on them. Normally, builders translate the documents to an output format, but it is also possible to use the builder builders that e.g. check for broken links in the diff --git a/doc/intro.rst b/doc/intro.rst index af3cc1aaa..7b8f86511 100644 --- a/doc/intro.rst +++ b/doc/intro.rst @@ -89,6 +89,12 @@ The :program:`sphinx-build` script has several more options: cross-references), but rebuild it completely. The default is to only read and parse source files that are new or have changed since the last run. +**-t** *tag* + Define the tag *tag*. This is relevant for :dir:`only` directives that only + include their content if this tag is set. + + .. versionadded:: 0.6 + **-d** *path* Since Sphinx has to read and parse all source files before it can write an output file, the parsed source files are cached as "doctree pickles". @@ -105,9 +111,18 @@ The :program:`sphinx-build` script has several more options: .. versionadded:: 0.3 +**-C** + Don't look for a configuration file; only take options via the ``-D`` option. + + .. versionadded:: 0.5 + **-D** *setting=value* - Override a configuration value set in the :file:`conf.py` file. (The value - must be a string value.) + Override a configuration value set in the :file:`conf.py` file. The value + must be a string or dictionary value. For the latter, supply the setting + name and key like this: ``-D latex_elements.docclass=scrartcl``. + + .. versionchanged:: 0.6 + The value can now be a dictionary value. **-A** *name=value* Make the *name* assigned to *value* in the HTML templates. @@ -124,6 +139,13 @@ The :program:`sphinx-build` script has several more options: Do not output anything on standard output, also suppress warnings. Only errors are written to standard error. +**-w** *file* + Write warnings (and errors) to the given file, in addition to standard error. + +**-W** + Turn warnings into errors. This means that the build stops at the first + warning and ``sphinx-build`` exits with exit status 1. + **-P** (Useful for debugging only.) Run the Python debugger, :mod:`pdb`, if an unhandled exception occurs while building. diff --git a/doc/markup/code.rst b/doc/markup/code.rst index 299ab0bc0..93cd127ba 100644 --- a/doc/markup/code.rst +++ b/doc/markup/code.rst @@ -30,7 +30,10 @@ installed) and handled in a smart way: config value. * Within Python highlighting mode, interactive sessions are recognized - automatically and highlighted appropriately. + automatically and highlighted appropriately. Normal Python code is only + highlighted if it is parseable (so you can use Python as the default, but + interspersed snippets of shell commands or other code blocks will not be + highlighted as Python). * The highlighting language can be changed using the ``highlight`` directive, used as follows:: @@ -96,12 +99,14 @@ Includes .. literalinclude:: example.py - The file name is relative to the current file's path. + The file name is usually relative to the current file's path. However, if it + is absolute (starting with ``/``), it is relative to the top source + directory. 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:: - + .. literalinclude:: example.rb :language: ruby :linenos: @@ -113,8 +118,36 @@ Includes .. literalinclude:: example.py :encoding: latin-1 + The directive also supports including only parts of the file. If it is a + Python module, you can select a class, function or method to include using + the ``pyobject`` option:: + + .. literalinclude:: example.py + :pyobject: Timer.start + + This would only include the code lines belonging to the ``start()`` method in + the ``Timer`` class within the file. + + Alternately, you can specify exactly which lines to include by giving a + ``lines`` option:: + + .. literalinclude:: example.py + :lines: 1,3,5-10,20- + + This includes the lines 1, 3, 5 to 10 and lines 20 to the last line. + + Another way to control which part of the file is included is to use the + ``start-after`` and ``end-before`` options (or only one of them). If + ``start-after`` is given as a string option, only lines that follow the first + line containing that string are included. If ``end-before`` is given as a + string option, only lines that precede the first lines containing that string + are included. + .. versionadded:: 0.4.3 The ``encoding`` option. + .. versionadded:: 0.6 + The ``pyobject``, ``lines``, ``start-after`` and ``end-before`` options, + as well as support for absolute filenames. .. rubric:: Footnotes diff --git a/doc/markup/desc.rst b/doc/markup/desc.rst index f121d23d7..ec8ede37d 100644 --- a/doc/markup/desc.rst +++ b/doc/markup/desc.rst @@ -17,7 +17,7 @@ typical module section might start like this:: .. moduleauthor:: John Idle -The directives you can use for module are: +The directives you can use for module declarations are: .. directive:: .. module:: name @@ -67,8 +67,8 @@ The directives you can use for module are: .. _desc-units: -Description units ------------------ +Object description units +------------------------ There are a number of directives used to describe specific features provided by modules. Each directive requires one or more signatures to provide basic @@ -204,39 +204,12 @@ The directives are: Like :dir:`method`, but indicates that the method is a static method. .. versionadded:: 0.4 - -.. directive:: .. cmdoption:: name args, name args, ... - Describes a command line option or switch. Option argument names should be - enclosed in angle brackets. Example:: +.. directive:: .. classmethod:: name(signature) - .. cmdoption:: -m , --module + Like :dir:`method`, but indicates that the method is a class method. - Run a module as a script. - - The directive will create a cross-reference target named after the *first* - option, referencable by :role:`option` (in the example case, you'd use - something like ``:option:`-m```). - -.. directive:: .. envvar:: name - - Describes an environment variable that the documented code uses or defines. - - -There is also a generic version of these directives: - -.. directive:: .. describe:: text - - This directive produces the same formatting as the specific ones explained - above but does not create index entries or cross-referencing targets. It is - used, for example, to describe the directives in this document. Example:: - - .. describe:: opcode - - Describes a Python bytecode instruction. - -Extensions may add more directives like that, using the -:func:`~sphinx.application.Sphinx.add_description_unit` method. + .. versionadded:: 0.6 .. _signatures: @@ -287,7 +260,7 @@ explained by an example:: .. function:: format_exception(etype, value, tb[, limit=None]) Format the exception with a traceback. - + :param etype: exception type :param value: exception value :param tb: traceback object @@ -308,3 +281,77 @@ This will render like this: :param limit: maximum number of stack frames to show :type limit: integer or None :rtype: list of strings + + +Command-line program markup +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +There is a set of directives allowing documenting command-line programs: + +.. directive:: .. cmdoption:: name args, name args, ... + + Describes a command line option or switch. Option argument names should be + enclosed in angle brackets. Example:: + + .. cmdoption:: -m , --module + + Run a module as a script. + + The directive will create a cross-reference target named after the *first* + option, referencable by :role:`option` (in the example case, you'd use + something like ``:option:`-m```). + +.. directive:: .. envvar:: name + + Describes an environment variable that the documented code or program uses or + defines. + + +.. directive:: .. program:: name + + Like :dir:`currentmodule`, this directive produces no output. Instead, it + serves to notify Sphinx that all following :dir:`cmdoption` directives + document options for the program called *name*. + + If you use :dir:`program`, you have to qualify the references in your + :role:`option` roles by the program name, so if you have the following + situation :: + + .. program:: rm + + .. cmdoption:: -r + + Work recursively. + + .. program:: svn + + .. cmdoption:: -r revision + + Specify the revision to work upon. + + then ``:option:`rm -r``` would refer to the first option, while + ``:option:`svn -r``` would refer to the second one. + + The program name may contain spaces (in case you want to document subcommands + like ``svn add`` and ``svn commit`` separately). + + .. versionadded:: 0.5 + + +Custom description units +~~~~~~~~~~~~~~~~~~~~~~~~ + +There is also a generic version of these directives: + +.. directive:: .. describe:: text + + This directive produces the same formatting as the specific ones explained + above but does not create index entries or cross-referencing targets. It is + used, for example, to describe the directives in this document. Example:: + + .. describe:: opcode + + Describes a Python bytecode instruction. + +Extensions may add more directives like that, using the +:func:`~sphinx.application.Sphinx.add_description_unit` method. diff --git a/doc/markup/inline.rst b/doc/markup/inline.rst index 7deffb435..69721b321 100644 --- a/doc/markup/inline.rst +++ b/doc/markup/inline.rst @@ -12,7 +12,8 @@ For all other roles, you have to write ``:rolename:`content```. .. note:: The default role (```content```) has no special meaning by default. You are - free to use it for anything you like. + free to use it for anything you like; use the :confval:`default_role` config + value to set it to a known role. .. _xref-syntax: @@ -223,7 +224,53 @@ to labels: Using :role:`ref` is advised over standard reStructuredText links to sections (like ```Section title`_``) because it works across files, when section headings are changed, and for all builders that support cross-references. - + + +Cross-referencing documents +--------------------------- + +.. versionadded:: 0.6 + +There is also a way to directly link to documents: + +.. role:: doc + + Link to the specified document; the document name can be specified in + absolute or relative fashion. For example, if the reference + ``:doc:`parrot``` occurs in the document ``sketches/index``, then the link + refers to ``sketches/parrot``. If the reference is ``:doc:`/people``` or + ``:doc:`../people```, the link refers to ``people``. + + If no explicit link text is given (like usual: ``:doc:`Monty Python members + ```), the link caption will be the title of the given document. + + +Referencing downloadable files +------------------------------ + +.. versionadded:: 0.6 + +.. role:: download + + This role lets you link to files within your source tree that are not reST + documents that can be viewed, but files that can be downloaded. + + When you use this role, the referenced file is automatically marked for + inclusion in the output when building (obviously, for HTML output only). + All downloadable files are put into the ``_downloads`` subdirectory of the + output directory; duplicate filenames are handled. + + An example:: + + See :download:`this example script <../example.py>`. + + The given filename is usually relative to the directory the current source + file is contained in, but if it absolute (starting with ``/``), it is taken + as relative to the top source directory. + + The ``example.py`` file will be copied to the output directory, and a + suitable link generated to it. + Other semantic markup --------------------- @@ -231,6 +278,16 @@ Other semantic markup The following roles don't do anything special except formatting the text in a different style: +.. role:: abbr + + An abbreviation. If the role content contains a parenthesized explanation, + it will be treated specially: it will be shown in a tool-tip in HTML, and + output only once in LaTeX. + + Example: ``:abbr:`LIFO (last-in, first-out)```. + + .. versionadded:: 0.6 + .. role:: command The name of an OS-level command, such as ``rm``. @@ -329,7 +386,7 @@ in a different style: curly braces to indicate a "variable" part, as in ``:file:``. If you don't need the "variable part" indication, use the standard - ````code```` instead. + ````code```` instead. The following roles generate external links: @@ -350,6 +407,7 @@ The following roles generate external links: Note that there are no special roles for including hyperlinks as you can use the standard reST markup for that purpose. + .. _default-substitutions: Substitutions @@ -372,6 +430,6 @@ They are set in the build configuration file. .. describe:: |today| - Replaced by either today's date, or the date set in the build configuration - file. Normally has the format ``April 14, 2007``. Set by - :confval:`today_fmt` and :confval:`today`. + Replaced by either today's date (the date on which the document is read), or + the date set in the build configuration file. Normally has the format + ``April 14, 2007``. Set by :confval:`today_fmt` and :confval:`today`. diff --git a/doc/markup/misc.rst b/doc/markup/misc.rst index 98f5485e7..01e5a3f18 100644 --- a/doc/markup/misc.rst +++ b/doc/markup/misc.rst @@ -3,6 +3,8 @@ Miscellaneous markup ==================== +.. _metadata: + File-wide metadata ------------------ @@ -46,6 +48,28 @@ Meta-information markup output. +.. _tags: + +Including content based on tags +------------------------------- + +.. directive:: .. only:: + + Include the content of the directive only if the *expression* is true. The + expression should consist of tags, like this:: + + .. only:: html and draft + + Undefined tags are false, defined tags (via the ``-t`` command-line option or + within :file:`conf.py`) are true. Boolean expressions, also using + parentheses (like ``html and (latex or draft)`` are supported. + + The format of the current builder (``html``, ``latex`` or ``text``) is always + set as a tag. + + .. versionadded:: 0.6 + + Tables ------ diff --git a/doc/markup/para.rst b/doc/markup/para.rst index c60eb2587..2ea2fd2d7 100644 --- a/doc/markup/para.rst +++ b/doc/markup/para.rst @@ -1,4 +1,4 @@ -.. highlight:: rest +x.. highlight:: rest Paragraph-level markup ---------------------- @@ -85,9 +85,9 @@ units as well as normal text: This directive creates a paragraph heading that is not used to create a table of contents node. - + .. note:: - + If the *title* of the rubric is "Footnotes", this rubric is ignored by the LaTeX writer, since it is assumed to only contain footnote definitions and therefore would create an empty heading. @@ -100,6 +100,27 @@ units as well as normal text: .. centered:: LICENSE AGREEMENT +.. directive:: hlist + + This directive must contain a bullet list. It will transform it into a more + compact list by either distributing more than one item horizontally, or + reducing spacing between items, depending on the builder. + + For builders that support the horizontal distribution, there is a ``columns`` + option that specifies the number of columns; it defaults to 2. Example:: + + .. hlist:: + :columns: 3 + + * A list of + * short items + * that should be + * displayed + * horizontally + + .. versionadded:: 0.6 + + Table-of-contents markup ------------------------ @@ -218,7 +239,7 @@ the definition of the symbol. There is this directive: Note that no further reST parsing is done in the production, so that you don't have to escape ``*`` or ``|`` characters. -.. XXX describe optional first parameter +.. XXX describe optional first parameter The following is an example taken from the Python Reference Manual:: diff --git a/doc/rest.rst b/doc/rest.rst index 8573430f6..e70fa105b 100644 --- a/doc/rest.rst +++ b/doc/rest.rst @@ -212,10 +212,19 @@ reST supports an image directive, used like so:: .. image:: gnu.png (options) -When used within Sphinx, the file name given (here ``gnu.png``) must be relative -to the source file, and Sphinx will automatically copy image files over to a -subdirectory of the output directory on building (e.g. the ``_static`` directory -for HTML output.) +When used within Sphinx, the file name given (here ``gnu.png``) must either be +relative to the source file, or absolute which means that they are relative to +the top source directory. For example, the file ``sketch/spam.rst`` could refer +to the image ``images/spam.png`` as ``../images/spam.png`` or +``/images/spam.png``. + +Sphinx will automatically copy image files over to a subdirectory of the output +directory on building (e.g. the ``_static`` directory for HTML output.) + +Interpretation of image size options (``width`` and ``height``) is as follows: +if the size has no unit or the unit is pixels, the given size will only be +respected for output channels that support pixels (i.e. not in LaTeX output). +Other units (like ``pt`` for points) will be used for HTML and LaTeX output. Sphinx extends the standard docutils behavior by allowing an asterisk for the extension:: @@ -231,6 +240,9 @@ the former, while the HTML builder would prefer the latter. .. versionchanged:: 0.4 Added the support for file names ending in an asterisk. +.. versionchanged:: 0.6 + Image paths can now be absolute. + Footnotes --------- @@ -277,7 +289,7 @@ markup blocks, like this:: See the `reST reference for substitutions `_ for details. - + If you want to use some substitutions for all documents, put them into a separate file and include it into all documents you want to use them in, using the :dir:`include` directive. Be sure to give the include file a file name @@ -291,7 +303,17 @@ Comments -------- Every explicit markup block which isn't a valid markup construct (like the -footnotes above) is regarded as a comment. +footnotes above) is regarded as a comment. For example:: + + .. This is a comment. + +You can indent text after a comment start to form multiline comments:: + + .. + This whole indented block + is a comment. + + Still in the comment. Source encoding @@ -312,4 +334,7 @@ There are some problems one commonly runs into while authoring reST documents: separated from the surrounding text by non-word characters, you have to use a backslash-escaped space to get around that. +* **No nested inline markup:** Something like ``*see :func:`foo`*`` is not + possible. + .. XXX more? diff --git a/doc/sphinx-build.1 b/doc/sphinx-build.1 new file mode 100644 index 000000000..498771c92 --- /dev/null +++ b/doc/sphinx-build.1 @@ -0,0 +1,102 @@ +.TH sphinx-build 1 "Jan 2009" "Sphinx 0.6" "User Commands" +.SH NAME +sphinx-build \- Sphinx documentation generator tool +.SH SYNOPSIS +.B sphinx-build +[\fIoptions\fR] <\fIsourcedir\fR> <\fIoutdir\fR> [\fIfilenames\fR...] +.SH DESCRIPTION +sphinx-build generates documentation from the files in and places it +in the . + +sphinx-build looks for /conf.py for the configuration settings. +.B sphinx-quickstart(1) +may be used to generate template files, including conf.py. + +sphinx-build can create documentation in different formats. A format is +selected by specifying the builder name on the command line; it defaults to +HTML. Builders can also perform other tasks related to documentation +processing. + +By default, everything that is outdated is built. Output only for selected +files can be built by specifying individual filenames. + +List of available builders: +.TP +\fBhtml\fR +HTML files generation. This is default builder. +.TP +\fBhtmlhelp\fR +Generates files for CHM generation. +.TP +\fBqthelp\fR +Generates files for Qt help collection generation. +.TP +\fBlatex\fR +Generates a LaTeX version of the documentation. +.TP +\fBtext\fR +Generates a plain-text version of the documentation. +.TP +\fBchanges\fR +Generates HTML files listing changed/added/deprecated items for the +current version. +.TP +\fBlinkcheck\fR +Checks the integrity of all external links in the documentation. +.TP +\fBpickle / json\fR +Generates serialized HTML files in the selected format. + +.SH OPTIONS +.TP +\fB-b\fR +Builder to use; defaults to html. See the full list of builders above. +.TP +\fB-a\fR +Generates output for all files; without this option only output for +new and changed files is generated. +.TP +\fB-E\fR +Ignores cached files, forces to re-read all source files from disk. +.TP +\fB-c\fR +Locates the conf.py file in the specified path instead of . +.TP +\fB-C\fR +Specifies that no conf.py file at all is to be used. Configuration can +only be set with the -D option. +.TP +\fB-D\fR = +Overrides a setting from the configuration file. +.TP +\fB-d\fR +Path to cached files; defaults to /.doctrees. +.TP +\fB-A\fR = +Passes a value into the HTML templates (only for html builders). +.TP +\fB-N\fR +Prevents colored output. +.TP +\fB-q\fR +Quiet operation, just prints warnings and errors on stderr. +.TP +\fB-Q\fR +Very quiet operation, doesn't print anything except for errors. +.TP +\fB-w\fR +Write warnings and errors into the given file, in addition to stderr. +.TP +\fB-W\fR +Turn warnings into errors. +.TP +\fB-P\fR +Runs Pdb on exception. +.SH "SEE ALSO" +.BR sphinx-quickstart(1) +.SH AUTHOR +Georg Brandl , Armin Ronacher et +al. +.PP +This manual page was initially written by Mikhail Gusarov +, for the Debian project. diff --git a/doc/sphinx-quickstart.1 b/doc/sphinx-quickstart.1 new file mode 100644 index 000000000..93b0a4a51 --- /dev/null +++ b/doc/sphinx-quickstart.1 @@ -0,0 +1,17 @@ +.TH sphinx-quickstart 1 "Jan 2009" "Sphinx 0.6" "User Commands" +.SH NAME +sphinx-quickstart \- Sphinx documentation template generator +.SH SYNOPSIS +.B sphinx-quickstart +.SH DESCRIPTION +sphinx-quickstart is an interactive tool that asks some questions about your +project and then generates a complete documentation directory and sample +Makefile to be used with \fBsphinx-build(1)\fR. +.SH "SEE ALSO" +.BR sphinx-build(1) +.SH AUTHOR +Georg Brandl , Armin Ronacher et +al. +.PP +This manual page was initially written by Mikhail Gusarov + for the Debian project. diff --git a/doc/templating.rst b/doc/templating.rst index 61a8a72b0..61657547d 100644 --- a/doc/templating.rst +++ b/doc/templating.rst @@ -1,3 +1,5 @@ +.. highlight:: html+jinja + .. _templating: Templating @@ -19,10 +21,10 @@ No. You have several other options: configuration value accordingly. * You can :ref:`write a custom builder ` that derives from - :class:`~sphinx.builder.StandaloneHTMLBuilder` and calls your template engine + :class:`~sphinx.builders.StandaloneHTMLBuilder` and calls your template engine of choice. -* You can use the :class:`~sphinx.builder.PickleHTMLBuilder` that produces +* You can use the :class:`~sphinx.builders.PickleHTMLBuilder` that produces pickle files with the page contents, and postprocess them using a custom tool, or use them in your Web application. @@ -37,27 +39,26 @@ template, customizing it while also keeping the changes at a minimum. To customize the output of your documentation you can override all the templates (both the layout templates and the child templates) by adding files with the -same name as the original filename into the template directory of the folder the -Sphinx quickstart generated for you. +same name as the original filename into the template directory of the structure +the Sphinx quickstart generated for you. Sphinx will look for templates in the folders of :confval:`templates_path` first, and if it can't find the template it's looking for there, it falls back -to the builtin templates that come with Sphinx. +to the selected theme's templates. A template contains **variables**, which are replaced with values when the template is evaluated, **tags**, which control the logic of the template and **blocks** which are used for template inheritance. -Sphinx provides base templates with a couple of blocks it will fill with data. -The default templates are located in the :file:`templates` folder of the Sphinx -installation directory. Templates with the same name in the -:confval:`templates_path` override templates located in the builtin folder. +Sphinx' *basic* theme provides base templates with a couple of blocks it will +fill with data. These are located in the :file:`themes/basic` subdirectory of +the Sphinx installation directory, and used by all builtin Sphinx themes. +Templates with the same name in the :confval:`templates_path` override templates +supplied by the selected theme. For example, to add a new link to the template area containing related links all you have to do is to add a new template called ``layout.html`` with the -following contents: - -.. sourcecode:: html+jinja +following contents:: {% extends "!layout.html" %} {% block rootrellink %} @@ -65,16 +66,24 @@ following contents: {{ super() }} {% endblock %} -By prefixing the name of the extended template with an exclamation mark, Sphinx -will load the builtin layout template. If you override a block, you should call -``{{ super() }}`` somewhere to render the block's content in the extended -template -- unless you don't want that content to show up. +By prefixing the name of the overridden template with an exclamation mark, +Sphinx will load the layout template from the underlying HTML theme. +**Important**: If you override a block, call ``{{ super() }}`` somewhere to +render the block's content in the extended template -- unless you don't want +that content to show up. + + +Working the 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: Blocks ~~~~~~ -The following blocks exist in the ``layout`` template: +The following blocks exist in the ``layout.html`` template: `doctype` The doctype of the output format. By default this is XHTML 1.0 Transitional @@ -92,11 +101,11 @@ The following blocks exist in the ``layout`` template: add references to JavaScript or extra CSS files. `relbar1` / `relbar2` - This block contains the list of related links (the parent documents on the - left, and the links to index, modules etc. on the right). `relbar1` appears - before the document, `relbar2` after the document. By default, both blocks - are filled; to show the relbar only before the document, you would override - `relbar2` like this:: + This block contains the *relation bar*, the list of related links (the + parent documents on the left, and the links to index, modules etc. on the + right). `relbar1` appears before the document, `relbar2` after the + document. By default, both blocks are filled; to show the relbar only + before the document, you would override `relbar2` like this:: {% block relbar2 %}{% endblock %} @@ -109,7 +118,8 @@ The following blocks exist in the ``layout`` template: the :data:`reldelim1`. `document` - The contents of the document itself. + The contents of the document itself. It contains the block "body" where the + individual content is put by subtemplates like ``page.html``. `sidebar1` / `sidebar2` A possible location for a sidebar. `sidebar1` appears before the document @@ -135,6 +145,10 @@ The following blocks exist in the ``layout`` template: `sidebarrel` The relation links (previous, next document) within the sidebar. +`sidebarsourcelink` + The "Show source" link within the sidebar (normally only shown if this is + enabled by :confval:`html_show_sourcelink`). + `sidebarsearch` The search box within the sidebar. Override this if you want to place some content at the bottom of the sidebar. @@ -162,13 +176,17 @@ using the ``{% set %}`` tag: defaults to ``' |'``. Each item except of the last one in the related bar ends with the value of this variable. -Overriding works like this: - -.. sourcecode:: html+jinja +Overriding works like this:: {% extends "!layout.html" %} {% set reldelim1 = ' >' %} +.. data:: script_files + + Add additional script files here, like this:: + + {% set script_files = script_files + [pathto("_static/myscript.js", 1)] %} + Helper Functions ~~~~~~~~~~~~~~~~ @@ -196,7 +214,7 @@ them to generate links or output multiply used elements. .. function:: relbar() - Return the rendered relbar. + Return the rendered relation bar. Global Variables @@ -206,32 +224,145 @@ These global variables are available in every template and are safe to use. There are more, but most of them are an implementation detail and might change in the future. +.. data:: builder + + The name of the builder (e.g. ``html`` or ``htmlhelp``). + +.. data:: copyright + + The value of :confval:`copyright`. + .. data:: docstitle The title of the documentation (the value of :confval:`html_title`). +.. data:: embedded + + True if the built HTML is meant to be embedded in some viewing application + that handles navigation, not the web browser, such as for HTML help or Qt + help formats. In this case, the sidebar is not included. + +.. data:: favicon + + The path to the HTML favicon in the static path, or ``''``. + +.. data:: file_suffix + + The value of the builder's :attr:`out_suffix` attribute, i.e. the file name + extension that the output files will get. For a standard HTML builder, this + is usually ``.html``. + +.. data:: has_source + + True if the reST document sources are copied (if :confval:`html_copy_source` + is true). + +.. data:: last_updated + + The build date. + +.. data:: logo + + The path to the HTML logo image in the static path, or ``''``. + +.. data:: master_doc + + The value of :confval:`master_doc`, for usage with :func:`pathto`. + +.. data:: next + + The next document for the navigation. This variable is either false or has + two attributes `link` and `title`. The title contains HTML markup. For + example, to generate a link to the next page, you can use this snippet:: + + {% if next %} + {{ next.title }} + {% endif %} + +.. data:: pagename + + The "page name" of the current file, i.e. either the document name if the + file is generated from a reST source, or the equivalent hierarchical name + relative to the output directory (``[directory/]filename_without_extension``). + +.. data:: parents + + A list of parent documents for navigation, structured like the :data:`next` + item. + +.. data:: prev + + Like :data:`next`, but for the previous page. + +.. data:: project + + The value of :confval:`project`. + +.. data:: release + + The value of :confval:`release`. + +.. data:: rellinks + + A list of links to put at the left side of the relbar, next to "next" and + "prev". This usually contains links to the index and the modindex. If you + add something yourself, it must be a tuple ``(pagename, link title, + accesskey, link text)``. + +.. data:: shorttitle + + The value of :confval:`html_short_title`. + +.. data:: show_source + + True if :confval:`html_show_sourcelink` is true. + +.. data:: sphinx_version + + The version of Sphinx used to build. + +.. data:: style + + The name of the main stylesheet, as given by the theme or + :confval:`html_style`. + +.. data:: title + + The title of the current document, as used in the ```` tag. + +.. data:: use_opensearch + + The value of :confval:`html_use_opensearch`. + +.. data:: version + + The value of :confval:`version`. + + +In addition to these values, there are also all **theme options** available +(prefixed by ``theme_``), as well as the values given by the user in +:confval:`html_context`. + +In documents that are created from source files (as opposed to +automatically-generated files like the module index, or documents that already +are in HTML form), these variables are also available: + +.. data:: meta + + Document metadata, see :ref:`metadata`. + .. data:: sourcename The name of the copied source file for the current document. This is only nonempty if the :confval:`html_copy_source` value is true. -.. data:: builder +.. data:: toc - The name of the builder (for builtin builders, ``html``, ``htmlhelp``, or - ``web``). + The local table of contents for the current page, rendered as HTML bullet + lists. -.. data:: next +.. data:: toctree - The next document for the navigation. This variable is either false or has - two attributes `link` and `title`. The title contains HTML markup. For - example, to generate a link to the next page, you can use this snippet: - - .. sourcecode:: html+jinja - - {% if next %} - <a href="{{ next.link|e }}">{{ next.title }}</a> - {% endif %} - -.. data:: prev - - Like :data:`next`, but for the previous page. + A callable yielding the global TOC tree containing the current page, rendered + as HTML bullet lists. If the optional keyword argument ``collapse`` is true, + all TOC entries that are not ancestors of the current page are collapsed. diff --git a/doc/theming.rst b/doc/theming.rst new file mode 100644 index 000000000..3e3a33c8d --- /dev/null +++ b/doc/theming.rst @@ -0,0 +1,187 @@ +.. highlightlang:: python + +HTML theming support +==================== + +.. versionadded:: 0.6 + +Sphinx supports changing the appearance of its HTML output via *themes*. A +theme is a collection of HTML templates, stylesheet(s) and other static files. +Additionally, it has a configuration file which specifies from which theme to +inherit, which highlighting style to use, and what options exist for customizing +the theme's look and feel. + +Themes are meant to be project-unaware, so they can be used for different +projects without change. + + +Using a theme +------------- + +Using an existing theme is easy. If the theme is builtin to Sphinx, you only +need to set the :confval:`html_theme` config value. With the +:confval:`html_theme_options` config value you can set theme-specific options +that change the look and feel. For example, you could have the following in +your :file:`conf.py`:: + + html_theme = "default" + html_theme_options = { + "rightsidebar": "true", + "relbarbgcolor: "black" + } + +That would give you the default theme, but with a sidebar on the right side and +a black background for the relation bar (the bar with the navigation links at +the page's top and bottom). + +If the theme does not come with Sphinx, it can be in two forms: either a +directory (containing :file:`theme.conf` and other needed files), or a zip file +with the same contents. Either of them must be put where Sphinx can find it; +for this there is the config value :confval:`html_theme_path`. It gives a list +of directories, relative to the directory containing :file:`conf.py`, that can +contain theme directories or zip files. For example, if you have a theme in the +file :file:`blue.zip`, you can put it right in the directory containing +:file:`conf.py` and use this configuration:: + + html_theme = "blue" + html_theme_path = ["."] + + +.. _builtin-themes: + +Builtin themes +-------------- + +Sphinx comes with a selection of themes to choose from: + +* **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*): + + - **nosidebar** (true or false): Don't include the sidebar. Defaults to + false. + +* **default** -- This is the default theme. It can be customized via these + options: + + - **rightsidebar** (true or false): Put the sidebar on the right side. + Defaults to false. + + - **stickysidebar** (true or false): Make the sidebar "fixed" so that it + doesn't scroll out of view for long body content. This may not work well + with all browsers. Defaults to false. + + There are also various color and font options that can change the color scheme + without having to write a custom stylesheet: + + - **footerbgcolor** (CSS color): Background color for the footer line. + - **footertextcolor** (CSS color): Text color for the footer line. + - **sidebarbgcolor** (CSS color): Background color for the sidebar. + - **sidebartextcolor** (CSS color): Text color for the sidebar. + - **sidebarlinkcolor** (CSS color): Link color for the sidebar. + - **relbarbgcolor** (CSS color): Background color for the relation bar. + - **relbartextcolor** (CSS color): Text color for the relation bar. + - **relbarlinkcolor** (CSS color): Link color for the relation bar. + - **bgcolor** (CSS color): Body background color. + - **textcolor** (CSS color): Body text color. + - **linkcolor** (CSS color): Body link color. + - **headbgcolor** (CSS color): Background color for headings. + - **headtextcolor** (CSS color): Text color for headings. + - **headlinkcolor** (CSS color): Link color for headings. + - **codebgcolor** (CSS color): Background color for code blocks. + - **codetextcolor** (CSS color): Default text color for code blocks, if not + set differently by the highlighting style. + + - **bodyfont** (CSS font-family): Font for normal text. + - **headfont** (CSS font-family): Font for headings. + +* **sphinxdoc** -- The theme used for this documentation. It features a sidebar + on the right side. There are currently no options beyond *nosidebar*. + +* **traditional** -- A theme resembling the old Python documentation. There are + currently no options beyond *nosidebar*. + + +Creating themes +--------------- + +As said, themes are either a directory or a zipfile (whose name is the theme +name), containing the following: + +* A :file:`theme.conf` file, see below. +* HTML templates, if needed. +* A ``static/`` directory containing any static files that will be copied to the + output statid directory on build. These can be images, styles, script files. + +The :file:`theme.conf` file is in INI format [1]_ (readable by the standard +Python :mod:`ConfigParser` module) and has the following structure: + +.. sourcecode:: ini + + [theme] + inherit = base theme + stylesheet = main CSS name + pygments_style = stylename + + [options] + variable = default value + +* The **inherit** setting gives the name of a "base theme", or ``none``. The + base theme will be used to locate missing templates (most themes will not have + to supply most templates if they use ``basic`` as the base theme), its options + will be inherited, and all of its static files will be used as well. + +* The **stylesheet** setting gives the name of a CSS file which will be + referenced in the HTML header. If you need more than one CSS file, either + include one from the other via CSS' ``@import``, or use a custom HTML template + that adds ``<link rel="stylesheet">`` tags as necessary. Setting the + :confval:`html_style` config value will override this setting. + +* The **pygments_style** setting gives the name of a Pygments style to use for + highlighting. This can be overridden by the user in the + :confval:`pygments_style` config value. + +* The **options** section contains pairs of variable names and default values. + These options can be overridden by the user in :confval:`html_theme_options` + and are accessible from all templates as ``theme_<name>``. + + +Templating +~~~~~~~~~~ + +The :doc:`guide to templating <templating>` is helpful if you want to write your +own templates. What is important to keep in mind is the order in which Sphinx +searches for templates: + +* First, in the user's ``templates_path`` directories. +* Then, in the selected theme. +* Then, in its base theme, its base's base theme, etc. + +When extending a template in the base theme with the same name, use the theme +name as an explicit directory: ``{% extends "basic/layout.html" %}``. From a +user ``templates_path`` template, you can still use the "exclamation mark" +syntax as described in the templating document. + + +Static templates +~~~~~~~~~~~~~~~~ + +Since theme options are meant for the user to configure a theme more easily, +without having to write a custom stylesheet, it is necessary to be able to +template static files as well as HTML files. Therefore, Sphinx supports +so-called "static templates", like this: + +If the name of a file in the ``static/`` directory of a theme (or in the user's +static path, for that matter) ends with ``_t``, it will be processed by the +template engine. The ``_t`` will be left from the final file name. For +example, the *default* theme has a file ``static/default.css_t`` which uses +templating to put the color options into the stylesheet. When a documentation +is built with the default theme, the output directory will contain a +``_static/default.css`` file where all template tags have been processed. + + +.. [1] It is not an executable Python file, as opposed to :file:`conf.py`, + because that would pose an unnecessary security risk if themes are + shared. + diff --git a/ez_setup.py b/ez_setup.py index 89cf056d9..d24e845e5 100644 --- a/ez_setup.py +++ b/ez_setup.py @@ -14,7 +14,7 @@ the appropriate options to ``use_setuptools()``. This file can also be run as a script to install or upgrade setuptools. """ import sys -DEFAULT_VERSION = "0.6c8" +DEFAULT_VERSION = "0.6c9" DEFAULT_URL = "http://pypi.python.org/packages/%s/s/setuptools/" % sys.version[:3] md5_data = { @@ -48,13 +48,18 @@ md5_data = { 'setuptools-0.6c8-py2.3.egg': '50759d29b349db8cfd807ba8303f1902', 'setuptools-0.6c8-py2.4.egg': 'cba38d74f7d483c06e9daa6070cce6de', 'setuptools-0.6c8-py2.5.egg': '1721747ee329dc150590a58b3e1ac95b', + 'setuptools-0.6c9-py2.3.egg': 'a83c4020414807b496e4cfbe08507c03', + 'setuptools-0.6c9-py2.4.egg': '260a2be2e5388d66bdaee06abec6342a', + 'setuptools-0.6c9-py2.5.egg': 'fe67c3e5a17b12c0e7c541b7ea43a8e6', + 'setuptools-0.6c9-py2.6.egg': 'ca37b1ff16fa2ede6e19383e7b59245a', } import sys, os +try: from hashlib import md5 +except ImportError: from md5 import md5 def _validate_md5(egg_name, data): if egg_name in md5_data: - from md5 import md5 digest = md5(data).hexdigest() if digest != md5_data[egg_name]: print >>sys.stderr, ( @@ -64,7 +69,6 @@ def _validate_md5(egg_name, data): sys.exit(2) return data - def use_setuptools( version=DEFAULT_VERSION, download_base=DEFAULT_URL, to_dir=os.curdir, download_delay=15 @@ -233,7 +237,6 @@ def update_md5(filenames): """Update our built-in md5 registry""" import re - from md5 import md5 for name in filenames: base = os.path.basename(name) @@ -270,3 +273,4 @@ if __name__=='__main__': + diff --git a/setup.py b/setup.py index 13e70690e..ffecc8444 100644 --- a/setup.py +++ b/setup.py @@ -24,7 +24,7 @@ parsing and translating suite, the Docutils. Although it is still under constant development, the following features are already present, work fine and can be seen "in action" in the Python docs: -* Output formats: HTML (including Windows HTML Help) and LaTeX, +* Output formats: HTML (including Windows HTML Help), plain text and LaTeX, for printable PDF versions * Extensive cross-references: semantic markup and automatic links for functions, classes, glossary terms and similar pieces of information @@ -36,7 +36,7 @@ are already present, work fine and can be seen "in action" in the Python docs: and inclusion of appropriately formatted docstrings. ''' -requires = ['Pygments>=0.8', 'Jinja>=1.1', 'docutils>=0.4'] +requires = ['Pygments>=0.8', 'Jinja2>=2.1', 'docutils>=0.4'] if sys.version_info < (2, 4): print 'ERROR: Sphinx requires at least Python 2.4 to run.' @@ -98,7 +98,8 @@ else: else: for locale in os.listdir(self.directory): po_file = os.path.join(self.directory, locale, - 'LC_MESSAGES', self.domain + '.po') + 'LC_MESSAGES', + self.domain + '.po') if os.path.exists(po_file): po_files.append((locale, po_file)) js_files.append(os.path.join(self.directory, locale, diff --git a/sphinx-build.py b/sphinx-build.py index 4e2a868d9..c1998911d 100755 --- a/sphinx-build.py +++ b/sphinx-build.py @@ -4,8 +4,8 @@ Sphinx - Python documentation toolchain ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - :copyright: 2007-2008 by Georg Brandl. - :license: BSD. + :copyright: Copyright 2007-2009 by the Sphinx team, see AUTHORS. + :license: BSD, see LICENSE for details. """ import sys diff --git a/sphinx-quickstart.py b/sphinx-quickstart.py index 579b35587..ea55f8341 100755 --- a/sphinx-quickstart.py +++ b/sphinx-quickstart.py @@ -4,8 +4,8 @@ Sphinx - Python documentation toolchain ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - :copyright: 2008 by Georg Brandl. - :license: BSD. + :copyright: Copyright 2007-2009 by the Sphinx team, see AUTHORS. + :license: BSD, see LICENSE for details. """ import sys diff --git a/sphinx/__init__.py b/sphinx/__init__.py index ccd49e533..e0d8813f4 100644 --- a/sphinx/__init__.py +++ b/sphinx/__init__.py @@ -5,199 +5,52 @@ The Sphinx documentation toolchain. - :copyright: 2007-2008 by Georg Brandl. - :license: BSD. + :copyright: Copyright 2007-2009 by the Sphinx team, see AUTHORS. + :license: BSD, see LICENSE for details. """ -import os import sys -import getopt -import traceback from os import path -from cStringIO import StringIO - -from sphinx.util import format_exception_cut_frames, save_traceback -from sphinx.util.console import darkred, nocolor, color_terminal __revision__ = '$Revision$' -__version__ = '0.5' -__released__ = '0.5 (hg)' +__version__ = '0.6' +__released__ = '0.6 (hg)' - -def usage(argv, msg=None): - if msg: - print >>sys.stderr, msg - print >>sys.stderr - print >>sys.stderr, """\ -Sphinx v%s -Usage: %s [options] sourcedir outdir [filenames...] -Options: -b <builder> -- builder to use; default is html - -a -- write all files; default is to only write new and changed files - -E -- don't use a saved environment, always read all files - -d <path> -- path for the cached environment and doctree files - (default: outdir/.doctrees) - -c <path> -- path where configuration file (conf.py) is located - (default: same as sourcedir) - -D <setting=value> -- override a setting in configuration - -A <name=value> -- pass a value into the templates, for HTML builder - -N -- do not do colored output - -q -- no output on stdout, just warnings on stderr - -Q -- no output at all, not even warnings - -P -- run Pdb on exception - -g <path> -- create autogenerated files -Modi: -* without -a and without filenames, write new and changed files. -* with -a, write all files. -* with filenames, write these.""" % (__version__, argv[0]) +package_dir = path.abspath(path.dirname(__file__)) def main(argv=sys.argv): - # delay-import these to be able to get sphinx.__version__ from setup.py - # even without docutils installed - from sphinx.application import Sphinx, SphinxError - from docutils.utils import SystemMessage - - if not sys.stdout.isatty() or not color_terminal(): - # Windows' poor cmd box doesn't understand ANSI sequences - nocolor() + if sys.version_info[:3] < (2, 4, 0): + print >>sys.stderr, \ + 'Error: Sphinx requires at least Python 2.4 to run.' + return 1 try: - opts, args = getopt.getopt(argv[1:], 'ab:d:c:D:A:g:NEqP') - srcdir = confdir = path.abspath(args[0]) - if not path.isdir(srcdir): - print >>sys.stderr, 'Error: Cannot find source directory.' - return 1 - if not path.isfile(path.join(srcdir, 'conf.py')) and \ - '-c' not in (opt[0] for opt in opts): - print >>sys.stderr, 'Error: Source directory doesn\'t contain conf.py file.' - return 1 - outdir = path.abspath(args[1]) - if not path.isdir(outdir): - print >>sys.stderr, 'Making output directory...' - os.makedirs(outdir) - except (IndexError, getopt.error): - usage(argv) - return 1 - - filenames = args[2:] - err = 0 - for filename in filenames: - if not path.isfile(filename): - print >>sys.stderr, 'Cannot find file %r.' % filename - err = 1 - if err: - return 1 - - - buildername = all_files = None - freshenv = use_pdb = False - status = sys.stdout - warning = sys.stderr - confoverrides = {} - htmlcontext = {} - doctreedir = path.join(outdir, '.doctrees') - for opt, val in opts: - - if opt == '-g': - source_filenames =[srcdir+'/'+f for f in os.listdir(srcdir) if f.endswith('.rst')] - if val is None: - print >>sys.stderr, \ - 'Error: you must provide a destination directory for autodoc generation.' - return 1 - p = path.abspath(val) - from sphinx.ext.autosummary.generate import generate_autosummary_docs - generate_autosummary_docs(source_filenames, p) - - elif opt == '-b': - buildername = val - elif opt == '-a': - if filenames: - usage(argv, 'Cannot combine -a option and filenames.') - return 1 - all_files = True - elif opt == '-d': - doctreedir = path.abspath(val) - elif opt == '-c': - confdir = path.abspath(val) - if not path.isfile(path.join(confdir, 'conf.py')): - print >>sys.stderr, \ - 'Error: Configuration directory doesn\'t contain conf.py file.' - return 1 - elif opt == '-D': - try: - key, val = val.split('=') - except ValueError: - print >>sys.stderr, \ - 'Error: -D option argument must be in the form name=value.' - return 1 - try: - val = int(val) - except ValueError: - pass - confoverrides[key] = val - elif opt == '-A': - try: - key, val = val.split('=') - except ValueError: - print >>sys.stderr, \ - 'Error: -A option argument must be in the form name=value.' - return 1 - try: - val = int(val) - except ValueError: - pass - htmlcontext[key] = val - elif opt == '-N': - nocolor() - elif opt == '-E': - freshenv = True - elif opt == '-q': - status = StringIO() - elif opt == '-Q': - status = StringIO() - warning = StringIO() - elif opt == '-P': - use_pdb = True - confoverrides['html_context'] = htmlcontext - - try: - app = Sphinx(srcdir, confdir, outdir, doctreedir, buildername, - confoverrides, status, warning, freshenv) - app.build(all_files, filenames) - except KeyboardInterrupt: - if use_pdb: - import pdb - print >>sys.stderr, darkred('Interrupted while building, starting debugger:') - traceback.print_exc() - pdb.post_mortem(sys.exc_info()[2]) - return 1 - except Exception, err: - if use_pdb: - import pdb - print >>sys.stderr, darkred('Exception occurred while building, ' - 'starting debugger:') - traceback.print_exc() - pdb.post_mortem(sys.exc_info()[2]) - else: - if isinstance(err, SystemMessage): - print >>sys.stderr, darkred('reST markup error:') - print >>sys.stderr, err.args[0].encode('ascii', 'backslashreplace') - elif isinstance(err, SphinxError): - print >>sys.stderr, darkred('%s:' % err.category) - print >>sys.stderr, err + from sphinx import cmdline + except ImportError, err: + errstr = str(err) + if errstr.lower().startswith('no module named'): + whichmod = errstr[16:] + hint = '' + if whichmod.startswith('docutils'): + whichmod = 'Docutils library' + elif whichmod.startswith('jinja'): + whichmod = 'Jinja library' + elif whichmod == 'roman': + whichmod = 'roman module (which is distributed with Docutils)' + hint = ('This can happen if you upgraded docutils using\n' + 'easy_install without uninstalling the old version' + 'first.') else: - print >>sys.stderr, darkred('Exception occurred:') - print >>sys.stderr, format_exception_cut_frames().rstrip() - tbpath = save_traceback() - print >>sys.stderr, darkred('The full traceback has been saved ' - 'in %s, if you want to report the ' - 'issue to the author.' % tbpath) - print >>sys.stderr, ('Please also report this if it was a user ' - 'error, so that a better error message ' - 'can be provided next time.') - print >>sys.stderr, ('Send reports to sphinx-dev@googlegroups.com. ' - 'Thanks!') + whichmod += ' module' + print >>sys.stderr, \ + 'Error: The %s cannot be found. Did you install Sphinx '\ + 'and its dependencies correctly?' % whichmod + if hint: + print >> sys.stderr, hint return 1 + raise + return cmdline.main(argv) if __name__ == '__main__': diff --git a/sphinx/_jinja.py b/sphinx/_jinja.py deleted file mode 100644 index d6e98b214..000000000 --- a/sphinx/_jinja.py +++ /dev/null @@ -1,113 +0,0 @@ -# -*- coding: utf-8 -*- -""" - sphinx._jinja - ~~~~~~~~~~~~~ - - Jinja glue. - - :copyright: 2007-2008 by Georg Brandl, Horst Gutmann. - :license: BSD. -""" - -import codecs -from os import path - -from sphinx.util import mtimes_of_files -from sphinx.application import TemplateBridge - -from jinja import Environment -from jinja.loaders import BaseLoader -from jinja.exceptions import TemplateNotFound - - -def babel_extract(fileobj, keywords, comment_tags, options): - """ - Simple extractor to get some basic Babel support. - """ - env = Environment() - for lineno, sg, pl in env.get_translations_for_string(fileobj.read()): - yield lineno, None, (sg, pl), '' - - -class SphinxFileSystemLoader(BaseLoader): - """ - A loader that loads templates either relative to one of a list of given - paths, or from an absolute path. - """ - - def __init__(self, basepath, extpaths): - self.basepath = path.abspath(basepath) - self.extpaths = map(path.abspath, extpaths) - self.searchpaths = self.extpaths + [self.basepath] - - def get_source(self, environment, name, parent): - name = name.replace('/', path.sep) - if name.startswith('!'): - name = name[1:] - if not path.exists(path.join(self.basepath, name)): - raise TemplateNotFound(name) - filename = path.join(self.basepath, name) - elif path.isabs(name): - if not path.exists(name): - raise TemplateNotFound(name) - filename = name - else: - for searchpath in self.searchpaths: - if path.exists(path.join(searchpath, name)): - filename = path.join(searchpath, name) - break - else: - raise TemplateNotFound(name) - f = codecs.open(filename, 'r', environment.template_charset) - try: - return f.read() - finally: - f.close() - - -class TranslatorEnvironment(Environment): - class _Translator(object): - def __init__(self, translator): - self.trans = translator - - def gettext(self, string): - return self.trans.ugettext(string) - - def ngettext(self, singular, plural, n): - return self.trans.ungettext(singular, plural, n) - - def __init__(self, *args, **kwargs): - self.translator = kwargs['translator'] - del kwargs['translator'] - super(TranslatorEnvironment, self).__init__(*args, **kwargs) - - def get_translator(self, context): - return TranslatorEnvironment._Translator(self.translator) - - -class BuiltinTemplates(TemplateBridge): - def init(self, builder): - self.templates = {} - base_templates_path = path.join(path.dirname(__file__), 'templates') - ext_templates_path = [path.join(builder.confdir, dir) - for dir in builder.config.templates_path] - self.templates_path = [base_templates_path] + ext_templates_path - loader = SphinxFileSystemLoader(base_templates_path, ext_templates_path) - if builder.translator is not None: - self.jinja_env = TranslatorEnvironment(loader=loader, - friendly_traceback=False, translator=builder.translator) - else: - self.jinja_env = Environment(loader=loader, - # disable traceback, more likely that something - # in the application is broken than in the templates - friendly_traceback=False) - - def newest_template_mtime(self): - return max(mtimes_of_files(self.templates_path, '.html')) - - def render(self, template, context): - if template in self.templates: - return self.templates[template].render(context) - templateobj = self.templates[template] = \ - self.jinja_env.get_template(template) - return templateobj.render(context) diff --git a/sphinx/addnodes.py b/sphinx/addnodes.py index 8b20f7ac0..63907a0e6 100644 --- a/sphinx/addnodes.py +++ b/sphinx/addnodes.py @@ -5,8 +5,8 @@ Additional docutils nodes. - :copyright: 2007-2008 by Georg Brandl. - :license: BSD. + :copyright: Copyright 2007-2009 by the Sphinx team, see AUTHORS. + :license: BSD, see LICENSE for details. """ from docutils import nodes @@ -23,8 +23,12 @@ class desc(nodes.Admonition, nodes.Element): pass class desc_addname(nodes.Part, nodes.Inline, nodes.TextElement): pass # compatibility alias desc_classname = desc_addname -# return type (C); object type, e.g. -> annotation (Python) +# return type (C); object type class desc_type(nodes.Part, nodes.Inline, nodes.TextElement): pass +# -> annotation (Python) +class desc_returns(desc_type): + def astext(self): + return ' -> ' + nodes.TextElement.astext(self) # main name of object class desc_name(nodes.Part, nodes.Inline, nodes.TextElement): pass # argument list @@ -64,15 +68,25 @@ class pending_xref(nodes.Element): pass # compact paragraph -- never makes a <p> class compact_paragraph(nodes.paragraph): pass +# reference to a file to download +class download_reference(nodes.reference): pass + # for the ACKS list class acks(nodes.Element): pass +# for horizontal lists +class hlist(nodes.Element): pass +class hlistcol(nodes.Element): pass + # sets the highlighting language for literal blocks class highlightlang(nodes.Element): pass # like emphasis, but doesn't apply further text processors, e.g. smartypants class literal_emphasis(nodes.emphasis): pass +# for abbreviations (with explanations) +class abbreviation(nodes.Inline, nodes.TextElement): pass + # glossary class glossary(nodes.Element): pass @@ -85,13 +99,18 @@ class start_of_file(nodes.Element): pass # tabular column specification, used for the LaTeX writer class tabular_col_spec(nodes.Element): pass +# only (in/exclusion based on tags) +class only(nodes.Element): pass + # meta directive -- same as docutils' standard meta node, but pickleable class meta(nodes.Special, nodes.PreBibliographic, nodes.Element): pass # make them known to docutils. this is needed, because the HTML writer # will choke at some point if these are not added -nodes._add_node_class_names("""index desc desc_content desc_signature desc_type - desc_addname desc_name desc_parameterlist desc_parameter desc_optional +nodes._add_node_class_names("""index desc desc_content desc_signature + desc_type desc_returns desc_addname desc_name desc_parameterlist + desc_parameter desc_optional download_reference hlist hlistcol centered versionmodified seealso productionlist production toctree pending_xref compact_paragraph highlightlang literal_emphasis - glossary acks module start_of_file tabular_col_spec meta""".split()) + abbreviation glossary acks module start_of_file tabular_col_spec + meta""".split()) diff --git a/sphinx/application.py b/sphinx/application.py index 4ac520fe1..9c4670660 100644 --- a/sphinx/application.py +++ b/sphinx/application.py @@ -7,13 +7,14 @@ Gracefully adapted from the TextPress system by Armin. - - :copyright: 2008 by Georg Brandl, Armin Ronacher. - :license: BSD. + :copyright: Copyright 2007-2009 by the Sphinx team, see AUTHORS. + :license: BSD, see LICENSE for details. """ import sys +import types import posixpath +from cStringIO import StringIO from docutils import nodes from docutils.parsers.rst import directives, roles @@ -21,43 +22,22 @@ from docutils.parsers.rst import directives, roles import sphinx from sphinx.roles import xfileref_role, innernodetypes from sphinx.config import Config -from sphinx.builder import builtin_builders, StandaloneHTMLBuilder -from sphinx.directives import desc_directive, target_directive, additional_xref_types +from sphinx.errors import SphinxError, SphinxWarning, ExtensionError +from sphinx.builders import BUILTIN_BUILDERS +from sphinx.directives import GenericDesc, Target, additional_xref_types from sphinx.environment import SphinxStandaloneReader +from sphinx.util.tags import Tags +from sphinx.util.compat import Directive, directive_dwim from sphinx.util.console import bold -class SphinxError(Exception): - """ - Base class for Sphinx errors that are shown to the user in a nicer - way than normal exceptions. - """ - category = 'Sphinx error' - -class ExtensionError(SphinxError): - """Raised if something's wrong with the configuration.""" - category = 'Extension error' - - def __init__(self, message, orig_exc=None): - super(ExtensionError, self).__init__(message) - self.orig_exc = orig_exc - - def __repr__(self): - if self.orig_exc: - return '%s(%r, %r)' % (self.__class__.__name__, - self.message, self.orig_exc) - return '%s(%r)' % (self.__class__.__name__, self.message) - - def __str__(self): - parent_str = super(ExtensionError, self).__str__() - if self.orig_exc: - return '%s (exception: %s)' % (parent_str, self.orig_exc) - return parent_str - +# Directive is either new-style or old-style +clstypes = (type, types.ClassType) # List of all known core events. Maps name to arguments description. events = { 'builder-inited': '', + 'env-purge-doc': 'env, docname', 'source-read': 'docname, source text', 'doctree-read': 'the doctree before being pickled', 'missing-reference': 'env, node, contnode', @@ -69,13 +49,16 @@ events = { CONFIG_FILENAME = 'conf.py' + class Sphinx(object): def __init__(self, srcdir, confdir, outdir, doctreedir, buildername, - confoverrides, status, warning=sys.stderr, freshenv=False): + confoverrides, status, warning=sys.stderr, freshenv=False, + warningiserror=False, tags=None): self.next_listener_id = 0 + self._extensions = {} self._listeners = {} - self.builderclasses = builtin_builders.copy() + self.builderclasses = BUILTIN_BUILDERS.copy() self.builder = None self.srcdir = srcdir @@ -83,14 +66,28 @@ class Sphinx(object): self.outdir = outdir self.doctreedir = doctreedir - self._status = status - self._warning = warning + if status is None: + self._status = StringIO() + self.quiet = True + else: + self._status = status + self.quiet = False + + if warning is None: + self._warning = StringIO() + else: + self._warning = warning self._warncount = 0 + self.warningiserror = warningiserror self._events = events.copy() + # status code for command-line application + self.statuscode = 0 + # read config - self.config = Config(confdir, CONFIG_FILENAME, confoverrides) + self.tags = Tags(tags) + self.config = Config(confdir, CONFIG_FILENAME, confoverrides, self.tags) # load all extension modules for extension in self.config.extensions: @@ -108,10 +105,18 @@ class Sphinx(object): if buildername not in self.builderclasses: raise SphinxError('Builder name %s not registered' % buildername) - self.info(bold('Sphinx v%s, building %s' % (sphinx.__version__, buildername))) + self.info(bold('Sphinx v%s, building %s' % (sphinx.__released__, + buildername))) builderclass = self.builderclasses[buildername] + if isinstance(builderclass, tuple): + # builtin builder + mod, cls = builderclass + builderclass = getattr( + __import__('sphinx.builders.' + mod, None, None, [cls]), cls) self.builder = builderclass(self, freshenv=freshenv) + self.builder.tags = self.tags + self.builder.tags.add(self.builder.format) self.emit('builder-inited') def build(self, all_files, filenames): @@ -127,28 +132,44 @@ class Sphinx(object): raise else: self.emit('build-finished', None) + self.builder.cleanup() - def warn(self, message): + def warn(self, message, location=None, prefix='WARNING: '): + warntext = location and '%s: %s%s\n' % (location, prefix, message) or \ + '%s%s\n' % (prefix, message) + if self.warningiserror: + raise SphinxWarning(warntext) self._warncount += 1 - self._warning.write('WARNING: %s\n' % message) + try: + self._warning.write(warntext) + except UnicodeEncodeError: + encoding = getattr(self._warning, 'encoding', 'ascii') + self._warning.write(warntext.encode(encoding, 'replace')) def info(self, message='', nonl=False): - if nonl: + try: self._status.write(message) - else: - self._status.write(message + '\n') + except UnicodeEncodeError: + encoding = getattr(self._status, 'encoding', 'ascii') + self._status.write(message.encode(encoding, 'replace')) + if not nonl: + self._status.write('\n') self._status.flush() # general extensibility interface def setup_extension(self, extension): - """Import and setup a Sphinx extension module.""" + """Import and setup a Sphinx extension module. No-op if called twice.""" + if extension in self._extensions: + return try: mod = __import__(extension, None, None, ['setup']) except ImportError, err: - raise ExtensionError('Could not import extension %s' % extension, err) + raise ExtensionError('Could not import extension %s' % extension, + err) if hasattr(mod, 'setup'): mod.setup(self) + self._extensions[extension] = mod def import_object(self, objname, source=None): """Import an object from a 'module.name' string.""" @@ -156,15 +177,18 @@ class Sphinx(object): module, name = objname.rsplit('.', 1) except ValueError, err: raise ExtensionError('Invalid full object name %s' % objname + - (source and ' (needed for %s)' % source or ''), err) + (source and ' (needed for %s)' % source or ''), + err) try: return getattr(__import__(module, None, None, [name]), name) except ImportError, err: raise ExtensionError('Could not import %s' % module + - (source and ' (needed for %s)' % source or ''), err) + (source and ' (needed for %s)' % source or ''), + err) except AttributeError, err: raise ExtensionError('Could not find %s' % objname + - (source and ' (needed for %s)' % source or ''), err) + (source and ' (needed for %s)' % source or ''), + err) # event interface @@ -204,16 +228,24 @@ class Sphinx(object): def add_builder(self, builder): if not hasattr(builder, 'name'): - raise ExtensionError('Builder class %s has no "name" attribute' % builder) + raise ExtensionError('Builder class %s has no "name" attribute' + % builder) if builder.name in self.builderclasses: - raise ExtensionError('Builder %r already exists (in module %s)' % ( - builder.name, self.builderclasses[builder.name].__module__)) + if isinstance(self.builderclasses[builder.name], tuple): + raise ExtensionError('Builder %r is a builtin builder' % + builder.name) + else: + raise ExtensionError( + 'Builder %r already exists (in module %s)' % ( + builder.name, self.builderclasses[builder.name].__module__)) self.builderclasses[builder.name] = builder - def add_config_value(self, name, default, rebuild_env): + def add_config_value(self, name, default, rebuild): if name in self.config.values: raise ExtensionError('Config value %r already present' % name) - self.config.values[name] = (default, rebuild_env) + if rebuild in (False, True): + rebuild = rebuild and 'env' or '' + self.config.values[name] = (default, rebuild) def add_event(self, name): if name in self._events: @@ -226,14 +258,14 @@ class Sphinx(object): try: visit, depart = val except ValueError: - raise ExtensionError('Value for key %r must be a (visit, depart) ' - 'function tuple' % key) + raise ExtensionError('Value for key %r must be a ' + '(visit, depart) function tuple' % key) if key == 'html': - from sphinx.htmlwriter import HTMLTranslator as translator + from sphinx.writers.html import HTMLTranslator as translator elif key == 'latex': - from sphinx.latexwriter import LaTeXTranslator as translator + from sphinx.writers.latex import LaTeXTranslator as translator elif key == 'text': - from sphinx.textwriter import TextTranslator as translator + from sphinx.writers.text import TextTranslator as translator else: # ignore invalid keys for compatibility continue @@ -241,28 +273,42 @@ class Sphinx(object): if depart: setattr(translator, 'depart_'+node.__name__, depart) - def add_directive(self, name, func, content, arguments, **options): - func.content = content - func.arguments = arguments - func.options = options - directives.register_directive(name, func) + def add_directive(self, name, obj, content=None, arguments=None, **options): + if isinstance(obj, clstypes) and issubclass(obj, Directive): + if content or arguments or options: + raise ExtensionError('when adding directive classes, no ' + 'additional arguments may be given') + directives.register_directive(name, directive_dwim(obj)) + else: + obj.content = content + obj.arguments = arguments + obj.options = options + directives.register_directive(name, obj) def add_role(self, name, role): - roles.register_canonical_role(name, role) + roles.register_local_role(name, role) + + def add_generic_role(self, name, nodeclass): + # don't use roles.register_generic_role because it uses + # register_canonical_role + role = roles.GenericRole(name, nodeclass) + roles.register_local_role(name, role) def add_description_unit(self, directivename, rolename, indextemplate='', parse_node=None, ref_nodeclass=None): - additional_xref_types[directivename] = (rolename, indextemplate, parse_node) - directives.register_directive(directivename, desc_directive) - roles.register_canonical_role(rolename, xfileref_role) + additional_xref_types[directivename] = (rolename, indextemplate, + parse_node) + directives.register_directive(directivename, + directive_dwim(GenericDesc)) + roles.register_local_role(rolename, xfileref_role) if ref_nodeclass is not None: innernodetypes[rolename] = ref_nodeclass def add_crossref_type(self, directivename, rolename, indextemplate='', ref_nodeclass=None): additional_xref_types[directivename] = (rolename, indextemplate, None) - directives.register_directive(directivename, target_directive) - roles.register_canonical_role(rolename, xfileref_role) + directives.register_directive(directivename, directive_dwim(Target)) + roles.register_local_role(rolename, xfileref_role) if ref_nodeclass is not None: innernodetypes[rolename] = ref_nodeclass @@ -270,9 +316,25 @@ class Sphinx(object): SphinxStandaloneReader.transforms.append(transform) def add_javascript(self, filename): + from sphinx.builders.html import StandaloneHTMLBuilder StandaloneHTMLBuilder.script_files.append( posixpath.join('_static', filename)) + def add_lexer(self, alias, lexer): + from sphinx.highlighting import lexers + if lexers is None: + return + lexers[alias] = lexer + + def add_autodocumenter(self, cls): + from sphinx.ext import autodoc + autodoc.add_documenter(cls) + self.add_directive('auto' + cls.objtype, autodoc.AutoDirective) + + def add_autodoc_attrgetter(self, type, getter): + from sphinx.ext import autodoc + autodoc.AutoDirective._special_attrgetters[type] = getter + class TemplateBridge(object): """ @@ -280,11 +342,15 @@ class TemplateBridge(object): that renders templates given a template name and a context. """ - def init(self, builder): + def init(self, builder, theme=None, dirs=None): """ - Called by the builder to initialize the template system. *builder* - is the builder object; you'll probably want to look at the value of - ``builder.config.templates_path``. + Called by the builder to initialize the template system. + + *builder* is the builder object; you'll probably want to look at the + value of ``builder.config.templates_path``. + + *theme* is a :class:`sphinx.theming.Theme` object or None; in the latter + case, *dirs* can be list of fixed directories to look for templates. """ raise NotImplementedError('must be implemented in subclasses') @@ -298,7 +364,14 @@ class TemplateBridge(object): def render(self, template, context): """ - Called by the builder to render a *template* with a specified - context (a Python dictionary). + Called by the builder to render a template given as a filename with a + specified context (a Python dictionary). + """ + raise NotImplementedError('must be implemented in subclasses') + + def render_string(self, template, context): + """ + Called by the builder to render a template given as a string with a + specified context (a Python dictionary). """ raise NotImplementedError('must be implemented in subclasses') diff --git a/sphinx/builder.py b/sphinx/builder.py index 5448573a7..13c56e18f 100644 --- a/sphinx/builder.py +++ b/sphinx/builder.py @@ -3,1268 +3,26 @@ sphinx.builder ~~~~~~~~~~~~~~ - Builder classes for different output formats. + .. warning:: - :copyright: 2007-2008 by Georg Brandl, Sebastian Wiesner, Horst Gutmann. - :license: BSD. + This module is only kept for API compatibility; new code should + import these classes directly from the sphinx.builders package. + + :copyright: Copyright 2007-2009 by the Sphinx team, see AUTHORS. + :license: BSD, see LICENSE for details. """ -import os -import time -import codecs -import shutil -import gettext -import cPickle as pickle -from os import path -from cgi import escape - -from docutils import nodes -from docutils.io import StringOutput, FileOutput, DocTreeInput -from docutils.core import publish_parts -from docutils.utils import new_document -from docutils.frontend import OptionParser -from docutils.readers.doctree import Reader as DoctreeReader - -from sphinx import addnodes, locale, __version__ -from sphinx.util import ensuredir, relative_uri, SEP, os_path, texescape -from sphinx.htmlhelp import build_hhx -from sphinx.htmlwriter import HTMLWriter, HTMLTranslator, SmartyPantsHTMLTranslator -from sphinx.textwriter import TextWriter -from sphinx.latexwriter import LaTeXWriter -from sphinx.environment import BuildEnvironment, NoUri -from sphinx.highlighting import PygmentsBridge -from sphinx.util.console import bold, purple, darkgreen -from sphinx.search import js_index - -try: - import json -except ImportError: - try: - import ssimplejson as json - except ImportError: - json = None - -# side effect: registers roles and directives -from sphinx import roles -from sphinx import directives - -ENV_PICKLE_FILENAME = 'environment.pickle' -LAST_BUILD_FILENAME = 'last_build' -INVENTORY_FILENAME = 'objects.inv' - - -class Builder(object): - """ - Builds target formats from the reST sources. - """ - - # builder's name, for the -b command line options - name = '' - - def __init__(self, app, env=None, freshenv=False): - self.srcdir = app.srcdir - self.confdir = app.confdir - self.outdir = app.outdir - self.doctreedir = app.doctreedir - if not path.isdir(self.doctreedir): - os.makedirs(self.doctreedir) - - self.app = app - self.warn = app.warn - self.info = app.info - self.config = app.config - - self.load_i18n() - - # images that need to be copied over (source -> dest) - self.images = {} - - # if None, this is set in load_env() - self.env = env - self.freshenv = freshenv - - self.init() - self.load_env() - - # helper methods - - def init(self): - """Load necessary templates and perform initialization.""" - raise NotImplementedError - - def init_templates(self): - # Call this from init() if you need templates. - if self.config.template_bridge: - self.templates = self.app.import_object( - self.config.template_bridge, 'template_bridge setting')() - else: - from sphinx._jinja import BuiltinTemplates - self.templates = BuiltinTemplates() - self.templates.init(self) - - def get_target_uri(self, docname, typ=None): - """ - Return the target URI for a document name (typ can be used to qualify - the link characteristic for individual builders). - """ - raise NotImplementedError - - def get_relative_uri(self, from_, to, typ=None): - """ - Return a relative URI between two source filenames. May raise environment.NoUri - if there's no way to return a sensible URI. - """ - return relative_uri(self.get_target_uri(from_), - self.get_target_uri(to, typ)) - - def get_outdated_docs(self): - """ - Return an iterable of output files that are outdated, or a string describing - what an update build will build. - """ - raise NotImplementedError - - def status_iterator(self, iterable, summary, colorfunc=darkgreen): - l = -1 - for item in iterable: - if l == -1: - self.info(bold(summary), nonl=1) - l = 0 - self.info(colorfunc(item) + ' ', nonl=1) - yield item - if l == 0: - self.info() - - supported_image_types = [] - - def post_process_images(self, doctree): - """ - Pick the best candidate for all image URIs. - """ - for node in doctree.traverse(nodes.image): - if '?' in node['candidates']: - # don't rewrite nonlocal image URIs - continue - if '*' not in node['candidates']: - for imgtype in self.supported_image_types: - candidate = node['candidates'].get(imgtype, None) - if candidate: - break - else: - self.warn('%s:%s: no matching candidate for image URI %r' % - (node.source, getattr(node, 'lineno', ''), node['uri'])) - continue - node['uri'] = candidate - else: - candidate = node['uri'] - if candidate not in self.env.images: - # non-existing URI; let it alone - continue - self.images[candidate] = self.env.images[candidate][1] - - # build methods - - def load_i18n(self): - """ - Load translated strings from the configured localedirs if - enabled in the configuration. - """ - self.translator = None - if self.config.language is not None: - self.info(bold('loading translations [%s]... ' % self.config.language), - nonl=True) - locale_dirs = [path.join(path.dirname(__file__), 'locale')] + \ - [path.join(self.srcdir, x) for x in self.config.locale_dirs] - for dir_ in locale_dirs: - try: - trans = gettext.translation('sphinx', localedir=dir_, - languages=[self.config.language]) - if self.translator is None: - self.translator = trans - else: - self.translator._catalog.update(trans.catalog) - except Exception: - # Language couldn't be found in the specified path - pass - if self.translator is not None: - self.info('done') - else: - self.info('locale not available') - if self.translator is None: - self.translator = gettext.NullTranslations() - self.translator.install(unicode=True) - locale.init() # translate common labels - - def load_env(self): - """Set up the build environment.""" - if self.env: - return - if not self.freshenv: - try: - self.info(bold('loading pickled environment... '), nonl=True) - self.env = BuildEnvironment.frompickle(self.config, - path.join(self.doctreedir, ENV_PICKLE_FILENAME)) - self.info('done') - except Exception, err: - if type(err) is IOError and err.errno == 2: - self.info('not found') - else: - self.info('failed: %s' % err) - self.env = BuildEnvironment(self.srcdir, self.doctreedir, self.config) - self.env.find_files(self.config) - else: - self.env = BuildEnvironment(self.srcdir, self.doctreedir, self.config) - self.env.find_files(self.config) - self.env.set_warnfunc(self.warn) - - def build_all(self): - """Build all source files.""" - self.build(None, summary='all source files', method='all') - - def build_specific(self, filenames): - """Only rebuild as much as needed for changes in the source_filenames.""" - # bring the filenames to the canonical format, that is, - # relative to the source directory and without source_suffix. - dirlen = len(self.srcdir) + 1 - to_write = [] - suffix = self.config.source_suffix - for filename in filenames: - filename = path.abspath(filename)[dirlen:] - if filename.endswith(suffix): - filename = filename[:-len(suffix)] - filename = filename.replace(os.path.sep, SEP) - to_write.append(filename) - self.build(to_write, method='specific', - summary='%d source files given on command ' - 'line' % len(to_write)) - - def build_update(self): - """Only rebuild files changed or added since last build.""" - to_build = self.get_outdated_docs() - if isinstance(to_build, str): - self.build(['__all__'], to_build) - else: - to_build = list(to_build) - self.build(to_build, - summary='targets for %d source files that are ' - 'out of date' % len(to_build)) - - def build(self, docnames, summary=None, method='update'): - if summary: - self.info(bold('building [%s]: ' % self.name), nonl=1) - self.info(summary) - - updated_docnames = [] - # while reading, collect all warnings from docutils - warnings = [] - self.env.set_warnfunc(warnings.append) - self.info(bold('updating environment: '), nonl=1) - iterator = self.env.update(self.config, self.srcdir, self.doctreedir, self.app) - # the first item in the iterator is a summary message - self.info(iterator.next()) - for docname in self.status_iterator(iterator, 'reading sources... ', purple): - updated_docnames.append(docname) - # nothing further to do, the environment has already done the reading - for warning in warnings: - if warning.strip(): - self.warn(warning) - self.env.set_warnfunc(self.warn) - - if updated_docnames: - # save the environment - self.info(bold('pickling environment... '), nonl=True) - self.env.topickle(path.join(self.doctreedir, ENV_PICKLE_FILENAME)) - self.info('done') - - # global actions - self.info(bold('checking consistency... '), nonl=True) - self.env.check_consistency() - self.info('done') - else: - if method == 'update' and not docnames: - self.info(bold('no targets are out of date.')) - return - - # another indirection to support methods which don't build files - # individually - self.write(docnames, updated_docnames, method) - - # finish (write static files etc.) - self.finish() - if self.app._warncount: - self.info(bold('build succeeded, %s warning%s.' % - (self.app._warncount, - self.app._warncount != 1 and 's' or ''))) - else: - self.info(bold('build succeeded.')) - - def write(self, build_docnames, updated_docnames, method='update'): - if build_docnames is None or build_docnames == ['__all__']: - # build_all - build_docnames = self.env.found_docs - if method == 'update': - # build updated ones as well - docnames = set(build_docnames) | set(updated_docnames) - else: - docnames = set(build_docnames) - - # add all toctree-containing files that may have changed - for docname in list(docnames): - for tocdocname in self.env.files_to_rebuild.get(docname, []): - docnames.add(tocdocname) - docnames.add(self.config.master_doc) - - self.info(bold('preparing documents... '), nonl=True) - self.prepare_writing(docnames) - self.info('done') - - # write target files - warnings = [] - self.env.set_warnfunc(warnings.append) - for docname in self.status_iterator(sorted(docnames), - 'writing output... ', darkgreen): - doctree = self.env.get_and_resolve_doctree(docname, self) - self.write_doc(docname, doctree) - for warning in warnings: - if warning.strip(): - self.warn(warning) - self.env.set_warnfunc(self.warn) - - def prepare_writing(self, docnames): - raise NotImplementedError - - def write_doc(self, docname, doctree): - raise NotImplementedError - - def finish(self): - raise NotImplementedError - - -class StandaloneHTMLBuilder(Builder): - """ - Builds standalone HTML docs. - """ - name = 'html' - copysource = True - out_suffix = '.html' - indexer_format = js_index - supported_image_types = ['image/svg+xml', 'image/png', 'image/gif', - 'image/jpeg'] - searchindex_filename = 'searchindex.js' - add_header_links = True - add_definition_links = True - - # This is a class attribute because it is mutated by Sphinx.add_javascript. - script_files = ['_static/jquery.js', '_static/doctools.js'] - - def init(self): - """Load templates.""" - self.init_templates() - self.init_translator_class() - if self.config.html_file_suffix: - self.out_suffix = self.config.html_file_suffix - - if self.config.language is not None: - jsfile = path.join(path.dirname(__file__), 'locale', self.config.language, - 'LC_MESSAGES', 'sphinx.js') - if path.isfile(jsfile): - self.script_files.append('_static/translations.js') - - def init_translator_class(self): - if self.config.html_translator_class: - self.translator_class = self.app.import_object( - self.config.html_translator_class, 'html_translator_class setting') - elif self.config.html_use_smartypants: - self.translator_class = SmartyPantsHTMLTranslator - else: - self.translator_class = HTMLTranslator - - def render_partial(self, node): - """Utility: Render a lone doctree node.""" - doc = new_document('<partial node>') - doc.append(node) - return publish_parts( - doc, - source_class=DocTreeInput, - reader=DoctreeReader(), - writer=HTMLWriter(self), - settings_overrides={'output_encoding': 'unicode'} - ) - - def prepare_writing(self, docnames): - from sphinx.search import IndexBuilder - - self.indexer = IndexBuilder(self.env) - self.load_indexer(docnames) - self.docwriter = HTMLWriter(self) - self.docsettings = OptionParser( - defaults=self.env.settings, - components=(self.docwriter,)).get_default_values() - - # format the "last updated on" string, only once is enough since it - # typically doesn't include the time of day - lufmt = self.config.html_last_updated_fmt - if lufmt is not None: - self.last_updated = time.strftime(lufmt or _('%b %d, %Y')) - else: - self.last_updated = None - - logo = self.config.html_logo and \ - path.basename(self.config.html_logo) or '' - - favicon = self.config.html_favicon and \ - path.basename(self.config.html_favicon) or '' - if favicon and os.path.splitext(favicon)[1] != '.ico': - self.warn('html_favicon is not an .ico file') - - if not isinstance(self.config.html_use_opensearch, basestring): - self.warn('html_use_opensearch config value must now be a string') - - self.relations = self.env.collect_relations() - - rellinks = [] - if self.config.html_use_index: - rellinks.append(('genindex', _('General Index'), 'I', _('index'))) - if self.config.html_use_modindex and self.env.modules: - rellinks.append(('modindex', _('Global Module Index'), 'M', _('modules'))) - - self.globalcontext = dict( - project = self.config.project, - release = self.config.release, - version = self.config.version, - last_updated = self.last_updated, - copyright = self.config.copyright, - master_doc = self.config.master_doc, - style = self.config.html_style, - use_opensearch = self.config.html_use_opensearch, - docstitle = self.config.html_title, - shorttitle = self.config.html_short_title, - show_sphinx = self.config.html_show_sphinx, - file_suffix = self.out_suffix, - script_files = self.script_files, - sphinx_version = __version__, - rellinks = rellinks, - builder = self.name, - parents = [], - logo = logo, - favicon = favicon, - ) - self.globalcontext.update(self.config.html_context) - - def get_doc_context(self, docname, body, metatags): - """Collect items for the template context of a page.""" - # find out relations - prev = next = None - parents = [] - rellinks = self.globalcontext['rellinks'][:] - related = self.relations.get(docname) - titles = self.env.titles - if related and related[2]: - try: - next = {'link': self.get_relative_uri(docname, related[2]), - 'title': self.render_partial(titles[related[2]])['title']} - rellinks.append((related[2], next['title'], 'N', _('next'))) - except KeyError: - next = None - if related and related[1]: - try: - prev = {'link': self.get_relative_uri(docname, related[1]), - 'title': self.render_partial(titles[related[1]])['title']} - rellinks.append((related[1], prev['title'], 'P', _('previous'))) - except KeyError: - # the relation is (somehow) not in the TOC tree, handle that gracefully - prev = None - while related and related[0]: - try: - parents.append( - {'link': self.get_relative_uri(docname, related[0]), - 'title': self.render_partial(titles[related[0]])['title']}) - except KeyError: - pass - related = self.relations.get(related[0]) - if parents: - parents.pop() # remove link to the master file; we have a generic - # "back to index" link already - parents.reverse() - - # title rendered as HTML - title = titles.get(docname) - title = title and self.render_partial(title)['title'] or '' - # the name for the copied source - sourcename = self.config.html_copy_source and docname + '.txt' or '' - - # metadata for the document - meta = self.env.metadata.get(docname) - - return dict( - parents = parents, - prev = prev, - next = next, - title = title, - meta = meta, - body = body, - metatags = metatags, - rellinks = rellinks, - sourcename = sourcename, - toc = self.render_partial(self.env.get_toc_for(docname))['fragment'], - # only display a TOC if there's more than one item to show - display_toc = (self.env.toc_num_entries[docname] > 1), - ) - - def write_doc(self, docname, doctree): - self.post_process_images(doctree) - destination = StringOutput(encoding='utf-8') - doctree.settings = self.docsettings - - self.imgpath = relative_uri(self.get_target_uri(docname), '_images') - self.docwriter.write(doctree, destination) - self.docwriter.assemble_parts() - body = self.docwriter.parts['fragment'] - metatags = self.docwriter.clean_meta - - ctx = self.get_doc_context(docname, body, metatags) - self.index_page(docname, doctree, ctx.get('title', '')) - self.handle_page(docname, ctx, event_arg=doctree) - - def finish(self): - self.info(bold('writing additional files...'), nonl=1) - - # the global general index - - if self.config.html_use_index: - # the total count of lines for each index letter, used to distribute - # the entries into two columns - genindex = self.env.create_index(self) - indexcounts = [] - for _, entries in genindex: - indexcounts.append(sum(1 + len(subitems) - for _, (_, subitems) in entries)) - - genindexcontext = dict( - genindexentries = genindex, - genindexcounts = indexcounts, - split_index = self.config.html_split_index, - ) - self.info(' genindex', nonl=1) - - if self.config.html_split_index: - self.handle_page('genindex', genindexcontext, 'genindex-split.html') - self.handle_page('genindex-all', genindexcontext, 'genindex.html') - for (key, entries), count in zip(genindex, indexcounts): - ctx = {'key': key, 'entries': entries, 'count': count, - 'genindexentries': genindex} - self.handle_page('genindex-' + key, ctx, 'genindex-single.html') - else: - self.handle_page('genindex', genindexcontext, 'genindex.html') - - # the global module index - - if self.config.html_use_modindex and self.env.modules: - # the sorted list of all modules, for the global module index - modules = sorted(((mn, (self.get_relative_uri('modindex', fn) + - '#module-' + mn, sy, pl, dep)) - for (mn, (fn, sy, pl, dep)) in - self.env.modules.iteritems()), - key=lambda x: x[0].lower()) - # collect all platforms - platforms = set() - # sort out collapsable modules - modindexentries = [] - letters = [] - pmn = '' - num_toplevels = 0 - num_collapsables = 0 - cg = 0 # collapse group - fl = '' # first letter - for mn, (fn, sy, pl, dep) in modules: - pl = pl and pl.split(', ') or [] - platforms.update(pl) - if fl != mn[0].lower() and mn[0] != '_': - # heading - modindexentries.append(['', False, 0, False, - mn[0].upper(), '', [], False]) - letters.append(mn[0].upper()) - tn = mn.split('.')[0] - if tn != mn: - # submodule - if pmn == tn: - # first submodule - make parent collapsable - modindexentries[-1][1] = True - num_collapsables += 1 - elif not pmn.startswith(tn): - # submodule without parent in list, add dummy entry - cg += 1 - modindexentries.append([tn, True, cg, False, '', '', [], False]) - else: - num_toplevels += 1 - cg += 1 - modindexentries.append([mn, False, cg, (tn != mn), fn, sy, pl, dep]) - pmn = mn - fl = mn[0].lower() - platforms = sorted(platforms) - - # apply heuristics when to collapse modindex at page load: - # only collapse if number of toplevel modules is larger than - # number of submodules - collapse = len(modules) - num_toplevels < num_toplevels - - modindexcontext = dict( - modindexentries = modindexentries, - platforms = platforms, - letters = letters, - collapse_modindex = collapse, - ) - self.info(' modindex', nonl=1) - self.handle_page('modindex', modindexcontext, 'modindex.html') - - # the search page - if self.name != 'htmlhelp': - self.info(' search', nonl=1) - self.handle_page('search', {}, 'search.html') - - # additional pages from conf.py - for pagename, template in self.config.html_additional_pages.items(): - self.info(' '+pagename, nonl=1) - self.handle_page(pagename, {}, template) - - if self.config.html_use_opensearch and self.name != 'htmlhelp': - self.info(' opensearch', nonl=1) - fn = path.join(self.outdir, '_static', 'opensearch.xml') - self.handle_page('opensearch', {}, 'opensearch.xml', outfilename=fn) - - self.info() - - # copy image files - if self.images: - self.info(bold('copying images...'), nonl=True) - ensuredir(path.join(self.outdir, '_images')) - for src, dest in self.images.iteritems(): - self.info(' '+src, nonl=1) - shutil.copyfile(path.join(self.srcdir, src), - path.join(self.outdir, '_images', dest)) - self.info() - - # copy static files - self.info(bold('copying static files... '), nonl=True) - ensuredir(path.join(self.outdir, '_static')) - # first, create pygments style file - f = open(path.join(self.outdir, '_static', 'pygments.css'), 'w') - f.write(PygmentsBridge('html', self.config.pygments_style).get_stylesheet()) - f.close() - # then, copy translations JavaScript file - if self.config.language is not None: - jsfile = path.join(path.dirname(__file__), 'locale', self.config.language, - 'LC_MESSAGES', 'sphinx.js') - if path.isfile(jsfile): - shutil.copyfile(jsfile, path.join(self.outdir, '_static', - 'translations.js')) - # then, copy over all user-supplied static files - staticdirnames = [path.join(path.dirname(__file__), 'static')] + \ - [path.join(self.confdir, spath) - for spath in self.config.html_static_path] - for staticdirname in staticdirnames: - for filename in os.listdir(staticdirname): - if filename.startswith('.'): - continue - fullname = path.join(staticdirname, filename) - targetname = path.join(self.outdir, '_static', filename) - if path.isfile(fullname): - shutil.copyfile(fullname, targetname) - elif path.isdir(fullname): - if filename in self.config.exclude_dirnames: - continue - if path.exists(targetname): - shutil.rmtree(targetname) - shutil.copytree(fullname, targetname) - # last, copy logo file (handled differently) - if self.config.html_logo: - logobase = path.basename(self.config.html_logo) - shutil.copyfile(path.join(self.confdir, self.config.html_logo), - path.join(self.outdir, '_static', logobase)) - self.info('done') - - # dump the search index - self.handle_finish() - - def get_outdated_docs(self): - if self.templates: - template_mtime = self.templates.newest_template_mtime() - else: - template_mtime = 0 - for docname in self.env.found_docs: - if docname not in self.env.all_docs: - yield docname - continue - targetname = self.env.doc2path(docname, self.outdir, self.out_suffix) - try: - targetmtime = path.getmtime(targetname) - except Exception: - targetmtime = 0 - try: - srcmtime = max(path.getmtime(self.env.doc2path(docname)), - template_mtime) - if srcmtime > targetmtime: - yield docname - except EnvironmentError: - # source doesn't exist anymore - pass - - def load_indexer(self, docnames): - keep = set(self.env.all_docs) - set(docnames) - try: - f = open(path.join(self.outdir, self.searchindex_filename), 'rb') - try: - self.indexer.load(f, self.indexer_format) - finally: - f.close() - except (IOError, OSError, ValueError): - if keep: - self.warn("search index couldn't be loaded, but not all documents " - "will be built: the index will be incomplete.") - # delete all entries for files that will be rebuilt - self.indexer.prune(keep) - - def index_page(self, pagename, doctree, title): - # only index pages with title - if self.indexer is not None and title: - self.indexer.feed(pagename, title, doctree) - - # --------- these are overwritten by the serialization builder - - def get_target_uri(self, docname, typ=None): - return docname + self.out_suffix - - def handle_page(self, pagename, addctx, templatename='page.html', - outfilename=None, event_arg=None): - ctx = self.globalcontext.copy() - # current_page_name is backwards compatibility - ctx['pagename'] = ctx['current_page_name'] = pagename - - def pathto(otheruri, resource=False, - baseuri=self.get_target_uri(pagename)): - if not resource: - otheruri = self.get_target_uri(otheruri) - return relative_uri(baseuri, otheruri) - ctx['pathto'] = pathto - ctx['hasdoc'] = lambda name: name in self.env.all_docs - ctx['customsidebar'] = self.config.html_sidebars.get(pagename) - ctx.update(addctx) - - self.app.emit('html-page-context', pagename, templatename, ctx, event_arg) - - output = self.templates.render(templatename, ctx) - if not outfilename: - outfilename = path.join(self.outdir, os_path(pagename) + self.out_suffix) - ensuredir(path.dirname(outfilename)) # normally different from self.outdir - try: - f = codecs.open(outfilename, 'w', 'utf-8') - try: - f.write(output) - finally: - f.close() - except (IOError, OSError), err: - self.warn("Error writing file %s: %s" % (outfilename, err)) - if self.copysource and ctx.get('sourcename'): - # copy the source file for the "show source" link - source_name = path.join(self.outdir, '_sources', os_path(ctx['sourcename'])) - ensuredir(path.dirname(source_name)) - shutil.copyfile(self.env.doc2path(pagename), source_name) - - def handle_finish(self): - self.info(bold('dumping search index... '), nonl=True) - self.indexer.prune(self.env.all_docs) - f = open(path.join(self.outdir, self.searchindex_filename), 'wb') - try: - self.indexer.dump(f, self.indexer_format) - finally: - f.close() - self.info('done') - - self.info(bold('dumping object inventory... '), nonl=True) - f = open(path.join(self.outdir, INVENTORY_FILENAME), 'w') - try: - f.write('# Sphinx inventory version 1\n') - f.write('# Project: %s\n' % self.config.project.encode('utf-8')) - f.write('# Version: %s\n' % self.config.version) - for modname, info in self.env.modules.iteritems(): - f.write('%s mod %s\n' % (modname, self.get_target_uri(info[0]))) - for refname, (docname, desctype) in self.env.descrefs.iteritems(): - f.write('%s %s %s\n' % (refname, desctype, self.get_target_uri(docname))) - finally: - f.close() - self.info('done') - - -class SerializingHTMLBuilder(StandaloneHTMLBuilder): - """ - An abstract builder that serializes the HTML generated. - """ - #: the serializing implementation to use. Set this to a module that - #: implements a `dump`, `load`, `dumps` and `loads` functions - #: (pickle, simplejson etc.) - implementation = None - - #: the filename for the global context file - globalcontext_filename = None - - supported_image_types = ('image/svg+xml', 'image/png', 'image/gif', - 'image/jpeg') - - def init(self): - self.init_translator_class() - self.templates = None # no template bridge necessary - - def get_target_uri(self, docname, typ=None): - if docname == 'index': - return '' - if docname.endswith(SEP + 'index'): - return docname[:-5] # up to sep - return docname + SEP - - 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 - - if not outfilename: - outfilename = path.join(self.outdir, os_path(pagename) + self.out_suffix) - - self.app.emit('html-page-context', pagename, templatename, ctx, event_arg) - - ensuredir(path.dirname(outfilename)) - f = open(outfilename, 'wb') - try: - self.implementation.dump(ctx, f, 2) - finally: - f.close() - - # if there is a source file, copy the source file for the - # "show source" link - if ctx.get('sourcename'): - source_name = path.join(self.outdir, '_sources', - os_path(ctx['sourcename'])) - ensuredir(path.dirname(source_name)) - shutil.copyfile(self.env.doc2path(pagename), source_name) - - def handle_finish(self): - # dump the global context - outfilename = path.join(self.outdir, self.globalcontext_filename) - f = open(outfilename, 'wb') - try: - self.implementation.dump(self.globalcontext, f, 2) - finally: - f.close() - - # super here to dump the search index - StandaloneHTMLBuilder.handle_finish(self) - - # copy the environment file from the doctree dir to the output dir - # as needed by the web app - shutil.copyfile(path.join(self.doctreedir, ENV_PICKLE_FILENAME), - path.join(self.outdir, ENV_PICKLE_FILENAME)) - - # touch 'last build' file, used by the web application to determine - # when to reload its environment and clear the cache - open(path.join(self.outdir, LAST_BUILD_FILENAME), 'w').close() - - -class PickleHTMLBuilder(SerializingHTMLBuilder): - """ - A Builder that dumps the generated HTML into pickle files. - """ - implementation = pickle - indexer_format = pickle - name = 'pickle' - out_suffix = '.fpickle' - globalcontext_filename = 'globalcontext.pickle' - searchindex_filename = 'searchindex.pickle' - - -class JSONHTMLBuilder(SerializingHTMLBuilder): - """ - A builder that dumps the generated HTML into JSON files. - """ - implementation = json - indexer_format = json - name = 'json' - out_suffix = '.fjson' - globalcontext_filename = 'globalcontext.json' - searchindex_filename = 'searchindex.json' - - def init(self): - if json is None: - from sphinx.application import SphinxError - raise SphinxError('The module simplejson (or json in Python >= 2.6) ' - 'is not available. The JSONHTMLBuilder builder ' - 'will not work.') - SerializingHTMLBuilder.init(self) - - -class HTMLHelpBuilder(StandaloneHTMLBuilder): - """ - Builder that also outputs Windows HTML help project, contents and index files. - Adapted from the original Doc/tools/prechm.py. - """ - name = 'htmlhelp' - - # don't copy the reST source - copysource = False - supported_image_types = ['image/png', 'image/gif', 'image/jpeg'] - - # don't add links - add_header_links = False - add_definition_links = False - - def init(self): - StandaloneHTMLBuilder.init(self) - # the output files for HTML help must be .html only - self.out_suffix = '.html' - - def handle_finish(self): - build_hhx(self, self.outdir, self.config.htmlhelp_basename) - - -class LaTeXBuilder(Builder): - """ - Builds LaTeX output to create PDF. - """ - name = 'latex' - supported_image_types = ['application/pdf', 'image/png', 'image/gif', - 'image/jpeg'] - - def init(self): - self.docnames = [] - self.document_data = [] - texescape.init() - - def get_outdated_docs(self): - return 'all documents' # for now - - def get_target_uri(self, docname, typ=None): - if typ == 'token': - # token references are always inside production lists and must be - # replaced by \token{} in LaTeX - return '@token' - if docname not in self.docnames: - raise NoUri - else: - return '' - - def init_document_data(self): - preliminary_document_data = map(list, self.config.latex_documents) - if not preliminary_document_data: - self.warn('No "latex_documents" config value found; no documents ' - 'will be written.') - return - # assign subdirs to titles - self.titles = [] - for entry in preliminary_document_data: - docname = entry[0] - if docname not in self.env.all_docs: - self.warn('"latex_documents" config value references unknown ' - 'document %s' % docname) - continue - self.document_data.append(entry) - if docname.endswith(SEP+'index'): - docname = docname[:-5] - self.titles.append((docname, entry[2])) - - def write(self, *ignored): - # first, assemble the "appendix" docs that are in every PDF - appendices = [] - for fname in self.config.latex_appendices: - appendices.append(self.env.get_doctree(fname)) - - docwriter = LaTeXWriter(self) - docsettings = OptionParser( - defaults=self.env.settings, - components=(docwriter,)).get_default_values() - - self.init_document_data() - - for entry in self.document_data: - docname, targetname, title, author, docclass = entry[:5] - toctree_only = False - if len(entry) > 5: - toctree_only = entry[5] - destination = FileOutput( - destination_path=path.join(self.outdir, targetname), - encoding='utf-8') - self.info("processing " + targetname + "... ", nonl=1) - doctree = self.assemble_doctree(docname, toctree_only, - appendices=(docclass == 'manual') and appendices or []) - self.post_process_images(doctree) - self.info("writing... ", nonl=1) - doctree.settings = docsettings - doctree.settings.author = author - doctree.settings.title = title - doctree.settings.docname = docname - doctree.settings.docclass = docclass - docwriter.write(doctree, destination) - self.info("done") - - def assemble_doctree(self, indexfile, toctree_only, appendices): - self.docnames = set([indexfile] + appendices) - self.info(darkgreen(indexfile) + " ", nonl=1) - def process_tree(docname, tree): - tree = tree.deepcopy() - for toctreenode in tree.traverse(addnodes.toctree): - newnodes = [] - includefiles = map(str, toctreenode['includefiles']) - for includefile in includefiles: - try: - self.info(darkgreen(includefile) + " ", nonl=1) - subtree = process_tree(includefile, - self.env.get_doctree(includefile)) - self.docnames.add(includefile) - except Exception: - self.warn('%s: toctree contains ref to nonexisting file %r' % - (docname, includefile)) - else: - sof = addnodes.start_of_file() - sof.children = subtree.children - newnodes.append(sof) - toctreenode.parent.replace(toctreenode, newnodes) - return tree - tree = self.env.get_doctree(indexfile) - if toctree_only: - # extract toctree nodes from the tree and put them in a fresh document - new_tree = new_document('<latex output>') - new_sect = nodes.section() - new_sect += nodes.title('<temp>', '<temp>') - new_tree += new_sect - for node in tree.traverse(addnodes.toctree): - new_sect += node - tree = new_tree - largetree = process_tree(indexfile, tree) - largetree.extend(appendices) - self.info() - self.info("resolving references...") - self.env.resolve_references(largetree, indexfile, self) - # resolve :ref:s to distant tex files -- we can't add a cross-reference, - # but append the document name - for pendingnode in largetree.traverse(addnodes.pending_xref): - docname = pendingnode['refdocname'] - sectname = pendingnode['refsectname'] - newnodes = [nodes.emphasis(sectname, sectname)] - for subdir, title in self.titles: - if docname.startswith(subdir): - newnodes.append(nodes.Text(_(' (in '), _(' (in '))) - newnodes.append(nodes.emphasis(title, title)) - newnodes.append(nodes.Text(')', ')')) - break - else: - pass - pendingnode.replace_self(newnodes) - return largetree - - def finish(self): - # copy image files - if self.images: - self.info(bold('copying images...'), nonl=1) - for src, dest in self.images.iteritems(): - self.info(' '+src, nonl=1) - shutil.copyfile(path.join(self.srcdir, src), - path.join(self.outdir, dest)) - self.info() - - # the logo is handled differently - if self.config.latex_logo: - logobase = path.basename(self.config.latex_logo) - shutil.copyfile(path.join(self.confdir, self.config.latex_logo), - path.join(self.outdir, logobase)) - - self.info(bold('copying TeX support files... '), nonl=True) - staticdirname = path.join(path.dirname(__file__), 'texinputs') - for filename in os.listdir(staticdirname): - if not filename.startswith('.'): - shutil.copyfile(path.join(staticdirname, filename), - path.join(self.outdir, filename)) - self.info('done') - - -class ChangesBuilder(Builder): - """ - Write a summary with all versionadded/changed directives. - """ - name = 'changes' - - def init(self): - self.init_templates() - - def get_outdated_docs(self): - return self.outdir - - typemap = { - 'versionadded': 'added', - 'versionchanged': 'changed', - 'deprecated': 'deprecated', - } - - def write(self, *ignored): - version = self.config.version - libchanges = {} - apichanges = [] - otherchanges = {} - if version not in self.env.versionchanges: - self.info(bold('no changes in this version.')) - return - self.info(bold('writing summary file...')) - for type, docname, lineno, module, descname, content in \ - self.env.versionchanges[version]: - ttext = self.typemap[type] - context = content.replace('\n', ' ') - if descname and docname.startswith('c-api'): - if not descname: - continue - if context: - entry = '<b>%s</b>: <i>%s:</i> %s' % (descname, ttext, context) - else: - entry = '<b>%s</b>: <i>%s</i>.' % (descname, ttext) - apichanges.append((entry, docname, lineno)) - elif descname or module: - if not module: - module = _('Builtins') - if not descname: - descname = _('Module level') - if context: - entry = '<b>%s</b>: <i>%s:</i> %s' % (descname, ttext, context) - else: - entry = '<b>%s</b>: <i>%s</i>.' % (descname, ttext) - libchanges.setdefault(module, []).append((entry, docname, lineno)) - else: - if not context: - continue - entry = '<i>%s:</i> %s' % (ttext.capitalize(), context) - title = self.env.titles[docname].astext() - otherchanges.setdefault((docname, title), []).append( - (entry, docname, lineno)) - - ctx = { - 'project': self.config.project, - 'version': version, - 'docstitle': self.config.html_title, - 'shorttitle': self.config.html_short_title, - 'libchanges': sorted(libchanges.iteritems()), - 'apichanges': sorted(apichanges), - 'otherchanges': sorted(otherchanges.iteritems()), - 'show_sphinx': self.config.html_show_sphinx, - } - f = open(path.join(self.outdir, 'index.html'), 'w') - try: - f.write(self.templates.render('changes/frameset.html', ctx)) - finally: - f.close() - f = open(path.join(self.outdir, 'changes.html'), 'w') - try: - f.write(self.templates.render('changes/versionchanges.html', ctx)) - finally: - f.close() - - hltext = ['.. versionadded:: %s' % version, - '.. versionchanged:: %s' % version, - '.. deprecated:: %s' % version] - - def hl(no, line): - line = '<a name="L%s"> </a>' % no + escape(line) - for x in hltext: - if x in line: - line = '<span class="hl">%s</span>' % line - break - return line - - self.info(bold('copying source files...')) - for docname in self.env.all_docs: - f = open(self.env.doc2path(docname)) - lines = f.readlines() - targetfn = path.join(self.outdir, 'rst', os_path(docname)) + '.html' - ensuredir(path.dirname(targetfn)) - f = codecs.open(targetfn, 'w', 'utf8') - try: - text = ''.join(hl(i+1, line) for (i, line) in enumerate(lines)) - ctx = {'filename': self.env.doc2path(docname, None), 'text': text} - f.write(self.templates.render('changes/rstsource.html', ctx)) - finally: - f.close() - shutil.copyfile(path.join(path.dirname(__file__), 'static', 'default.css'), - path.join(self.outdir, 'default.css')) - - def hl(self, text, version): - text = escape(text) - for directive in ['versionchanged', 'versionadded', 'deprecated']: - text = text.replace('.. %s:: %s' % (directive, version), - '<b>.. %s:: %s</b>' % (directive, version)) - return text - - def finish(self): - pass - - -class TextBuilder(Builder): - name = 'text' - out_suffix = '.txt' - - def init(self): - pass - - def get_outdated_docs(self): - for docname in self.env.found_docs: - if docname not in self.env.all_docs: - yield docname - continue - targetname = self.env.doc2path(docname, self.outdir, self.out_suffix) - try: - targetmtime = path.getmtime(targetname) - except Exception: - targetmtime = 0 - try: - srcmtime = path.getmtime(self.env.doc2path(docname)) - if srcmtime > targetmtime: - yield docname - except EnvironmentError: - # source doesn't exist anymore - pass - - def get_target_uri(self, docname, typ=None): - return '' - - def prepare_writing(self, docnames): - self.writer = TextWriter(self) - - def write_doc(self, docname, doctree): - destination = StringOutput(encoding='utf-8') - self.writer.write(doctree, destination) - outfilename = path.join(self.outdir, os_path(docname) + self.out_suffix) - ensuredir(path.dirname(outfilename)) # normally different from self.outdir - try: - f = codecs.open(outfilename, 'w', 'utf-8') - try: - f.write(self.writer.output) - finally: - f.close() - except (IOError, OSError), err: - self.warn("Error writing file %s: %s" % (outfilename, err)) - - def finish(self): - pass - - -# compatibility alias -WebHTMLBuilder = PickleHTMLBuilder - - -from sphinx.linkcheck import CheckExternalLinksBuilder - -builtin_builders = { - 'html': StandaloneHTMLBuilder, - 'pickle': PickleHTMLBuilder, - 'json': JSONHTMLBuilder, - 'web': PickleHTMLBuilder, - 'htmlhelp': HTMLHelpBuilder, - 'latex': LaTeXBuilder, - 'text': TextBuilder, - 'changes': ChangesBuilder, - 'linkcheck': CheckExternalLinksBuilder, -} +import warnings + +from sphinx.builders import Builder +from sphinx.builders.text import TextBuilder +from sphinx.builders.html import StandaloneHTMLBuilder, WebHTMLBuilder, \ + PickleHTMLBuilder, JSONHTMLBuilder +from sphinx.builders.latex import LaTeXBuilder +from sphinx.builders.changes import ChangesBuilder +from sphinx.builders.htmlhelp import HTMLHelpBuilder +from sphinx.builders.linkcheck import CheckExternalLinksBuilder + +warnings.warn('The sphinx.builder module is deprecated; please import ' + 'builders from the respective sphinx.builders submodules.', + DeprecationWarning, stacklevel=2) diff --git a/sphinx/builders/__init__.py b/sphinx/builders/__init__.py new file mode 100644 index 000000000..41f63de4d --- /dev/null +++ b/sphinx/builders/__init__.py @@ -0,0 +1,384 @@ +# -*- coding: utf-8 -*- +""" + sphinx.builders + ~~~~~~~~~~~~~~~ + + Builder superclass for all builders. + + :copyright: Copyright 2007-2009 by the Sphinx team, see AUTHORS. + :license: BSD, see LICENSE for details. +""" + +import os +import gettext +from os import path + +from docutils import nodes + +from sphinx import package_dir, locale +from sphinx.util import SEP, relative_uri +from sphinx.environment import BuildEnvironment +from sphinx.util.console import bold, purple, darkgreen, term_width_line + +# side effect: registers roles and directives +from sphinx import roles +from sphinx import directives + + +ENV_PICKLE_FILENAME = 'environment.pickle' + + +class Builder(object): + """ + Builds target formats from the reST sources. + """ + + # builder's name, for the -b command line options + name = '' + # builder's output format, or '' if no document output is produced + format = '' + + def __init__(self, app, env=None, freshenv=False): + self.srcdir = app.srcdir + self.confdir = app.confdir + self.outdir = app.outdir + self.doctreedir = app.doctreedir + if not path.isdir(self.doctreedir): + os.makedirs(self.doctreedir) + + self.app = app + self.warn = app.warn + self.info = app.info + self.config = app.config + + self.load_i18n() + + # images that need to be copied over (source -> dest) + self.images = {} + + # if None, this is set in load_env() + self.env = env + self.freshenv = freshenv + + self.init() + self.load_env() + + # helper methods + + def init(self): + """ + Load necessary templates and perform initialization. The default + implementation does nothing. + """ + pass + + def create_template_bridge(self): + """ + Return the template bridge configured. + """ + if self.config.template_bridge: + self.templates = self.app.import_object( + self.config.template_bridge, 'template_bridge setting')() + else: + from sphinx.jinja2glue import BuiltinTemplateLoader + self.templates = BuiltinTemplateLoader() + + def get_target_uri(self, docname, typ=None): + """ + Return the target URI for a document name (*typ* can be used to qualify + the link characteristic for individual builders). + """ + raise NotImplementedError + + def get_relative_uri(self, from_, to, typ=None): + """ + Return a relative URI between two source filenames. May raise + environment.NoUri if there's no way to return a sensible URI. + """ + return relative_uri(self.get_target_uri(from_), + self.get_target_uri(to, typ)) + + def get_outdated_docs(self): + """ + Return an iterable of output files that are outdated, or a string + describing what an update build will build. + + If the builder does not output individual files corresponding to + source files, return a string here. If it does, return an iterable + of those files that need to be written. + """ + raise NotImplementedError + + def old_status_iterator(self, iterable, summary, colorfunc=darkgreen): + l = 0 + for item in iterable: + if l == 0: + self.info(bold(summary), nonl=1) + l = 1 + self.info(colorfunc(item) + ' ', nonl=1) + yield item + if l == 1: + self.info() + + # new version with progress info + def status_iterator(self, iterable, summary, colorfunc=darkgreen, length=0): + if length == 0: + for item in self.old_status_iterator(iterable, summary, colorfunc): + yield item + return + l = 0 + summary = bold(summary) + for item in iterable: + l += 1 + self.info(term_width_line('%s[%3d%%] %s' % + (summary, 100*l/length, + colorfunc(item))), nonl=1) + yield item + if l > 0: + self.info() + + supported_image_types = [] + + def post_process_images(self, doctree): + """ + Pick the best candidate for all image URIs. + """ + for node in doctree.traverse(nodes.image): + if '?' in node['candidates']: + # don't rewrite nonlocal image URIs + continue + if '*' not in node['candidates']: + for imgtype in self.supported_image_types: + candidate = node['candidates'].get(imgtype, None) + if candidate: + break + else: + self.warn( + 'no matching candidate for image URI %r' % node['uri'], + '%s:%s' % (node.source, getattr(node, 'line', ''))) + continue + node['uri'] = candidate + else: + candidate = node['uri'] + if candidate not in self.env.images: + # non-existing URI; let it alone + continue + self.images[candidate] = self.env.images[candidate][1] + + # build methods + + def load_i18n(self): + """ + Load translated strings from the configured localedirs if + enabled in the configuration. + """ + self.translator = None + if self.config.language is not None: + self.info(bold('loading translations [%s]... ' % + self.config.language), nonl=True) + locale_dirs = [path.join(package_dir, 'locale')] + \ + [path.join(self.srcdir, x) for x in self.config.locale_dirs] + for dir_ in locale_dirs: + try: + trans = gettext.translation('sphinx', localedir=dir_, + languages=[self.config.language]) + if self.translator is None: + self.translator = trans + else: + self.translator._catalog.update(trans.catalog) + except Exception: + # Language couldn't be found in the specified path + pass + if self.translator is not None: + self.info('done') + else: + self.info('locale not available') + if self.translator is None: + self.translator = gettext.NullTranslations() + self.translator.install(unicode=True) + locale.init() # translate common labels + + def load_env(self): + """Set up the build environment.""" + if self.env: + return + if not self.freshenv: + try: + self.info(bold('loading pickled environment... '), nonl=True) + self.env = BuildEnvironment.frompickle(self.config, + path.join(self.doctreedir, ENV_PICKLE_FILENAME)) + self.info('done') + except Exception, err: + if type(err) is IOError and err.errno == 2: + self.info('not found') + else: + self.info('failed: %s' % err) + self.env = BuildEnvironment(self.srcdir, self.doctreedir, + self.config) + self.env.find_files(self.config) + else: + self.env = BuildEnvironment(self.srcdir, self.doctreedir, + self.config) + self.env.find_files(self.config) + self.env.set_warnfunc(self.warn) + + def build_all(self): + """Build all source files.""" + self.build(None, summary='all source files', method='all') + + def build_specific(self, filenames): + """Only rebuild as much as needed for changes in the *filenames*.""" + # bring the filenames to the canonical format, that is, + # relative to the source directory and without source_suffix. + dirlen = len(self.srcdir) + 1 + to_write = [] + suffix = self.config.source_suffix + for filename in filenames: + filename = path.abspath(filename)[dirlen:] + if filename.endswith(suffix): + filename = filename[:-len(suffix)] + filename = filename.replace(os.path.sep, SEP) + to_write.append(filename) + self.build(to_write, method='specific', + summary='%d source files given on command ' + 'line' % len(to_write)) + + def build_update(self): + """Only rebuild what was changed or added since last build.""" + to_build = self.get_outdated_docs() + if isinstance(to_build, str): + self.build(['__all__'], to_build) + else: + to_build = list(to_build) + self.build(to_build, + summary='targets for %d source files that are ' + 'out of date' % len(to_build)) + + def build(self, docnames, summary=None, method='update'): + """ + Main build method. First updates the environment, and then + calls :meth:`write`. + """ + if summary: + self.info(bold('building [%s]: ' % self.name), nonl=1) + self.info(summary) + + updated_docnames = set() + # while reading, collect all warnings from docutils + warnings = [] + self.env.set_warnfunc(lambda *args: warnings.append(args)) + self.info(bold('updating environment: '), nonl=1) + msg, length, iterator = self.env.update(self.config, self.srcdir, + self.doctreedir, self.app) + self.info(msg) + for docname in self.status_iterator(iterator, 'reading sources... ', + purple, length): + updated_docnames.add(docname) + # nothing further to do, the environment has already + # done the reading + for warning in warnings: + self.warn(*warning) + self.env.set_warnfunc(self.warn) + + doccount = len(updated_docnames) + self.info(bold('looking for now-outdated files... '), nonl=1) + for docname in self.env.check_dependents(updated_docnames): + updated_docnames.add(docname) + outdated = len(updated_docnames) - doccount + if outdated: + self.info('%d found' % outdated) + else: + self.info('none found') + + if updated_docnames: + # save the environment + self.info(bold('pickling environment... '), nonl=True) + self.env.topickle(path.join(self.doctreedir, ENV_PICKLE_FILENAME)) + self.info('done') + + # global actions + self.info(bold('checking consistency... '), nonl=True) + self.env.check_consistency() + self.info('done') + else: + if method == 'update' and not docnames: + self.info(bold('no targets are out of date.')) + return + + # another indirection to support builders that don't build + # files individually + self.write(docnames, list(updated_docnames), method) + + # finish (write static files etc.) + self.finish() + status = (self.app.statuscode == 0 and 'succeeded' + or 'finished with problems') + if self.app._warncount: + self.info(bold('build %s, %s warning%s.' % + (status, self.app._warncount, + self.app._warncount != 1 and 's' or ''))) + else: + self.info(bold('build %s.' % status)) + + def write(self, build_docnames, updated_docnames, method='update'): + if build_docnames is None or build_docnames == ['__all__']: + # build_all + build_docnames = self.env.found_docs + if method == 'update': + # build updated ones as well + docnames = set(build_docnames) | set(updated_docnames) + else: + docnames = set(build_docnames) + + # add all toctree-containing files that may have changed + for docname in list(docnames): + for tocdocname in self.env.files_to_rebuild.get(docname, []): + docnames.add(tocdocname) + docnames.add(self.config.master_doc) + + self.info(bold('preparing documents... '), nonl=True) + self.prepare_writing(docnames) + self.info('done') + + # write target files + warnings = [] + self.env.set_warnfunc(lambda *args: warnings.append(args)) + for docname in self.status_iterator( + sorted(docnames), 'writing output... ', darkgreen, len(docnames)): + doctree = self.env.get_and_resolve_doctree(docname, self) + self.write_doc(docname, doctree) + for warning in warnings: + self.warn(*warning) + self.env.set_warnfunc(self.warn) + + def prepare_writing(self, docnames): + raise NotImplementedError + + def write_doc(self, docname, doctree): + raise NotImplementedError + + def finish(self): + """ + Finish the building process. The default implementation does nothing. + """ + pass + + def cleanup(self): + """ + Cleanup any resources. The default implementation does nothing. + """ + + +BUILTIN_BUILDERS = { + 'html': ('html', 'StandaloneHTMLBuilder'), + 'dirhtml': ('html', 'DirectoryHTMLBuilder'), + 'pickle': ('html', 'PickleHTMLBuilder'), + 'json': ('html', 'JSONHTMLBuilder'), + 'web': ('html', 'PickleHTMLBuilder'), + 'htmlhelp': ('htmlhelp', 'HTMLHelpBuilder'), + 'qthelp': ('qthelp', 'QtHelpBuilder'), + 'latex': ('latex', 'LaTeXBuilder'), + 'text': ('text', 'TextBuilder'), + 'changes': ('changes', 'ChangesBuilder'), + 'linkcheck': ('linkcheck', 'CheckExternalLinksBuilder'), +} diff --git a/sphinx/builders/changes.py b/sphinx/builders/changes.py new file mode 100644 index 000000000..e07b06d88 --- /dev/null +++ b/sphinx/builders/changes.py @@ -0,0 +1,156 @@ +# -*- coding: utf-8 -*- +""" + sphinx.builders.changes + ~~~~~~~~~~~~~~~~~~~~~~~ + + Changelog builder. + + :copyright: Copyright 2007-2009 by the Sphinx team, see AUTHORS. + :license: BSD, see LICENSE for details. +""" + +import codecs +import shutil +from os import path +from cgi import escape + +from sphinx import package_dir +from sphinx.util import ensuredir, os_path, copy_static_entry +from sphinx.theming import Theme +from sphinx.builders import Builder +from sphinx.util.console import bold + + +class ChangesBuilder(Builder): + """ + Write a summary with all versionadded/changed directives. + """ + name = 'changes' + + def init(self): + self.create_template_bridge() + Theme.init_themes(self) + self.theme = Theme('default') + self.templates.init(self, self.theme) + + def get_outdated_docs(self): + return self.outdir + + typemap = { + 'versionadded': 'added', + 'versionchanged': 'changed', + 'deprecated': 'deprecated', + } + + def write(self, *ignored): + version = self.config.version + libchanges = {} + apichanges = [] + otherchanges = {} + if version not in self.env.versionchanges: + self.info(bold('no changes in version %s.' % version)) + return + self.info(bold('writing summary file...')) + for type, docname, lineno, module, descname, content in \ + self.env.versionchanges[version]: + if isinstance(descname, tuple): + descname = descname[0] + ttext = self.typemap[type] + context = content.replace('\n', ' ') + if descname and docname.startswith('c-api'): + if not descname: + continue + if context: + entry = '<b>%s</b>: <i>%s:</i> %s' % (descname, ttext, + context) + else: + entry = '<b>%s</b>: <i>%s</i>.' % (descname, ttext) + apichanges.append((entry, docname, lineno)) + elif descname or module: + if not module: + module = _('Builtins') + if not descname: + descname = _('Module level') + if context: + entry = '<b>%s</b>: <i>%s:</i> %s' % (descname, ttext, + context) + else: + entry = '<b>%s</b>: <i>%s</i>.' % (descname, ttext) + libchanges.setdefault(module, []).append((entry, docname, + lineno)) + else: + if not context: + continue + entry = '<i>%s:</i> %s' % (ttext.capitalize(), context) + title = self.env.titles[docname].astext() + otherchanges.setdefault((docname, title), []).append( + (entry, docname, lineno)) + + ctx = { + 'project': self.config.project, + 'version': version, + 'docstitle': self.config.html_title, + 'shorttitle': self.config.html_short_title, + 'libchanges': sorted(libchanges.iteritems()), + 'apichanges': sorted(apichanges), + 'otherchanges': sorted(otherchanges.iteritems()), + 'show_sphinx': self.config.html_show_sphinx, + } + f = codecs.open(path.join(self.outdir, 'index.html'), 'w', 'utf8') + try: + f.write(self.templates.render('changes/frameset.html', ctx)) + finally: + f.close() + f = codecs.open(path.join(self.outdir, 'changes.html'), 'w', 'utf8') + try: + f.write(self.templates.render('changes/versionchanges.html', ctx)) + finally: + f.close() + + hltext = ['.. versionadded:: %s' % version, + '.. versionchanged:: %s' % version, + '.. deprecated:: %s' % version] + + def hl(no, line): + line = '<a name="L%s"> </a>' % no + escape(line) + for x in hltext: + if x in line: + line = '<span class="hl">%s</span>' % line + break + return line + + self.info(bold('copying source files...')) + for docname in self.env.all_docs: + f = codecs.open(self.env.doc2path(docname), 'r', 'latin1') + lines = f.readlines() + targetfn = path.join(self.outdir, 'rst', os_path(docname)) + '.html' + ensuredir(path.dirname(targetfn)) + f = codecs.open(targetfn, 'w', 'latin1') + try: + text = ''.join(hl(i+1, line) for (i, line) in enumerate(lines)) + ctx = { + 'filename': self.env.doc2path(docname, None), + 'text': text + } + f.write(self.templates.render('changes/rstsource.html', ctx)) + finally: + f.close() + themectx = dict(('theme_' + key, val) for (key, val) in + 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) + copy_static_entry(path.join(package_dir, 'themes', 'basic', + 'static', 'basic.css'), + path.join(self.outdir, 'basic.css'), self) + + def hl(self, text, version): + text = escape(text) + for directive in ['versionchanged', 'versionadded', 'deprecated']: + text = text.replace('.. %s:: %s' % (directive, version), + '<b>.. %s:: %s</b>' % (directive, version)) + return text + + def finish(self): + pass diff --git a/sphinx/builders/html.py b/sphinx/builders/html.py new file mode 100644 index 000000000..365cf5f96 --- /dev/null +++ b/sphinx/builders/html.py @@ -0,0 +1,836 @@ +# -*- coding: utf-8 -*- +""" + sphinx.builders.html + ~~~~~~~~~~~~~~~~~~~~ + + Several HTML builders. + + :copyright: Copyright 2007-2009 by the Sphinx team, see AUTHORS. + :license: BSD, see LICENSE for details. +""" + +import os +import codecs +import shutil +import posixpath +import cPickle as pickle +from os import path +try: + from hashlib import md5 +except ImportError: + # 2.4 compatibility + from md5 import md5 + +from docutils import nodes +from docutils.io import DocTreeInput, StringOutput +from docutils.core import publish_parts +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 +from sphinx.errors import SphinxError +from sphinx.search import js_index +from sphinx.theming import Theme +from sphinx.builders import Builder, ENV_PICKLE_FILENAME +from sphinx.highlighting import PygmentsBridge +from sphinx.util.console import bold +from sphinx.writers.html import HTMLWriter, HTMLTranslator, \ + SmartyPantsHTMLTranslator + +try: + import json +except ImportError: + try: + import simplejson as json + except ImportError: + json = None + +#: the filename for the inventory of objects +INVENTORY_FILENAME = 'objects.inv' +#: the filename for the "last build" file (for serializing builders) +LAST_BUILD_FILENAME = 'last_build' + + +class StandaloneHTMLBuilder(Builder): + """ + Builds standalone HTML docs. + """ + name = 'html' + format = 'html' + copysource = True + out_suffix = '.html' + link_suffix = '.html' # defaults to matching out_suffix + indexer_format = js_index + supported_image_types = ['image/svg+xml', 'image/png', + 'image/gif', 'image/jpeg'] + searchindex_filename = 'searchindex.js' + add_permalinks = True + embedded = False # for things like HTML help or Qt help: suppresses sidebar + + # This is a class attribute because it is mutated by Sphinx.add_javascript. + script_files = ['_static/jquery.js', '_static/doctools.js'] + + def init(self): + # a hash of all config values that, if changed, cause a full rebuild + self.config_hash = '' + self.tags_hash = '' + # section numbers for headings in the currently visited document + self.secnumbers = {} + + self.init_templates() + self.init_highlighter() + self.init_translator_class() + if self.config.html_file_suffix: + self.out_suffix = self.config.html_file_suffix + + if self.config.html_link_suffix is not None: + self.link_suffix = self.config.html_link_suffix + else: + self.link_suffix = self.out_suffix + + if self.config.language is not None: + jsfile = path.join(package_dir, 'locale', self.config.language, + 'LC_MESSAGES', 'sphinx.js') + if path.isfile(jsfile): + self.script_files.append('_static/translations.js') + + def init_templates(self): + Theme.init_themes(self) + self.theme = Theme(self.config.html_theme) + self.create_template_bridge() + self.templates.init(self, self.theme) + + def init_highlighter(self): + # determine Pygments style and create the highlighter + if self.config.pygments_style is not None: + style = self.config.pygments_style + elif self.theme: + style = self.theme.get_confstr('theme', 'pygments_style', 'none') + else: + style = 'sphinx' + self.highlighter = PygmentsBridge('html', style) + + def init_translator_class(self): + if self.config.html_translator_class: + self.translator_class = self.app.import_object( + self.config.html_translator_class, + 'html_translator_class setting') + elif self.config.html_use_smartypants: + self.translator_class = SmartyPantsHTMLTranslator + else: + self.translator_class = HTMLTranslator + + def get_outdated_docs(self): + cfgdict = dict((name, self.config[name]) + for (name, desc) in self.config.values.iteritems() + if desc[1] == 'html') + self.config_hash = md5(str(cfgdict)).hexdigest() + self.tags_hash = md5(str(sorted(self.tags))).hexdigest() + old_config_hash = old_tags_hash = '' + try: + fp = open(path.join(self.outdir, '.buildinfo')) + version = fp.readline() + if version.rstrip() != '# Sphinx build info version 1': + raise ValueError + fp.readline() # skip commentary + cfg, old_config_hash = fp.readline().strip().split(': ') + if cfg != 'config': + raise ValueError + tag, old_tags_hash = fp.readline().strip().split(': ') + if tag != 'tags': + raise ValueError + fp.close() + except ValueError: + self.warn('unsupported build info format in %r, building all' % + path.join(self.outdir, '.buildinfo')) + except Exception: + pass + if old_config_hash != self.config_hash or \ + old_tags_hash != self.tags_hash: + for docname in self.env.found_docs: + yield docname + return + + if self.templates: + template_mtime = self.templates.newest_template_mtime() + else: + template_mtime = 0 + for docname in self.env.found_docs: + if docname not in self.env.all_docs: + yield docname + continue + targetname = self.env.doc2path(docname, self.outdir, + self.out_suffix) + try: + targetmtime = path.getmtime(targetname) + except Exception: + targetmtime = 0 + try: + srcmtime = max(path.getmtime(self.env.doc2path(docname)), + template_mtime) + if srcmtime > targetmtime: + yield docname + except EnvironmentError: + # source doesn't exist anymore + pass + + def render_partial(self, node): + """Utility: Render a lone doctree node.""" + doc = new_document('<partial node>') + doc.append(node) + return publish_parts( + doc, + source_class=DocTreeInput, + reader=DoctreeReader(), + writer=HTMLWriter(self), + settings_overrides={'output_encoding': 'unicode'} + ) + + def prepare_writing(self, docnames): + from sphinx.search import IndexBuilder + + self.indexer = IndexBuilder(self.env) + self.load_indexer(docnames) + self.docwriter = HTMLWriter(self) + self.docsettings = OptionParser( + defaults=self.env.settings, + components=(self.docwriter,)).get_default_values() + + # format the "last updated on" string, only once is enough since it + # typically doesn't include the time of day + lufmt = self.config.html_last_updated_fmt + if lufmt is not None: + self.last_updated = ustrftime(lufmt or _('%b %d, %Y')) + else: + self.last_updated = None + + logo = self.config.html_logo and \ + path.basename(self.config.html_logo) or '' + + favicon = self.config.html_favicon and \ + path.basename(self.config.html_favicon) or '' + if favicon and os.path.splitext(favicon)[1] != '.ico': + self.warn('html_favicon is not an .ico file') + + if not isinstance(self.config.html_use_opensearch, basestring): + self.warn('html_use_opensearch config value must now be a string') + + self.relations = self.env.collect_relations() + + rellinks = [] + if self.config.html_use_index: + rellinks.append(('genindex', _('General Index'), 'I', _('index'))) + if self.config.html_use_modindex and self.env.modules: + rellinks.append(('modindex', _('Global Module Index'), + 'M', _('modules'))) + + if self.config.html_style is not None: + stylename = self.config.html_style + elif self.theme: + stylename = self.theme.get_confstr('theme', 'stylesheet') + else: + stylename = 'default.css' + + self.globalcontext = dict( + embedded = self.embedded, + project = self.config.project, + release = self.config.release, + version = self.config.version, + last_updated = self.last_updated, + copyright = self.config.copyright, + master_doc = self.config.master_doc, + use_opensearch = self.config.html_use_opensearch, + docstitle = self.config.html_title, + shorttitle = self.config.html_short_title, + show_sphinx = self.config.html_show_sphinx, + has_source = self.config.html_copy_source, + show_source = self.config.html_show_sourcelink, + file_suffix = self.out_suffix, + script_files = self.script_files, + sphinx_version = __version__, + style = stylename, + rellinks = rellinks, + builder = self.name, + parents = [], + logo = logo, + favicon = favicon, + ) + if self.theme: + self.globalcontext.update( + ('theme_' + key, val) for (key, val) in + self.theme.get_options( + self.config.html_theme_options).iteritems()) + self.globalcontext.update(self.config.html_context) + + def get_doc_context(self, docname, body, metatags): + """Collect items for the template context of a page.""" + # find out relations + prev = next = None + parents = [] + rellinks = self.globalcontext['rellinks'][:] + related = self.relations.get(docname) + titles = self.env.titles + if related and related[2]: + try: + next = { + 'link': self.get_relative_uri(docname, related[2]), + 'title': self.render_partial(titles[related[2]])['title'] + } + rellinks.append((related[2], next['title'], 'N', _('next'))) + except KeyError: + next = None + if related and related[1]: + try: + prev = { + 'link': self.get_relative_uri(docname, related[1]), + 'title': self.render_partial(titles[related[1]])['title'] + } + rellinks.append((related[1], prev['title'], 'P', _('previous'))) + except KeyError: + # the relation is (somehow) not in the TOC tree, handle + # that gracefully + prev = None + while related and related[0]: + try: + parents.append( + {'link': self.get_relative_uri(docname, related[0]), + 'title': self.render_partial(titles[related[0]])['title']}) + except KeyError: + pass + related = self.relations.get(related[0]) + if parents: + parents.pop() # remove link to the master file; we have a generic + # "back to index" link already + parents.reverse() + + # title rendered as HTML + title = titles.get(docname) + title = title and self.render_partial(title)['title'] or '' + # the name for the copied source + sourcename = self.config.html_copy_source and docname + '.txt' or '' + + # metadata for the document + meta = self.env.metadata.get(docname) + + # local TOC and global TOC tree + toc = self.render_partial(self.env.get_toc_for(docname))['fragment'] + + return dict( + parents = parents, + prev = prev, + next = next, + title = title, + meta = meta, + body = body, + metatags = metatags, + rellinks = rellinks, + sourcename = sourcename, + toc = toc, + # only display a TOC if there's more than one item to show + display_toc = (self.env.toc_num_entries[docname] > 1), + ) + + def write_doc(self, docname, doctree): + destination = StringOutput(encoding='utf-8') + doctree.settings = self.docsettings + + self.secnumbers = self.env.toc_secnumbers.get(docname, {}) + self.imgpath = relative_uri(self.get_target_uri(docname), '_images') + self.post_process_images(doctree) + self.dlpath = relative_uri(self.get_target_uri(docname), '_downloads') + self.docwriter.write(doctree, destination) + self.docwriter.assemble_parts() + body = self.docwriter.parts['fragment'] + metatags = self.docwriter.clean_meta + + ctx = self.get_doc_context(docname, body, metatags) + self.index_page(docname, doctree, ctx.get('title', '')) + self.handle_page(docname, ctx, event_arg=doctree) + + def finish(self): + self.info(bold('writing additional files...'), nonl=1) + + # the global general index + + if self.config.html_use_index: + # the total count of lines for each index letter, used to distribute + # the entries into two columns + genindex = self.env.create_index(self) + indexcounts = [] + for _, entries in genindex: + indexcounts.append(sum(1 + len(subitems) + for _, (_, subitems) in entries)) + + genindexcontext = dict( + genindexentries = genindex, + genindexcounts = indexcounts, + split_index = self.config.html_split_index, + ) + self.info(' genindex', nonl=1) + + if self.config.html_split_index: + self.handle_page('genindex', genindexcontext, + 'genindex-split.html') + self.handle_page('genindex-all', genindexcontext, + 'genindex.html') + for (key, entries), count in zip(genindex, indexcounts): + ctx = {'key': key, 'entries': entries, 'count': count, + 'genindexentries': genindex} + self.handle_page('genindex-' + key, ctx, + 'genindex-single.html') + else: + self.handle_page('genindex', genindexcontext, 'genindex.html') + + # the global module index + + if self.config.html_use_modindex and self.env.modules: + # the sorted list of all modules, for the global module index + modules = sorted(((mn, (self.get_relative_uri('modindex', fn) + + '#module-' + mn, sy, pl, dep)) + for (mn, (fn, sy, pl, dep)) in + self.env.modules.iteritems()), + key=lambda x: x[0].lower()) + # collect all platforms + platforms = set() + # sort out collapsable modules + modindexentries = [] + letters = [] + pmn = '' + num_toplevels = 0 + num_collapsables = 0 + cg = 0 # collapse group + fl = '' # first letter + for mn, (fn, sy, pl, dep) in modules: + pl = pl and pl.split(', ') or [] + platforms.update(pl) + + ignore = self.env.config['modindex_common_prefix'] + ignore = sorted(ignore, key=len, reverse=True) + for i in ignore: + if mn.startswith(i): + mn = mn[len(i):] + stripped = i + break + else: + stripped = '' + + if fl != mn[0].lower() and mn[0] != '_': + # heading + letter = mn[0].upper() + if letter not in letters: + modindexentries.append(['', False, 0, False, + letter, '', [], False, '']) + letters.append(letter) + tn = mn.split('.')[0] + if tn != mn: + # submodule + if pmn == tn: + # first submodule - make parent collapsable + modindexentries[-1][1] = True + num_collapsables += 1 + elif not pmn.startswith(tn): + # submodule without parent in list, add dummy entry + cg += 1 + modindexentries.append([tn, True, cg, False, '', '', + [], False, stripped]) + else: + num_toplevels += 1 + cg += 1 + modindexentries.append([mn, False, cg, (tn != mn), fn, sy, pl, + dep, stripped]) + pmn = mn + fl = mn[0].lower() + platforms = sorted(platforms) + + # apply heuristics when to collapse modindex at page load: + # only collapse if number of toplevel modules is larger than + # number of submodules + collapse = len(modules) - num_toplevels < num_toplevels + + # As some parts of the module names may have been stripped, those + # names have changed, thus it is necessary to sort the entries. + if ignore: + def sorthelper(entry): + name = entry[0] + if name == '': + # heading + name = entry[4] + return name.lower() + + modindexentries.sort(key=sorthelper) + letters.sort() + + modindexcontext = dict( + modindexentries = modindexentries, + platforms = platforms, + letters = letters, + collapse_modindex = collapse, + ) + self.info(' modindex', nonl=1) + self.handle_page('modindex', modindexcontext, 'modindex.html') + + # the search page + if self.name != 'htmlhelp': + self.info(' search', nonl=1) + self.handle_page('search', {}, 'search.html') + + # additional pages from conf.py + for pagename, template in self.config.html_additional_pages.items(): + self.info(' '+pagename, nonl=1) + self.handle_page(pagename, {}, template) + + if self.config.html_use_opensearch and self.name != 'htmlhelp': + self.info(' opensearch', nonl=1) + fn = path.join(self.outdir, '_static', 'opensearch.xml') + self.handle_page('opensearch', {}, 'opensearch.xml', outfilename=fn) + + self.info() + + # copy image files + if self.images: + self.info(bold('copying images...'), nonl=True) + ensuredir(path.join(self.outdir, '_images')) + for src, dest in self.images.iteritems(): + self.info(' '+src, nonl=1) + shutil.copyfile(path.join(self.srcdir, src), + path.join(self.outdir, '_images', dest)) + self.info() + + # copy downloadable files + if self.env.dlfiles: + self.info(bold('copying downloadable files...'), nonl=True) + ensuredir(path.join(self.outdir, '_downloads')) + for src, (_, dest) in self.env.dlfiles.iteritems(): + self.info(' '+src, nonl=1) + shutil.copyfile(path.join(self.srcdir, src), + path.join(self.outdir, '_downloads', dest)) + self.info() + + # copy static files + self.info(bold('copying static files... '), nonl=True) + ensuredir(path.join(self.outdir, '_static')) + # first, create pygments style file + f = open(path.join(self.outdir, '_static', 'pygments.css'), 'w') + f.write(self.highlighter.get_stylesheet()) + f.close() + # then, copy translations JavaScript file + if self.config.language is not None: + jsfile = path.join(package_dir, 'locale', self.config.language, + 'LC_MESSAGES', 'sphinx.js') + if path.isfile(jsfile): + shutil.copyfile(jsfile, path.join(self.outdir, '_static', + 'translations.js')) + # then, copy over all user-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) + 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) + if self.config.html_logo: + logobase = path.basename(self.config.html_logo) + shutil.copyfile(path.join(self.confdir, self.config.html_logo), + path.join(self.outdir, '_static', logobase)) + + # write build info file + fp = open(path.join(self.outdir, '.buildinfo'), 'w') + try: + fp.write('# Sphinx build info version 1\n' + '# This file hashes the configuration used when building' + ' these files. When it is not found, a full rebuild will' + ' be done.\nconfig: %s\ntags: %s\n' % + (self.config_hash, self.tags_hash)) + finally: + fp.close() + + self.info('done') + + # dump the search index + self.handle_finish() + + def cleanup(self): + # clean up theme stuff + if self.theme: + self.theme.cleanup() + + def post_process_images(self, doctree): + """ + Pick the best candiate for an image and link down-scaled images to + their high res version. + """ + Builder.post_process_images(self, doctree) + for node in doctree.traverse(nodes.image): + if not node.has_key('scale') or \ + isinstance(node.parent, nodes.reference): + # docutils does unfortunately not preserve the + # ``target`` attribute on images, so we need to check + # the parent node here. + continue + uri = node['uri'] + reference = nodes.reference() + if uri in self.images: + reference['refuri'] = posixpath.join(self.imgpath, + self.images[uri]) + else: + reference['refuri'] = uri + node.replace_self(reference) + reference.append(node) + + def load_indexer(self, docnames): + keep = set(self.env.all_docs) - set(docnames) + try: + f = open(path.join(self.outdir, self.searchindex_filename), 'rb') + try: + self.indexer.load(f, self.indexer_format) + finally: + f.close() + except (IOError, OSError, ValueError): + if keep: + self.warn('search index couldn\'t be loaded, but not all ' + 'documents will be built: the index will be ' + 'incomplete.') + # delete all entries for files that will be rebuilt + self.indexer.prune(keep) + + def index_page(self, pagename, doctree, title): + # only index pages with title + if self.indexer is not None and title: + self.indexer.feed(pagename, title, doctree) + + def _get_local_toctree(self, docname, collapse=True): + return self.render_partial(self.env.get_toctree_for( + docname, self, collapse))['fragment'] + + def get_outfilename(self, pagename): + return path.join(self.outdir, os_path(pagename) + self.out_suffix) + + # --------- these are overwritten by the serialization builder + + def get_target_uri(self, docname, typ=None): + return docname + self.link_suffix + + def handle_page(self, pagename, addctx, templatename='page.html', + outfilename=None, event_arg=None): + ctx = self.globalcontext.copy() + # current_page_name is backwards compatibility + ctx['pagename'] = ctx['current_page_name'] = pagename + + def pathto(otheruri, resource=False, + baseuri=self.get_target_uri(pagename)): + if not resource: + otheruri = self.get_target_uri(otheruri) + return relative_uri(baseuri, otheruri) + ctx['pathto'] = pathto + ctx['hasdoc'] = lambda name: name in self.env.all_docs + ctx['customsidebar'] = self.config.html_sidebars.get(pagename) + ctx['toctree'] = lambda **kw: self._get_local_toctree(pagename, **kw) + ctx.update(addctx) + + self.app.emit('html-page-context', pagename, templatename, + ctx, event_arg) + + output = self.templates.render(templatename, ctx) + if not outfilename: + outfilename = self.get_outfilename(pagename) + # outfilename's path is in general different from self.outdir + ensuredir(path.dirname(outfilename)) + try: + f = codecs.open(outfilename, 'w', 'utf-8') + try: + f.write(output) + finally: + f.close() + except (IOError, OSError), err: + self.warn("error writing file %s: %s" % (outfilename, err)) + if self.copysource and ctx.get('sourcename'): + # copy the source file for the "show source" link + source_name = path.join(self.outdir, '_sources', + os_path(ctx['sourcename'])) + ensuredir(path.dirname(source_name)) + shutil.copyfile(self.env.doc2path(pagename), source_name) + + def handle_finish(self): + self.info(bold('dumping search index... '), nonl=True) + self.indexer.prune(self.env.all_docs) + searchindexfn = path.join(self.outdir, self.searchindex_filename) + # first write to a temporary file, so that if dumping fails, + # the existing index won't be overwritten + f = open(searchindexfn + '.tmp', 'wb') + try: + self.indexer.dump(f, self.indexer_format) + finally: + f.close() + movefile(searchindexfn + '.tmp', searchindexfn) + self.info('done') + + self.info(bold('dumping object inventory... '), nonl=True) + f = open(path.join(self.outdir, INVENTORY_FILENAME), 'w') + try: + f.write('# Sphinx inventory version 1\n') + f.write('# Project: %s\n' % self.config.project.encode('utf-8')) + f.write('# Version: %s\n' % self.config.version) + for modname, info in self.env.modules.iteritems(): + f.write('%s mod %s\n' % (modname, self.get_target_uri(info[0]))) + for refname, (docname, desctype) in self.env.descrefs.iteritems(): + f.write('%s %s %s\n' % (refname, desctype, + self.get_target_uri(docname))) + finally: + f.close() + self.info('done') + + +class DirectoryHTMLBuilder(StandaloneHTMLBuilder): + """ + A StandaloneHTMLBuilder that creates all HTML pages as "index.html" in + a directory given by their pagename, so that generated URLs don't have + ``.html`` in them. + """ + name = 'dirhtml' + + def get_target_uri(self, docname, typ=None): + if docname == 'index': + return '' + if docname.endswith(SEP + 'index'): + return docname[:-5] # up to sep + return docname + SEP + + def get_outfilename(self, pagename): + if pagename == 'index' or pagename.endswith(SEP + 'index'): + outfilename = path.join(self.outdir, os_path(pagename) + + self.out_suffix) + else: + outfilename = path.join(self.outdir, os_path(pagename), + 'index' + self.out_suffix) + + return outfilename + + +class SerializingHTMLBuilder(StandaloneHTMLBuilder): + """ + An abstract builder that serializes the generated HTML. + """ + #: the serializing implementation to use. Set this to a module that + #: implements a `dump`, `load`, `dumps` and `loads` functions + #: (pickle, simplejson etc.) + implementation = None + + #: the filename for the global context file + globalcontext_filename = None + + supported_image_types = ['image/svg+xml', 'image/png', + 'image/gif', 'image/jpeg'] + + def init(self): + self.config_hash = '' + self.tags_hash = '' + self.theme = None # no theme necessary + self.templates = None # no template bridge necessary + self.init_translator_class() + self.init_highlighter() + + def get_target_uri(self, docname, typ=None): + if docname == 'index': + return '' + if docname.endswith(SEP + 'index'): + return docname[:-5] # up to sep + return docname + SEP + + 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 + + if not outfilename: + outfilename = path.join(self.outdir, + os_path(pagename) + self.out_suffix) + + self.app.emit('html-page-context', pagename, templatename, + ctx, event_arg) + + ensuredir(path.dirname(outfilename)) + f = open(outfilename, 'wb') + try: + self.implementation.dump(ctx, f, 2) + finally: + f.close() + + # if there is a source file, copy the source file for the + # "show source" link + if ctx.get('sourcename'): + source_name = path.join(self.outdir, '_sources', + os_path(ctx['sourcename'])) + ensuredir(path.dirname(source_name)) + shutil.copyfile(self.env.doc2path(pagename), source_name) + + def handle_finish(self): + # dump the global context + outfilename = path.join(self.outdir, self.globalcontext_filename) + f = open(outfilename, 'wb') + try: + self.implementation.dump(self.globalcontext, f, 2) + finally: + f.close() + + # super here to dump the search index + StandaloneHTMLBuilder.handle_finish(self) + + # copy the environment file from the doctree dir to the output dir + # as needed by the web app + shutil.copyfile(path.join(self.doctreedir, ENV_PICKLE_FILENAME), + path.join(self.outdir, ENV_PICKLE_FILENAME)) + + # touch 'last build' file, used by the web application to determine + # when to reload its environment and clear the cache + open(path.join(self.outdir, LAST_BUILD_FILENAME), 'w').close() + + +class PickleHTMLBuilder(SerializingHTMLBuilder): + """ + A Builder that dumps the generated HTML into pickle files. + """ + implementation = pickle + indexer_format = pickle + name = 'pickle' + out_suffix = '.fpickle' + globalcontext_filename = 'globalcontext.pickle' + searchindex_filename = 'searchindex.pickle' + +# compatibility alias +WebHTMLBuilder = PickleHTMLBuilder + + +class JSONHTMLBuilder(SerializingHTMLBuilder): + """ + A builder that dumps the generated HTML into JSON files. + """ + implementation = json + indexer_format = json + name = 'json' + out_suffix = '.fjson' + globalcontext_filename = 'globalcontext.json' + searchindex_filename = 'searchindex.json' + + def init(self): + if json is None: + raise SphinxError( + 'The module simplejson (or json in Python >= 2.6) ' + 'is not available. The JSONHTMLBuilder builder will not work.') + SerializingHTMLBuilder.init(self) diff --git a/sphinx/builders/htmlhelp.py b/sphinx/builders/htmlhelp.py new file mode 100644 index 000000000..8d17f91b8 --- /dev/null +++ b/sphinx/builders/htmlhelp.py @@ -0,0 +1,250 @@ +# -*- coding: utf-8 -*- +""" + sphinx.builders.htmlhelp + ~~~~~~~~~~~~~~~~~~~~~~~~ + + Build HTML help support files. + Parts adapted from Python's Doc/tools/prechm.py. + + :copyright: Copyright 2007-2009 by the Sphinx team, see AUTHORS. + :license: BSD, see LICENSE for details. +""" + +import os +import cgi +from os import path + +from docutils import nodes + +from sphinx import addnodes +from sphinx.builders.html import StandaloneHTMLBuilder + + +# Project file (*.hhp) template. 'outname' is the file basename (like +# the pythlp in pythlp.hhp); 'version' is the doc version number (like +# the 2.2 in Python 2.2). +# The magical numbers in the long line under [WINDOWS] set most of the +# user-visible features (visible buttons, tabs, etc). +# About 0x10384e: This defines the buttons in the help viewer. The +# following defns are taken from htmlhelp.h. Not all possibilities +# actually work, and not all those that work are available from the Help +# Workshop GUI. In particular, the Zoom/Font button works and is not +# available from the GUI. The ones we're using are marked with 'x': +# +# 0x000002 Hide/Show x +# 0x000004 Back x +# 0x000008 Forward x +# 0x000010 Stop +# 0x000020 Refresh +# 0x000040 Home x +# 0x000080 Forward +# 0x000100 Back +# 0x000200 Notes +# 0x000400 Contents +# 0x000800 Locate x +# 0x001000 Options x +# 0x002000 Print x +# 0x004000 Index +# 0x008000 Search +# 0x010000 History +# 0x020000 Favorites +# 0x040000 Jump 1 +# 0x080000 Jump 2 +# 0x100000 Zoom/Font x +# 0x200000 TOC Next +# 0x400000 TOC Prev + +project_template = '''\ +[OPTIONS] +Binary TOC=Yes +Binary Index=No +Compiled file=%(outname)s.chm +Contents file=%(outname)s.hhc +Default Window=%(outname)s +Default topic=index.html +Display compile progress=No +Full text search stop list file=%(outname)s.stp +Full-text search=Yes +Index file=%(outname)s.hhk +Language=0x409 +Title=%(title)s + +[WINDOWS] +%(outname)s="%(title)s","%(outname)s.hhc","%(outname)s.hhk",\ +"index.html","index.html",,,,,0x63520,220,0x10384e,[0,0,1024,768],,,,,,,0 + +[FILES] +''' + +contents_header = '''\ +<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN"> +<HTML> +<HEAD> +<meta name="GENERATOR" content="Microsoft® HTML Help Workshop 4.1"> +<!-- Sitemap 1.0 --> +</HEAD><BODY> +<OBJECT type="text/site properties"> + <param name="Window Styles" value="0x801227"> + <param name="ImageType" value="Folder"> +</OBJECT> +<UL> +''' + +contents_footer = '''\ +</UL></BODY></HTML> +''' + +object_sitemap = '''\ +<OBJECT type="text/sitemap"> + <param name="Name" value="%s"> + <param name="Local" value="%s"> +</OBJECT> +''' + +# List of words the full text search facility shouldn't index. This +# becomes file outname.stp. Note that this list must be pretty small! +# Different versions of the MS docs claim the file has a maximum size of +# 256 or 512 bytes (including \r\n at the end of each line). +# Note that "and", "or", "not" and "near" are operators in the search +# language, so no point indexing them even if we wanted to. +stopwords = """ +a and are as at +be but by +for +if in into is it +near no not +of on or +such +that the their then there these they this to +was will with +""".split() + + +class HTMLHelpBuilder(StandaloneHTMLBuilder): + """ + Builder that also outputs Windows HTML help project, contents and + index files. Adapted from the original Doc/tools/prechm.py. + """ + name = 'htmlhelp' + + # don't copy the reST source + copysource = False + supported_image_types = ['image/png', 'image/gif', 'image/jpeg'] + + # don't add links + add_permalinks = False + # don't add sidebar etc. + embedded = True + + def init(self): + StandaloneHTMLBuilder.init(self) + # the output files for HTML help must be .html only + self.out_suffix = '.html' + + def handle_finish(self): + self.build_hhx(self.outdir, self.config.htmlhelp_basename) + + def build_hhx(self, outdir, outname): + self.info('dumping stopword list...') + f = open(path.join(outdir, outname+'.stp'), 'w') + try: + for word in sorted(stopwords): + print >>f, word + finally: + f.close() + + self.info('writing project file...') + f = open(path.join(outdir, outname+'.hhp'), 'w') + try: + f.write(project_template % {'outname': outname, + 'title': self.config.html_title, + 'version': self.config.version, + 'project': self.config.project}) + if not outdir.endswith(os.sep): + outdir += os.sep + olen = len(outdir) + for root, dirs, files in os.walk(outdir): + staticdir = (root == path.join(outdir, '_static')) + for fn in files: + if (staticdir and not fn.endswith('.js')) or \ + fn.endswith('.html'): + print >>f, path.join(root, fn)[olen:].replace(os.sep, + '\\') + finally: + f.close() + + self.info('writing TOC file...') + f = open(path.join(outdir, outname+'.hhc'), 'w') + try: + f.write(contents_header) + # special books + f.write('<LI> ' + object_sitemap % (self.config.html_short_title, + 'index.html')) + if self.config.html_use_modindex: + f.write('<LI> ' + object_sitemap % (_('Global Module Index'), + 'modindex.html')) + # the TOC + tocdoc = self.env.get_and_resolve_doctree( + self.config.master_doc, self, prune_toctrees=False) + def write_toc(node, ullevel=0): + if isinstance(node, nodes.list_item): + f.write('<LI> ') + for subnode in node: + write_toc(subnode, ullevel) + elif isinstance(node, nodes.reference): + link = node['refuri'] + title = cgi.escape(node.astext()).replace('"','"') + item = object_sitemap % (title, link) + f.write(item.encode('ascii', 'xmlcharrefreplace')) + elif isinstance(node, nodes.bullet_list): + if ullevel != 0: + f.write('<UL>\n') + for subnode in node: + write_toc(subnode, ullevel+1) + if ullevel != 0: + f.write('</UL>\n') + elif isinstance(node, addnodes.compact_paragraph): + for subnode in node: + write_toc(subnode, ullevel) + def istoctree(node): + return isinstance(node, addnodes.compact_paragraph) and \ + node.has_key('toctree') + for node in tocdoc.traverse(istoctree): + write_toc(node) + f.write(contents_footer) + finally: + f.close() + + self.info('writing index file...') + index = self.env.create_index(self) + f = open(path.join(outdir, outname+'.hhk'), 'w') + try: + f.write('<UL>\n') + def write_index(title, refs, subitems): + def write_param(name, value): + item = ' <param name="%s" value="%s">\n' % (name, value) + f.write(item.encode('ascii', 'xmlcharrefreplace')) + title = cgi.escape(title) + f.write('<LI> <OBJECT type="text/sitemap">\n') + write_param('Keyword', title) + if len(refs) == 0: + write_param('See Also', title) + elif len(refs) == 1: + write_param('Local', refs[0]) + else: + for i, ref in enumerate(refs): + # XXX: better title? + write_param('Name', '[%d] %s' % (i, ref)) + write_param('Local', ref) + f.write('</OBJECT>\n') + if subitems: + f.write('<UL> ') + for subitem in subitems: + write_index(subitem[0], subitem[1], []) + f.write('</UL>') + for (key, group) in index: + for title, (refs, subitems) in group: + write_index(title, refs, subitems) + f.write('</UL>\n') + finally: + f.close() diff --git a/sphinx/builders/latex.py b/sphinx/builders/latex.py new file mode 100644 index 000000000..96d70e3e7 --- /dev/null +++ b/sphinx/builders/latex.py @@ -0,0 +1,203 @@ +# -*- coding: utf-8 -*- +""" + sphinx.builders.latex + ~~~~~~~~~~~~~~~~~~~~~ + + LaTeX builder. + + :copyright: Copyright 2007-2009 by the Sphinx team, see AUTHORS. + :license: BSD, see LICENSE for details. +""" + +import os +import shutil +from os import path + +from docutils import nodes +from docutils.io import FileOutput +from docutils.utils import new_document +from docutils.frontend import OptionParser + +from sphinx import package_dir, addnodes +from sphinx.util import SEP, texescape +from sphinx.builders import Builder +from sphinx.environment import NoUri +from sphinx.util.console import bold, darkgreen +from sphinx.writers.latex import LaTeXWriter + + +class LaTeXBuilder(Builder): + """ + Builds LaTeX output to create PDF. + """ + name = 'latex' + format = 'latex' + supported_image_types = ['application/pdf', 'image/png', + 'image/gif', 'image/jpeg'] + + def init(self): + self.docnames = [] + self.document_data = [] + texescape.init() + + def get_outdated_docs(self): + return 'all documents' # for now + + def get_target_uri(self, docname, typ=None): + if typ == 'token': + # token references are always inside production lists and must be + # replaced by \token{} in LaTeX + return '@token' + if docname not in self.docnames: + raise NoUri + else: + return '%' + docname + + def get_relative_uri(self, from_, to, typ=None): + # ignore source path + return self.get_target_uri(to, typ) + + def init_document_data(self): + preliminary_document_data = map(list, self.config.latex_documents) + if not preliminary_document_data: + self.warn('no "latex_documents" config value found; no documents ' + 'will be written') + return + # assign subdirs to titles + self.titles = [] + for entry in preliminary_document_data: + docname = entry[0] + if docname not in self.env.all_docs: + self.warn('"latex_documents" config value references unknown ' + 'document %s' % docname) + continue + self.document_data.append(entry) + if docname.endswith(SEP+'index'): + docname = docname[:-5] + self.titles.append((docname, entry[2])) + + def write(self, *ignored): + docwriter = LaTeXWriter(self) + docsettings = OptionParser( + defaults=self.env.settings, + components=(docwriter,)).get_default_values() + + self.init_document_data() + + for entry in self.document_data: + docname, targetname, title, author, docclass = entry[:5] + toctree_only = False + if len(entry) > 5: + toctree_only = entry[5] + destination = FileOutput( + destination_path=path.join(self.outdir, targetname), + encoding='utf-8') + self.info("processing " + targetname + "... ", nonl=1) + doctree = self.assemble_doctree(docname, toctree_only, + appendices=((docclass == 'manual') and + self.config.latex_appendices or [])) + self.post_process_images(doctree) + self.info("writing... ", nonl=1) + doctree.settings = docsettings + doctree.settings.author = author + doctree.settings.title = title + doctree.settings.docname = docname + doctree.settings.docclass = docclass + docwriter.write(doctree, destination) + self.info("done") + + def assemble_doctree(self, indexfile, toctree_only, appendices): + self.docnames = set([indexfile] + appendices) + self.info(darkgreen(indexfile) + " ", nonl=1) + def process_tree(docname, tree): + tree = tree.deepcopy() + for toctreenode in tree.traverse(addnodes.toctree): + newnodes = [] + includefiles = map(str, toctreenode['includefiles']) + for includefile in includefiles: + try: + self.info(darkgreen(includefile) + " ", nonl=1) + subtree = process_tree( + includefile, self.env.get_doctree(includefile)) + self.docnames.add(includefile) + except Exception: + self.warn('toctree contains ref to nonexisting ' + 'file %r' % includefile, + self.builder.env.doc2path(docname)) + else: + sof = addnodes.start_of_file(docname=includefile) + sof.children = subtree.children + newnodes.append(sof) + toctreenode.parent.replace(toctreenode, newnodes) + return tree + tree = self.env.get_doctree(indexfile) + tree['docname'] = indexfile + if toctree_only: + # extract toctree nodes from the tree and put them in a + # fresh document + new_tree = new_document('<latex output>') + new_sect = nodes.section() + new_sect += nodes.title(u'<Set title in conf.py>', + u'<Set title in conf.py>') + new_tree += new_sect + for node in tree.traverse(addnodes.toctree): + new_sect += node + tree = new_tree + largetree = process_tree(indexfile, tree) + largetree['docname'] = indexfile + for docname in appendices: + appendix = self.env.get_doctree(docname) + appendix['docname'] = docname + largetree.append(appendix) + self.info() + self.info("resolving references...") + self.env.resolve_references(largetree, indexfile, self) + # resolve :ref:s to distant tex files -- we can't add a cross-reference, + # but append the document name + for pendingnode in largetree.traverse(addnodes.pending_xref): + docname = pendingnode['refdocname'] + sectname = pendingnode['refsectname'] + newnodes = [nodes.emphasis(sectname, sectname)] + for subdir, title in self.titles: + if docname.startswith(subdir): + newnodes.append(nodes.Text(_(' (in '), _(' (in '))) + newnodes.append(nodes.emphasis(title, title)) + newnodes.append(nodes.Text(')', ')')) + break + else: + pass + pendingnode.replace_self(newnodes) + return largetree + + def finish(self): + # copy image files + if self.images: + self.info(bold('copying images...'), nonl=1) + for src, dest in self.images.iteritems(): + self.info(' '+src, nonl=1) + shutil.copyfile(path.join(self.srcdir, src), + path.join(self.outdir, dest)) + self.info() + + # copy additional files + if self.config.latex_additional_files: + self.info(bold('copying additional files...'), nonl=1) + for filename in self.config.latex_additional_files: + self.info(' '+filename, nonl=1) + shutil.copyfile(path.join(self.confdir, filename), + path.join(self.outdir, path.basename(filename))) + self.info() + + # the logo is handled differently + if self.config.latex_logo: + logobase = path.basename(self.config.latex_logo) + shutil.copyfile(path.join(self.confdir, self.config.latex_logo), + path.join(self.outdir, logobase)) + + self.info(bold('copying TeX support files... '), nonl=True) + staticdirname = path.join(package_dir, 'texinputs') + for filename in os.listdir(staticdirname): + if not filename.startswith('.'): + shutil.copyfile(path.join(staticdirname, filename), + path.join(self.outdir, filename)) + self.info('done') diff --git a/sphinx/linkcheck.py b/sphinx/builders/linkcheck.py similarity index 80% rename from sphinx/linkcheck.py rename to sphinx/builders/linkcheck.py index 457b18dcb..f3962965c 100644 --- a/sphinx/linkcheck.py +++ b/sphinx/builders/linkcheck.py @@ -1,12 +1,12 @@ # -*- coding: utf-8 -*- """ - sphinx.linkcheck - ~~~~~~~~~~~~~~~~ + sphinx.builders.linkcheck + ~~~~~~~~~~~~~~~~~~~~~~~~~ The CheckExternalLinksBuilder class. - :copyright: 2008 by Georg Brandl, Thomas Lamb. - :license: BSD. + :copyright: Copyright 2007-2009 by the Sphinx team, see AUTHORS. + :license: BSD, see LICENSE for details. """ import socket @@ -15,7 +15,7 @@ from urllib2 import build_opener, HTTPError from docutils import nodes -from sphinx.builder import Builder +from sphinx.builders import Builder from sphinx.util.console import purple, red, darkgreen # create an opener that will simulate a browser user-agent @@ -84,20 +84,28 @@ class CheckExternalLinksBuilder(Builder): self.good.add(uri) elif r == 2: self.info(' - ' + red('broken: ') + s) - self.broken[uri] = (r, s) self.write_entry('broken', docname, lineno, uri + ': ' + s) + self.broken[uri] = (r, s) + if self.app.quiet: + self.warn('broken link: %s' % uri, + '%s:%s' % (self.env.doc2path(docname), lineno)) else: self.info(' - ' + purple('redirected') + ' to ' + s) + self.write_entry('redirected', docname, + lineno, uri + ' to ' + s) self.redirected[uri] = (r, s) - self.write_entry('redirected', docname, lineno, uri + ' to ' + s) - elif len(uri) == 0 or uri[0:7] == 'mailto:' or uri[0:4] == 'ftp:': return else: - self.info(uri + ' - ' + red('malformed!')) + self.warn(uri + ' - ' + red('malformed!')) self.write_entry('malformed', docname, lineno, uri) + if self.app.quiet: + self.warn('malformed link: %s' % uri, + '%s:%s' % (self.env.doc2path(docname), lineno)) + self.app.statuscode = 1 - return + if self.broken: + self.app.statuscode = 1 def write_entry(self, what, docname, line, uri): output = open(path.join(self.outdir, 'output.txt'), 'a') diff --git a/sphinx/builders/qthelp.py b/sphinx/builders/qthelp.py new file mode 100644 index 000000000..7c2af1ef8 --- /dev/null +++ b/sphinx/builders/qthelp.py @@ -0,0 +1,263 @@ +# -*- coding: utf-8 -*- +""" + sphinx.builders.qthelp + ~~~~~~~~~~~~~~~~~~~~~~ + + Build input files for the Qt collection generator. + + :copyright: Copyright 2007-2009 by the Sphinx team, see AUTHORS. + :license: BSD, see LICENSE for details. +""" + +import os +import re +import cgi +from os import path + +from docutils import nodes + +from sphinx import addnodes +from sphinx.builders.html import StandaloneHTMLBuilder + +_idpattern = re.compile( + r'(?P<title>.+) (\((?P<id>[\w\.]+)( (?P<descr>\w+))?\))$') + + +# Qt Help Collection Project (.qhcp). +# Is the input file for the help collection generator. +# It contains references to compressed help files which should be +# included in the collection. +# It may contain various other information for customizing Qt Assistant. +collection_template = '''\ +<?xml version="1.0" encoding="utf-8" ?> +<QHelpCollectionProject version="1.0"> + <docFiles> + <generate> + <file> + <input>%(outname)s.qhp</input> + <output>%(outname)s.qch</output> + </file> + </generate> + <register> + <file>%(outname)s.qch</file> + </register> + </docFiles> +</QHelpCollectionProject> +''' + +# Qt Help Project (.qhp) +# This is the input file for the help generator. +# It contains the table of contents, indices and references to the +# actual documentation files (*.html). +# In addition it defines a unique namespace for the documentation. +project_template = '''\ +<?xml version="1.0" encoding="UTF-8"?> +<QtHelpProject version="1.0"> + <namespace>%(outname)s.org.%(outname)s.%(nversion)s</namespace> + <virtualFolder>doc</virtualFolder> + <customFilter name="%(project)s %(version)s"> + <filterAttribute>%(outname)s</filterAttribute> + <filterAttribute>%(version)s</filterAttribute> + </customFilter> + <filterSection> + <filterAttribute>%(outname)s</filterAttribute> + <filterAttribute>%(version)s</filterAttribute> + <toc> + <section title="%(title)s" ref="%(masterdoc)s.html"> +%(sections)s + </section> + </toc> + <keywords> +%(keywords)s + </keywords> + <files> +%(files)s + </files> + </filterSection> +</QtHelpProject> +''' + +section_template = '<section title="%(title)s" ref="%(ref)s"/>' +file_template = ' '*12 + '<file>%(filename)s</file>' + + +class QtHelpBuilder(StandaloneHTMLBuilder): + """ + Builder that also outputs Qt help project, contents and index files. + """ + name = 'qthelp' + + # don't copy the reST source + copysource = False + supported_image_types = ['image/svg+xml', 'image/png', 'image/gif', + 'image/jpeg'] + + # don't add links + add_permalinks = False + # don't add sidebar etc. + embedded = True + + def init(self): + StandaloneHTMLBuilder.init(self) + # the output files for HTML help must be .html only + self.out_suffix = '.html' + #self.config.html_style = 'traditional.css' + + def handle_finish(self): + self.build_qhcp(self.outdir, self.config.qthelp_basename) + self.build_qhp(self.outdir, self.config.qthelp_basename) + + def build_qhcp(self, outdir, outname): + self.info('writing collection project file...') + f = open(path.join(outdir, outname+'.qhcp'), 'w') + try: + f.write(collection_template % {'outname': outname}) + finally: + f.close() + + def build_qhp(self, outdir, outname): + self.info('writing project file...') + + # sections + tocdoc = self.env.get_and_resolve_doctree(self.config.master_doc, self, + prune_toctrees=False) + istoctree = lambda node: ( + isinstance(node, addnodes.compact_paragraph) + and node.has_key('toctree')) + sections = [] + for node in tocdoc.traverse(istoctree): + sections.extend(self.write_toc(node)) + + if self.config.html_use_modindex: + item = section_template % {'title': _('Global Module Index'), + 'ref': 'modindex.html'} + sections.append(' '*4*4 + item) + sections = '\n'.join(sections) + + # keywords + keywords = [] + index = self.env.create_index(self) + for (key, group) in index: + for title, (refs, subitems) in group: + keywords.extend(self.build_keywords(title, refs, subitems)) + keywords = '\n'.join(keywords) + + # files + if not outdir.endswith(os.sep): + outdir += os.sep + olen = len(outdir) + projectfiles = [] + for root, dirs, files in os.walk(outdir): + staticdir = (root == path.join(outdir, '_static')) + for fn in files: + if (staticdir and not fn.endswith('.js')) or \ + fn.endswith('.html'): + filename = path.join(root, fn)[olen:] + #filename = filename.replace(os.sep, '\\') # XXX + projectfiles.append(file_template % {'filename': filename}) + projectfiles = '\n'.join(projectfiles) + + # write the project file + f = open(path.join(outdir, outname+'.qhp'), 'w') + try: + nversion = self.config.version.replace('.', '_') + nversion = nversion.replace(' ', '_') + f.write(project_template % {'outname': outname, + 'title': self.config.html_title, + 'version': self.config.version, + 'project': self.config.project, + 'nversion': nversion, + 'masterdoc': self.config.master_doc, + 'sections': sections, + 'keywords': keywords, + 'files': projectfiles}) + finally: + f.close() + + def isdocnode(self, node): + if not isinstance(node, nodes.list_item): + return False + if len(node.children) != 2: + return False + if not isinstance(node.children[0], addnodes.compact_paragraph): + return False + if not isinstance(node.children[0][0], nodes.reference): + return False + if not isinstance(node.children[1], nodes.bullet_list): + return False + return True + + def write_toc(self, node, indentlevel=4): + parts = [] + if self.isdocnode(node): + refnode = node.children[0][0] + link = refnode['refuri'] + title = cgi.escape(refnode.astext()).replace('"','"') + item = '<section title="%(title)s" ref="%(ref)s">' % { + 'title': title, + 'ref': link} + parts.append(' '*4*indentlevel + item) + for subnode in node.children[1]: + parts.extend(self.write_toc(subnode, indentlevel+1)) + parts.append(' '*4*indentlevel + '</section>') + elif isinstance(node, nodes.list_item): + for subnode in node: + parts.extend(self.write_toc(subnode, indentlevel)) + elif isinstance(node, nodes.reference): + link = node['refuri'] + title = cgi.escape(node.astext()).replace('"','"') + item = section_template % {'title': title, 'ref': link} + item = ' '*4*indentlevel + item.encode('ascii', 'xmlcharrefreplace') + parts.append(item.encode('ascii', 'xmlcharrefreplace')) + elif isinstance(node, nodes.bullet_list): + for subnode in node: + parts.extend(self.write_toc(subnode, indentlevel)) + elif isinstance(node, addnodes.compact_paragraph): + for subnode in node: + parts.extend(self.write_toc(subnode, indentlevel)) + + return parts + + def keyword_item(self, name, ref): + matchobj = _idpattern.match(name) + if matchobj: + groupdict = matchobj.groupdict() + shortname = groupdict['title'] + id = groupdict.get('id') +# descr = groupdict.get('descr') + if shortname.endswith('()'): + shortname = shortname[:-2] + id = '%s.%s' % (id, shortname) + else: + id = descr = None + + if id: + item = ' '*12 + '<keyword name="%s" id="%s" ref="%s"/>' % ( + name, id, ref) + else: + item = ' '*12 + '<keyword name="%s" ref="%s"/>' % (name, ref) + item.encode('ascii', 'xmlcharrefreplace') + return item + + def build_keywords(self, title, refs, subitems): + keywords = [] + + title = cgi.escape(title) +# if len(refs) == 0: # XXX +# write_param('See Also', title) + if len(refs) == 1: + keywords.append(self.keyword_item(title, refs[0])) + elif len(refs) > 1: + for i, ref in enumerate(refs): # XXX +# item = (' '*12 + +# '<keyword name="%s [%d]" ref="%s"/>' % ( +# title, i, ref)) +# item.encode('ascii', 'xmlcharrefreplace') +# keywords.append(item) + keywords.append(self.keyword_item(title, ref)) + + if subitems: + for subitem in subitems: + keywords.extend(self.build_keywords(subitem[0], subitem[1], [])) + + return keywords diff --git a/sphinx/builders/text.py b/sphinx/builders/text.py new file mode 100644 index 000000000..8651778cb --- /dev/null +++ b/sphinx/builders/text.py @@ -0,0 +1,70 @@ +# -*- coding: utf-8 -*- +""" + sphinx.builders.text + ~~~~~~~~~~~~~~~~~~~~ + + Plain-text Sphinx builder. + + :copyright: Copyright 2007-2009 by the Sphinx team, see AUTHORS. + :license: BSD, see LICENSE for details. +""" + +import codecs +from os import path + +from docutils.io import StringOutput + +from sphinx.util import ensuredir, os_path +from sphinx.builders import Builder +from sphinx.writers.text import TextWriter + + +class TextBuilder(Builder): + name = 'text' + format = 'text' + out_suffix = '.txt' + + def init(self): + pass + + def get_outdated_docs(self): + for docname in self.env.found_docs: + if docname not in self.env.all_docs: + yield docname + continue + targetname = self.env.doc2path(docname, self.outdir, + self.out_suffix) + try: + targetmtime = path.getmtime(targetname) + except Exception: + targetmtime = 0 + try: + srcmtime = path.getmtime(self.env.doc2path(docname)) + if srcmtime > targetmtime: + yield docname + except EnvironmentError: + # source doesn't exist anymore + pass + + def get_target_uri(self, docname, typ=None): + return '' + + def prepare_writing(self, docnames): + self.writer = TextWriter(self) + + def write_doc(self, docname, doctree): + destination = StringOutput(encoding='utf-8') + self.writer.write(doctree, destination) + outfilename = path.join(self.outdir, os_path(docname) + self.out_suffix) + ensuredir(path.dirname(outfilename)) + try: + f = codecs.open(outfilename, 'w', 'utf-8') + try: + f.write(self.writer.output) + finally: + f.close() + except (IOError, OSError), err: + self.warn("error writing file %s: %s" % (outfilename, err)) + + def finish(self): + pass diff --git a/sphinx/cmdline.py b/sphinx/cmdline.py new file mode 100644 index 000000000..79bd9751c --- /dev/null +++ b/sphinx/cmdline.py @@ -0,0 +1,222 @@ +# -*- coding: utf-8 -*- +""" + sphinx.cmdline + ~~~~~~~~~~~~~~ + + sphinx-build command-line handling. + + :copyright: Copyright 2007-2009 by the Sphinx team, see AUTHORS. + :license: BSD, see LICENSE for details. +""" + +import os +import sys +import getopt +import traceback +from os import path + +from docutils.utils import SystemMessage + +from sphinx import __version__ +from sphinx.errors import SphinxError +from sphinx.application import Sphinx +from sphinx.util import Tee, format_exception_cut_frames, save_traceback +from sphinx.util.console import darkred, nocolor, color_terminal + + +def usage(argv, msg=None): + if msg: + print >>sys.stderr, msg + print >>sys.stderr + print >>sys.stderr, """\ +Sphinx v%s +Usage: %s [options] sourcedir outdir [filenames...] +Options: -b <builder> -- builder to use; default is html + -a -- write all files; default is to only write \ +new and changed files + -E -- don't use a saved environment, always read all files + -t <tag> -- include "only" blocks with <tag> + -d <path> -- path for the cached environment and doctree files + (default: outdir/.doctrees) + -c <path> -- path where configuration file (conf.py) is located + (default: same as sourcedir) + -C -- use no config file at all, only -D options + -D <setting=value> -- override a setting in configuration + -A <name=value> -- pass a value into the templates, for HTML builder + -g <path> -- auto-generate docs with sphinx.ext.autosummary + for autosummary directives in sources found in path + -N -- do not do colored output + -q -- no output on stdout, just warnings on stderr + -Q -- no output at all, not even warnings + -w <file> -- write warnings (and errors) to given file + -W -- turn warnings into errors + -P -- run Pdb on exception +Modi: +* without -a and without filenames, write new and changed files. +* with -a, write all files. +* with filenames, write these.""" % (__version__, argv[0]) + + +def main(argv): + if not sys.stdout.isatty() or not color_terminal(): + # Windows' poor cmd box doesn't understand ANSI sequences + nocolor() + + try: + opts, args = getopt.getopt(argv[1:], 'ab:t:d:c:CD:A:g:NEqQWw:P') + allopts = set(opt[0] for opt in opts) + srcdir = confdir = path.abspath(args[0]) + if not path.isdir(srcdir): + print >>sys.stderr, 'Error: Cannot find source directory.' + return 1 + if not path.isfile(path.join(srcdir, 'conf.py')) and \ + '-c' not in allopts and '-C' not in allopts: + print >>sys.stderr, ('Error: Source directory doesn\'t ' + 'contain conf.py file.') + return 1 + outdir = path.abspath(args[1]) + if not path.isdir(outdir): + print >>sys.stderr, 'Making output directory...' + os.makedirs(outdir) + except (IndexError, getopt.error): + usage(argv) + return 1 + + filenames = args[2:] + err = 0 + for filename in filenames: + if not path.isfile(filename): + print >>sys.stderr, 'Cannot find file %r.' % filename + err = 1 + if err: + return 1 + + buildername = all_files = None + freshenv = warningiserror = use_pdb = False + status = sys.stdout + warning = sys.stderr + error = sys.stderr + warnfile = None + confoverrides = {} + htmlcontext = {} + tags = [] + doctreedir = path.join(outdir, '.doctrees') + for opt, val in opts: + if opt == '-b': + buildername = val + elif opt == '-a': + if filenames: + usage(argv, 'Cannot combine -a option and filenames.') + return 1 + all_files = True + elif opt == '-t': + tags.append(val) + elif opt == '-d': + doctreedir = path.abspath(val) + elif opt == '-c': + confdir = path.abspath(val) + if not path.isfile(path.join(confdir, 'conf.py')): + print >>sys.stderr, ('Error: Configuration directory ' + 'doesn\'t contain conf.py file.') + return 1 + elif opt == '-C': + confdir = None + elif opt == '-D': + try: + key, val = val.split('=') + except ValueError: + print >>sys.stderr, ('Error: -D option argument must be ' + 'in the form name=value.') + return 1 + try: + val = int(val) + except ValueError: + pass + confoverrides[key] = val + elif opt == '-A': + try: + key, val = val.split('=') + except ValueError: + print >>sys.stderr, ('Error: -A option argument must be ' + 'in the form name=value.') + return 1 + try: + val = int(val) + except ValueError: + pass + htmlcontext[key] = val + elif opt == '-g': + # XXX XXX XXX + source_filenames = [path.join(srcdir, f) + for f in os.listdir(srcdir) if f.endswith('.rst')] + if val is None: + print >>sys.stderr, \ + 'Error: you must provide a destination directory ' \ + 'for autodoc generation.' + return 1 + p = path.abspath(val) + from sphinx.ext.autosummary.generate import generate_autosummary_docs + generate_autosummary_docs(source_filenames, p) + elif opt == '-N': + nocolor() + elif opt == '-E': + freshenv = True + elif opt == '-q': + status = None + elif opt == '-Q': + status = None + warning = None + elif opt == '-W': + warningiserror = True + elif opt == '-w': + warnfile = val + elif opt == '-P': + use_pdb = True + confoverrides['html_context'] = htmlcontext + + if warning and warnfile: + warnfp = open(warnfile, 'w') + warning = Tee(warning, warnfp) + error = warning + + try: + app = Sphinx(srcdir, confdir, outdir, doctreedir, buildername, + confoverrides, status, warning, freshenv, + warningiserror, tags) + app.build(all_files, filenames) + return app.statuscode + except KeyboardInterrupt: + if use_pdb: + import pdb + print >>error, darkred('Interrupted while building, ' + 'starting debugger:') + traceback.print_exc() + pdb.post_mortem(sys.exc_info()[2]) + return 1 + except Exception, err: + if use_pdb: + import pdb + print >>error, darkred('Exception occurred while building, ' + 'starting debugger:') + traceback.print_exc() + pdb.post_mortem(sys.exc_info()[2]) + else: + if isinstance(err, SystemMessage): + print >>error, darkred('reST markup error:') + print >>error, err.args[0].encode('ascii', 'backslashreplace') + elif isinstance(err, SphinxError): + print >>error, darkred('%s:' % err.category) + print >>error, err + else: + print >>error, darkred('Exception occurred:') + print >>error, format_exception_cut_frames().rstrip() + tbpath = save_traceback() + print >>error, darkred('The full traceback has been saved ' + 'in %s, if you want to report the ' + 'issue to the author.' % tbpath) + print >>error, ('Please also report this if it was a user ' + 'error, so that a better error message ' + 'can be provided next time.') + print >>error, ('Send reports to sphinx-dev@googlegroups.com. ' + 'Thanks!') + return 1 diff --git a/sphinx/config.py b/sphinx/config.py index 012668e79..3e3abb0db 100644 --- a/sphinx/config.py +++ b/sphinx/config.py @@ -5,102 +5,121 @@ Build configuration file handling. - :copyright: 2008 by Georg Brandl. - :license: BSD license. + :copyright: Copyright 2007-2009 by the Sphinx team, see AUTHORS. + :license: BSD, see LICENSE for details. """ import os from os import path +from sphinx.util import make_filename + class Config(object): """Configuration file abstraction.""" - # the values are: (default, needs fresh doctrees if changed) + # the values are: (default, what needs to be rebuilt if changed) # If you add a value here, don't forget to include it in the # quickstart.py file template as well as in the docs! config_values = dict( # general options - project = ('Python', True), - copyright = ('', False), - version = ('', True), - release = ('', True), - today = ('', True), - today_fmt = (None, True), # the real default is locale-dependent + project = ('Python', 'env'), + copyright = ('', 'html'), + version = ('', 'env'), + release = ('', 'env'), + today = ('', 'env'), + today_fmt = (None, 'env'), # the real default is locale-dependent - language = (None, True), - locale_dirs = ([], True), + language = (None, 'env'), + locale_dirs = ([], 'env'), - master_doc = ('contents', True), - source_suffix = ('.rst', True), - source_encoding = ('utf-8', True), - unused_docs = ([], True), - exclude_dirs = ([], True), - exclude_trees = ([], True), - exclude_dirnames = ([], True), - default_role = (None, True), - add_function_parentheses = (True, True), - add_module_names = (True, True), - show_authors = (False, True), - pygments_style = ('sphinx', False), - highlight_language = ('python', False), - templates_path = ([], False), - template_bridge = (None, False), - keep_warnings = (False, True), + master_doc = ('contents', 'env'), + source_suffix = ('.rst', 'env'), + source_encoding = ('utf-8', 'env'), + unused_docs = ([], 'env'), + exclude_dirs = ([], 'env'), + exclude_trees = ([], 'env'), + exclude_dirnames = ([], 'env'), + default_role = (None, 'env'), + add_function_parentheses = (True, 'env'), + add_module_names = (True, 'env'), + trim_footnote_reference_space = (False, 'env'), + show_authors = (False, 'env'), + pygments_style = (None, 'html'), + highlight_language = ('python', 'env'), + templates_path = ([], 'html'), + template_bridge = (None, 'html'), + keep_warnings = (False, 'env'), + modindex_common_prefix = ([], 'html'), + rst_epilog = (None, 'env'), # HTML options + html_theme = ('default', 'html'), + html_theme_path = ([], 'html'), + html_theme_options = ({}, 'html'), html_title = (lambda self: '%s v%s documentation' % (self.project, self.release), - False), - html_short_title = (lambda self: self.html_title, False), - html_style = ('default.css', False), - html_logo = (None, False), - html_favicon = (None, False), - html_static_path = ([], False), - html_last_updated_fmt = (None, False), # the real default is locale-dependent - html_use_smartypants = (True, False), - html_translator_class = (None, False), - html_sidebars = ({}, False), - html_additional_pages = ({}, False), - html_use_modindex = (True, False), - html_use_index = (True, False), - html_split_index = (False, False), - html_copy_source = (True, False), - html_use_opensearch = ('', False), - html_file_suffix = (None, False), - html_show_sphinx = (True, False), - html_context = ({}, False), + 'html'), + html_short_title = (lambda self: self.html_title, 'html'), + html_style = (None, 'html'), + html_logo = (None, 'html'), + html_favicon = (None, 'html'), + html_static_path = ([], 'html'), + # the real default is locale-dependent + html_last_updated_fmt = (None, 'html'), + html_use_smartypants = (True, 'html'), + html_translator_class = (None, 'html'), + html_sidebars = ({}, 'html'), + html_additional_pages = ({}, 'html'), + html_use_modindex = (True, 'html'), + html_add_permalinks = (True, 'html'), + html_use_index = (True, 'html'), + html_split_index = (False, 'html'), + html_copy_source = (True, 'html'), + html_show_sourcelink = (True, 'html'), + html_use_opensearch = ('', 'html'), + html_file_suffix = (None, 'html'), + html_link_suffix = (None, 'html'), + html_show_sphinx = (True, 'html'), + html_context = ({}, 'html'), # HTML help only options - htmlhelp_basename = ('pydoc', False), + htmlhelp_basename = (lambda self: make_filename(self.project), None), + + # Qt help only options + qthelp_basename = (lambda self: make_filename(self.project), None), # LaTeX options - latex_documents = ([], False), - latex_logo = (None, False), - latex_appendices = ([], False), - latex_use_parts = (False, False), - latex_use_modindex = (True, False), + latex_documents = ([], None), + latex_logo = (None, None), + latex_appendices = ([], None), + latex_use_parts = (False, None), + latex_use_modindex = (True, None), # paper_size and font_size are still separate values # so that you can give them easily on the command line - latex_paper_size = ('letter', False), - latex_font_size = ('10pt', False), - latex_elements = ({}, False), + latex_paper_size = ('letter', None), + latex_font_size = ('10pt', None), + latex_elements = ({}, None), + latex_additional_files = ([], None), # now deprecated - use latex_elements - latex_preamble = ('', False), + latex_preamble = ('', None), ) - def __init__(self, dirname, filename, overrides): + def __init__(self, dirname, filename, overrides, tags): self.overrides = overrides self.values = Config.config_values.copy() - config = {'__file__': path.join(dirname, filename)} - olddir = os.getcwd() - try: - os.chdir(dirname) - execfile(config['__file__'], config) - finally: - os.chdir(olddir) + config = {} + if dirname is not None: + config['__file__'] = path.join(dirname, filename) + config['tags'] = tags + olddir = os.getcwd() + try: + os.chdir(dirname) + execfile(config['__file__'], config) + finally: + os.chdir(olddir) self._raw_config = config # these two must be preinitialized because extensions can add their # own config values @@ -109,7 +128,12 @@ class Config(object): def init_values(self): config = self._raw_config - config.update(self.overrides) + for valname, value in self.overrides.iteritems(): + if '.' in valname: + realvalname, key = valname.split('.', 1) + config.setdefault(realvalname, {})[key] = value + else: + config[valname] = value for name in config: if name in self.values: self.__dict__[name] = config[name] @@ -121,7 +145,7 @@ class Config(object): if name not in self.values: raise AttributeError('No such config value: %s' % name) default = self.values[name][0] - if callable(default): + if hasattr(default, '__call__'): return default(self) return default diff --git a/sphinx/directives/__init__.py b/sphinx/directives/__init__.py index 462b2cffc..2de29010c 100644 --- a/sphinx/directives/__init__.py +++ b/sphinx/directives/__init__.py @@ -5,10 +5,23 @@ Handlers for additional ReST directives. - :copyright: 2008 by Georg Brandl. - :license: BSD. + :copyright: Copyright 2007-2009 by the Sphinx team, see AUTHORS. + :license: BSD, see LICENSE for details. """ +from docutils.parsers.rst import directives +from docutils.parsers.rst.directives import images + +# import and register directives from sphinx.directives.desc import * from sphinx.directives.code import * from sphinx.directives.other import * + + +# allow units for the figure's "figwidth" +try: + images.Figure.option_spec['figwidth'] = \ + directives.length_or_percentage_or_unitless +except AttributeError: + images.figure.options['figwidth'] = \ + directives.length_or_percentage_or_unitless diff --git a/sphinx/directives/code.py b/sphinx/directives/code.py index 5ea477635..645bc7844 100644 --- a/sphinx/directives/code.py +++ b/sphinx/directives/code.py @@ -3,10 +3,11 @@ sphinx.directives.code ~~~~~~~~~~~~~~~~~~~~~~ - :copyright: 2007-2008 by Georg Brandl. - :license: BSD. + :copyright: Copyright 2007-2009 by the Sphinx team, see AUTHORS. + :license: BSD, see LICENSE for details. """ +import os import sys import codecs from os import path @@ -15,85 +16,161 @@ from docutils import nodes from docutils.parsers.rst import directives from sphinx import addnodes +from sphinx.util import parselinenos +from sphinx.util.compat import Directive, directive_dwim -# ------ highlight directive -------------------------------------------------------- +class Highlight(Directive): + """ + Directive to set the highlighting language for code blocks, as well + as the threshold for line numbers. + """ -def highlightlang_directive(name, arguments, options, content, lineno, - content_offset, block_text, state, state_machine): - if 'linenothreshold' in options: + has_content = False + required_arguments = 1 + optional_arguments = 0 + final_argument_whitespace = False + option_spec = { + 'linenothreshold': directives.unchanged, + } + + def run(self): + if 'linenothreshold' in self.options: + try: + linenothreshold = int(self.options['linenothreshold']) + except Exception: + linenothreshold = 10 + else: + linenothreshold = sys.maxint + return [addnodes.highlightlang(lang=self.arguments[0].strip(), + linenothreshold=linenothreshold)] + + +class CodeBlock(Directive): + """ + Directive for a code block with special highlighting or line numbering + settings. + """ + + has_content = True + required_arguments = 1 + optional_arguments = 0 + final_argument_whitespace = False + option_spec = { + 'linenos': directives.flag, + } + + def run(self): + code = u'\n'.join(self.content) + literal = nodes.literal_block(code, code) + literal['language'] = self.arguments[0] + literal['linenos'] = 'linenos' in self.options + return [literal] + + +class LiteralInclude(Directive): + """ + Like ``.. include:: :literal:``, but only warns if the include file is + not found, and does not raise errors. Also has several options for + selecting what to include. + """ + + has_content = False + required_arguments = 1 + optional_arguments = 0 + final_argument_whitespace = False + option_spec = { + 'linenos': directives.flag, + 'language': directives.unchanged_required, + 'encoding': directives.encoding, + 'pyobject': directives.unchanged_required, + 'lines': directives.unchanged_required, + 'start-after': directives.unchanged_required, + 'end-before': directives.unchanged_required, + } + + def run(self): + document = self.state.document + filename = self.arguments[0] + if not document.settings.file_insertion_enabled: + return [document.reporter.warning('File insertion disabled', + line=self.lineno)] + env = document.settings.env + if filename.startswith('/') or filename.startswith(os.sep): + rel_fn = filename[1:] + else: + docdir = path.dirname(env.doc2path(env.docname, base=None)) + rel_fn = path.normpath(path.join(docdir, filename)) + fn = path.join(env.srcdir, rel_fn) + + if 'pyobject' in self.options and 'lines' in self.options: + return [document.reporter.warning( + 'Cannot use both "pyobject" and "lines" options', + line=self.lineno)] + + encoding = self.options.get('encoding', env.config.source_encoding) try: - linenothreshold = int(options['linenothreshold']) - except Exception: - linenothreshold = 10 - else: - linenothreshold = sys.maxint - return [addnodes.highlightlang(lang=arguments[0].strip(), - linenothreshold=linenothreshold)] + f = codecs.open(fn, 'rU', encoding) + lines = f.readlines() + f.close() + except (IOError, OSError): + return [document.reporter.warning( + 'Include file %r not found or reading it failed' % filename, + line=self.lineno)] + except UnicodeError: + return [document.reporter.warning( + 'Encoding %r used for reading included file %r seems to ' + 'be wrong, try giving an :encoding: option' % + (encoding, filename))] -highlightlang_directive.content = 0 -highlightlang_directive.arguments = (1, 0, 0) -highlightlang_directive.options = {'linenothreshold': directives.unchanged} -directives.register_directive('highlight', highlightlang_directive) -directives.register_directive('highlightlang', highlightlang_directive) # old name + objectname = self.options.get('pyobject') + if objectname is not None: + from sphinx.pycode import ModuleAnalyzer + analyzer = ModuleAnalyzer.for_file(fn, '') + tags = analyzer.find_tags() + if objectname not in tags: + return [document.reporter.warning( + 'Object named %r not found in include file %r' % + (objectname, filename), line=self.lineno)] + else: + lines = lines[tags[objectname][1]-1 : tags[objectname][2]-1] + linespec = self.options.get('lines') + if linespec is not None: + try: + linelist = parselinenos(linespec, len(lines)) + except ValueError, err: + return [document.reporter.warning(str(err), line=self.lineno)] + lines = [lines[i] for i in linelist] -# ------ code-block directive ------------------------------------------------------- + startafter = self.options.get('start-after') + endbefore = self.options.get('end-before') + if startafter is not None or endbefore is not None: + use = not startafter + res = [] + for line in lines: + if not use and startafter in line: + use = True + elif use and endbefore in line: + use = False + break + elif use: + res.append(line) + lines = res -def codeblock_directive(name, arguments, options, content, lineno, - content_offset, block_text, state, state_machine): - code = u'\n'.join(content) - literal = nodes.literal_block(code, code) - literal['language'] = arguments[0] - literal['linenos'] = 'linenos' in options - return [literal] - -codeblock_directive.content = 1 -codeblock_directive.arguments = (1, 0, 0) -codeblock_directive.options = {'linenos': directives.flag} -directives.register_directive('code-block', codeblock_directive) -directives.register_directive('sourcecode', codeblock_directive) - - -# ------ literalinclude directive --------------------------------------------------- - -def literalinclude_directive(name, arguments, options, content, lineno, - content_offset, block_text, state, state_machine): - """Like .. include:: :literal:, but only warns if the include file is not found.""" - if not state.document.settings.file_insertion_enabled: - return [state.document.reporter.warning('File insertion disabled', line=lineno)] - env = state.document.settings.env - rel_fn = arguments[0] - source_dir = path.dirname(path.abspath(state_machine.input_lines.source( - lineno - state_machine.input_offset - 1))) - fn = path.normpath(path.join(source_dir, rel_fn)) - - encoding = options.get('encoding', env.config.source_encoding) - try: - f = codecs.open(fn, 'r', encoding) - text = f.read() - f.close() - except (IOError, OSError): - retnode = state.document.reporter.warning( - 'Include file %r not found or reading it failed' % arguments[0], line=lineno) - except UnicodeError: - retnode = state.document.reporter.warning( - 'Encoding %r used for reading included file %r seems to ' - 'be wrong, try giving an :encoding: option' % - (encoding, arguments[0])) - else: + text = ''.join(lines) retnode = nodes.literal_block(text, text, source=fn) retnode.line = 1 - if options.get('language', ''): - retnode['language'] = options['language'] - if 'linenos' in options: + if self.options.get('language', ''): + retnode['language'] = self.options['language'] + if 'linenos' in self.options: retnode['linenos'] = True - state.document.settings.env.note_dependency(rel_fn) - return [retnode] + document.settings.env.note_dependency(rel_fn) + return [retnode] -literalinclude_directive.options = {'linenos': directives.flag, - 'language': directives.unchanged, - 'encoding': directives.encoding} -literalinclude_directive.content = 0 -literalinclude_directive.arguments = (1, 0, 0) -directives.register_directive('literalinclude', literalinclude_directive) + +directives.register_directive('highlight', directive_dwim(Highlight)) +directives.register_directive('highlightlang', directive_dwim(Highlight)) # old +directives.register_directive('code-block', directive_dwim(CodeBlock)) +directives.register_directive('sourcecode', directive_dwim(CodeBlock)) +directives.register_directive('literalinclude', directive_dwim(LiteralInclude)) diff --git a/sphinx/directives/desc.py b/sphinx/directives/desc.py index a73748920..60b43a5d9 100644 --- a/sphinx/directives/desc.py +++ b/sphinx/directives/desc.py @@ -3,8 +3,8 @@ sphinx.directives.desc ~~~~~~~~~~~~~~~~~~~~~~ - :copyright: 2007-2008 by Georg Brandl. - :license: BSD. + :copyright: Copyright 2007-2009 by the Sphinx team, see AUTHORS. + :license: BSD, see LICENSE for details. """ import re @@ -14,258 +14,35 @@ from docutils import nodes from docutils.parsers.rst import directives from sphinx import addnodes +from sphinx.util import ws_re +from sphinx.util.compat import Directive, directive_dwim -ws_re = re.compile(r'\s+') - -# ------ information units --------------------------------------------------------- - -def desc_index_text(desctype, module, name, add_modules): - if desctype == 'function': - if not module: - return _('%s() (built-in function)') % name - return _('%s() (in module %s)') % (name, module) - elif desctype == 'data': - if not module: - return _('%s (built-in variable)') % name - return _('%s (in module %s)') % (name, module) - elif desctype == 'class': - if not module: - return _('%s (built-in class)') % name - return _('%s (class in %s)') % (name, module) - elif desctype == 'exception': - return name - elif desctype == 'method': - try: - clsname, methname = name.rsplit('.', 1) - except ValueError: - if module: - return _('%s() (in module %s)') % (name, module) - else: - return '%s()' % name - if module and add_modules: - return _('%s() (%s.%s method)') % (methname, module, clsname) - else: - return _('%s() (%s method)') % (methname, clsname) - elif desctype == 'staticmethod': - try: - clsname, methname = name.rsplit('.', 1) - except ValueError: - if module: - return _('%s() (in module %s)') % (name, module) - else: - return '%s()' % name - if module and add_modules: - return _('%s() (%s.%s static method)') % (methname, module, clsname) - else: - return _('%s() (%s static method)') % (methname, clsname) - elif desctype == 'attribute': - try: - clsname, attrname = name.rsplit('.', 1) - except ValueError: - if module: - return _('%s (in module %s)') % (name, module) - else: - return name - if module and add_modules: - return _('%s (%s.%s attribute)') % (attrname, module, clsname) - else: - return _('%s (%s attribute)') % (attrname, clsname) - elif desctype == 'cfunction': - return _('%s (C function)') % name - elif desctype == 'cmember': - return _('%s (C member)') % name - elif desctype == 'cmacro': - return _('%s (C macro)') % name - elif desctype == 'ctype': - return _('%s (C type)') % name - elif desctype == 'cvar': - return _('%s (C variable)') % name - else: - raise ValueError('unhandled descenv: %s' % desctype) +def _is_only_paragraph(node): + """True if the node only contains one paragraph (and system messages).""" + if len(node) == 0: + return False + elif len(node) > 1: + for subnode in node[1:]: + if not isinstance(subnode, nodes.system_message): + return False + if isinstance(node[0], nodes.paragraph): + return True + return False -# ------ make field lists (like :param foo:) in desc bodies prettier - -_ = lambda x: x # make gettext extraction in constants possible - -doc_fields_with_arg = { - 'param': '%param', - 'parameter': '%param', - 'arg': '%param', - 'argument': '%param', - 'keyword': '%param', - 'kwarg': '%param', - 'kwparam': '%param', - 'type': '%type', - 'raises': _('Raises'), - 'raise': 'Raises', - 'exception': 'Raises', - 'except': 'Raises', - 'var': _('Variable'), - 'ivar': 'Variable', - 'cvar': 'Variable', - 'returns': _('Returns'), - 'return': 'Returns', -} - -doc_fields_without_arg = { - 'returns': 'Returns', - 'return': 'Returns', - 'rtype': _('Return type'), -} - -del _ - -def handle_doc_fields(node): - # don't traverse, only handle field lists that are immediate children - for child in node.children: - if not isinstance(child, nodes.field_list): - continue - params = None - param_nodes = {} - param_types = {} - new_list = nodes.field_list() - for field in child: - fname, fbody = field - try: - typ, obj = fname.astext().split(None, 1) - typ = _(doc_fields_with_arg[typ]) - if len(fbody.children) == 1 and \ - isinstance(fbody.children[0], nodes.paragraph): - children = fbody.children[0].children - else: - children = fbody.children - if typ == '%param': - if not params: - pfield = nodes.field() - pfield += nodes.field_name('', _('Parameters')) - pfield += nodes.field_body() - params = nodes.bullet_list() - pfield[1] += params - new_list += pfield - dlitem = nodes.list_item() - dlpar = nodes.paragraph() - dlpar += nodes.emphasis(obj, obj) - dlpar += nodes.Text(' -- ', ' -- ') - dlpar += children - param_nodes[obj] = dlpar - dlitem += dlpar - params += dlitem - elif typ == '%type': - param_types[obj] = fbody.astext() - else: - fieldname = typ + ' ' + obj - nfield = nodes.field() - nfield += nodes.field_name(fieldname, fieldname) - nfield += nodes.field_body() - nfield[1] += fbody.children - new_list += nfield - except (KeyError, ValueError): - fnametext = fname.astext() - try: - typ = _(doc_fields_without_arg[fnametext]) - except KeyError: - # at least capitalize the field name - typ = fnametext.capitalize() - fname[0] = nodes.Text(typ) - new_list += field - for param, type in param_types.iteritems(): - if param in param_nodes: - param_nodes[param].insert(1, nodes.Text(' (%s)' % type)) - child.replace_self(new_list) - - -# ------ functions to parse a Python or C signature and create desc_* nodes. - +# REs for Python signatures py_sig_re = re.compile( r'''^ ([\w.]*\.)? # class name(s) (\w+) \s* # thing name - (?: \((.*)\) # optional arguments - (\s* -> \s* .*)? )? $ # optional return annotation + (?: \((.*)\) # optional: arguments + (?:\s* -> \s* (.*))? # return annotation + )? $ # and nothing more ''', re.VERBOSE) py_paramlist_re = re.compile(r'([\[\],])') # split at '[', ']' and ',' -def parse_py_signature(signode, sig, desctype, module, env): - """ - Transform a python signature into RST nodes. - Return (fully qualified name of the thing, classname if any). - - If inside a class, the current class name is handled intelligently: - * it is stripped from the displayed name if present - * it is added to the full name (return value) if not present - """ - m = py_sig_re.match(sig) - if m is None: - raise ValueError - classname, name, arglist, retann = m.groups() - - if retann: - retann = u' \N{RIGHTWARDS ARROW} ' + retann.strip()[2:] - - if env.currclass: - add_module = False - if classname and classname.startswith(env.currclass): - fullname = classname + name - # class name is given again in the signature - classname = classname[len(env.currclass):].lstrip('.') - elif classname: - # class name is given in the signature, but different - # (shouldn't happen) - fullname = env.currclass + '.' + classname + name - else: - # class name is not given in the signature - fullname = env.currclass + '.' + name - else: - add_module = True - fullname = classname and classname + name or name - - if desctype == 'staticmethod': - signode += addnodes.desc_annotation('static ', 'static ') - - if classname: - signode += addnodes.desc_addname(classname, classname) - # exceptions are a special case, since they are documented in the - # 'exceptions' module. - elif add_module and env.config.add_module_names and \ - module and module != 'exceptions': - nodetext = module + '.' - signode += addnodes.desc_addname(nodetext, nodetext) - - signode += addnodes.desc_name(name, name) - if not arglist: - if desctype in ('function', 'method', 'staticmethod'): - # for callables, add an empty parameter list - signode += addnodes.desc_parameterlist() - if retann: - signode += addnodes.desc_type(retann, retann) - return fullname, classname - signode += addnodes.desc_parameterlist() - - stack = [signode[-1]] - for token in py_paramlist_re.split(arglist): - if token == '[': - opt = addnodes.desc_optional() - stack[-1] += opt - stack.append(opt) - elif token == ']': - try: - stack.pop() - except IndexError: - raise ValueError - elif not token or token == ',' or token.isspace(): - pass - else: - token = token.strip() - stack[-1] += addnodes.desc_parameter(token, token) - if len(stack) != 1: - raise ValueError - if retann: - signode += addnodes.desc_type(retann, retann) - return fullname, classname - - +# REs for C signatures c_sig_re = re.compile( r'''^([^(]*?) # return type ([\w:]+) \s* # thing name (colon allowed for C++ class names) @@ -280,242 +57,689 @@ c_funcptr_sig_re = re.compile( ''', re.VERBOSE) c_funcptr_name_re = re.compile(r'^\(\s*\*\s*(.*?)\s*\)$') +# RE for option descriptions +option_desc_re = re.compile( + r'((?:/|-|--)[-_a-zA-Z0-9]+)(\s*.*?)(?=,\s+(?:/|-|--)|$)') + # RE to split at word boundaries wsplit_re = re.compile(r'(\W+)') -# These C types aren't described in the reference, so don't try to create -# a cross-reference to them -stopwords = set(('const', 'void', 'char', 'int', 'long', 'FILE', 'struct')) - -def parse_c_type(node, ctype): - # add cross-ref nodes for all words - for part in filter(None, wsplit_re.split(ctype)): - tnode = nodes.Text(part, part) - if part[0] in string.letters+'_' and part not in stopwords: - pnode = addnodes.pending_xref( - '', reftype='ctype', reftarget=part, modname=None, classname=None) - pnode += tnode - node += pnode - else: - node += tnode - -def parse_c_signature(signode, sig, desctype): - """Transform a C (or C++) signature into RST nodes.""" - # first try the function pointer signature regex, it's more specific - m = c_funcptr_sig_re.match(sig) - if m is None: - m = c_sig_re.match(sig) - if m is None: - raise ValueError('no match') - rettype, name, arglist, const = m.groups() - - signode += addnodes.desc_type('', '') - parse_c_type(signode[-1], rettype) - try: - classname, funcname = name.split('::', 1) - classname += '::' - signode += addnodes.desc_addname(classname, classname) - signode += addnodes.desc_name(funcname, funcname) - # name (the full name) is still both parts - except ValueError: - signode += addnodes.desc_name(name, name) - # clean up parentheses from canonical name - m = c_funcptr_name_re.match(name) - if m: - name = m.group(1) - if not arglist: - if desctype == 'cfunction': - # for functions, add an empty parameter list - signode += addnodes.desc_parameterlist() - return name - - paramlist = addnodes.desc_parameterlist() - arglist = arglist.replace('`', '').replace('\\ ', '') # remove markup - # this messes up function pointer types, but not too badly ;) - args = arglist.split(',') - for arg in args: - arg = arg.strip() - param = addnodes.desc_parameter('', '', noemph=True) - try: - ctype, argname = arg.rsplit(' ', 1) - except ValueError: - # no argument name given, only the type - parse_c_type(param, arg) - else: - parse_c_type(param, ctype) - param += nodes.emphasis(' '+argname, ' '+argname) - paramlist += param - signode += paramlist - if const: - signode += addnodes.desc_addname(const, const) - return name +# RE to strip backslash escapes +strip_backslash_re = re.compile(r'\\(?=[^\\])') -option_desc_re = re.compile( - r'(/|-|--)([-_a-zA-Z0-9]+)(\s*.*?)(?=,\s+(?:/|-|--)|$)') +class DescDirective(Directive): + """ + Directive to describe a class, function or similar object. Not used + directly, but subclassed to add custom behavior. + """ -def parse_option_desc(signode, sig): - """Transform an option description into RST nodes.""" - count = 0 - firstname = '' - for m in option_desc_re.finditer(sig): - prefix, optname, args = m.groups() - if count: - signode += addnodes.desc_addname(', ', ', ') - signode += addnodes.desc_name(prefix+optname, prefix+optname) - signode += addnodes.desc_addname(args, args) - if not count: - firstname = optname - count += 1 - if not firstname: - raise ValueError - return firstname + has_content = True + required_arguments = 1 + optional_arguments = 0 + final_argument_whitespace = True + option_spec = { + 'noindex': directives.flag, + 'module': directives.unchanged, + } + _ = lambda x: x # make gettext extraction in constants possible -def desc_directive(desctype, arguments, options, content, lineno, - content_offset, block_text, state, state_machine): - env = state.document.settings.env - inode = addnodes.index(entries=[]) - node = addnodes.desc() - node['desctype'] = desctype + doc_fields_with_arg = { + 'param': '%param', + 'parameter': '%param', + 'arg': '%param', + 'argument': '%param', + 'keyword': '%param', + 'kwarg': '%param', + 'kwparam': '%param', + 'type': '%type', + 'raises': _('Raises'), + 'raise': 'Raises', + 'exception': 'Raises', + 'except': 'Raises', + 'var': _('Variable'), + 'ivar': 'Variable', + 'cvar': 'Variable', + 'returns': _('Returns'), + 'return': 'Returns', + } - noindex = ('noindex' in options) - node['noindex'] = noindex - # remove backslashes to support (dummy) escapes; helps Vim's highlighting - signatures = map(lambda s: s.strip().replace('\\', ''), arguments[0].split('\n')) - names = [] - clsname = None - module = options.get('module', env.currmodule) - for i, sig in enumerate(signatures): - # add a signature node for each signature in the current unit - # and add a reference target for it - sig = sig.strip() - signode = addnodes.desc_signature(sig, '') - signode['first'] = False - node.append(signode) - try: - if desctype in ('function', 'data', 'class', 'exception', - 'method', 'staticmethod', 'attribute'): - name, clsname = parse_py_signature(signode, sig, desctype, module, env) - elif desctype in ('cfunction', 'cmember', 'cmacro', 'ctype', 'cvar'): - name = parse_c_signature(signode, sig, desctype) - elif desctype == 'cmdoption': - optname = parse_option_desc(signode, sig) - if not noindex: - targetname = 'cmdoption-' + optname - signode['ids'].append(targetname) - state.document.note_explicit_target(signode) - inode['entries'].append(('pair', _('command line option; %s') % sig, - targetname, targetname)) - env.note_reftarget('option', optname, targetname) + doc_fields_with_linked_arg = ('raises', 'raise', 'exception', 'except') + + doc_fields_without_arg = { + 'returns': 'Returns', + 'return': 'Returns', + 'rtype': _('Return type'), + } + + def handle_doc_fields(self, node): + """ + Convert field lists with known keys inside the description content into + better-looking equivalents. + """ + # don't traverse, only handle field lists that are immediate children + for child in node.children: + if not isinstance(child, nodes.field_list): continue - elif desctype == 'describe': + params = [] + pfield = None + param_nodes = {} + param_types = {} + new_list = nodes.field_list() + for field in child: + fname, fbody = field + try: + typ, obj = fname.astext().split(None, 1) + typdesc = _(self.doc_fields_with_arg[typ]) + if _is_only_paragraph(fbody): + children = fbody.children[0].children + else: + children = fbody.children + if typdesc == '%param': + if not params: + # add the field that later gets all the parameters + pfield = nodes.field() + new_list += pfield + dlitem = nodes.list_item() + dlpar = nodes.paragraph() + dlpar += nodes.emphasis(obj, obj) + dlpar += nodes.Text(' -- ', ' -- ') + dlpar += children + param_nodes[obj] = dlpar + dlitem += dlpar + params.append(dlitem) + elif typdesc == '%type': + typenodes = fbody.children + if _is_only_paragraph(fbody): + typenodes = ([nodes.Text(' (')] + + typenodes[0].children + + [nodes.Text(')')]) + param_types[obj] = typenodes + else: + fieldname = typdesc + ' ' + nfield = nodes.field() + nfieldname = nodes.field_name(fieldname, fieldname) + nfield += nfieldname + node = nfieldname + if typ in self.doc_fields_with_linked_arg: + node = addnodes.pending_xref( + obj, reftype='obj', refcaption=False, + reftarget=obj, modname=self.env.currmodule, + classname=self.env.currclass) + nfieldname += node + node += nodes.Text(obj, obj) + nfield += nodes.field_body() + nfield[1] += fbody.children + new_list += nfield + except (KeyError, ValueError): + fnametext = fname.astext() + try: + typ = _(self.doc_fields_without_arg[fnametext]) + except KeyError: + # at least capitalize the field name + typ = fnametext.capitalize() + fname[0] = nodes.Text(typ) + new_list += field + if params: + if len(params) == 1: + pfield += nodes.field_name('', _('Parameter')) + pfield += nodes.field_body() + pfield[1] += params[0][0] + else: + pfield += nodes.field_name('', _('Parameters')) + pfield += nodes.field_body() + pfield[1] += nodes.bullet_list() + pfield[1][0].extend(params) + + for param, type in param_types.iteritems(): + if param in param_nodes: + param_nodes[param][1:1] = type + child.replace_self(new_list) + + def get_signatures(self): + """ + Retrieve the signatures to document from the directive arguments. + """ + # remove backslashes to support (dummy) escapes; helps Vim highlighting + return [strip_backslash_re.sub('', sig.strip()) + for sig in self.arguments[0].split('\n')] + + def parse_signature(self, sig, signode): + """ + Parse the signature *sig* into individual nodes and append them to + *signode*. If ValueError is raised, parsing is aborted and the whole + *sig* is put into a single desc_name node. + """ + raise ValueError + + def add_target_and_index(self, name, sig, signode): + """ + Add cross-reference IDs and entries to self.indexnode, if applicable. + """ + return # do nothing by default + + def before_content(self): + """ + Called before parsing content. Used to set information about the current + directive context on the build environment. + """ + pass + + def after_content(self): + """ + Called after parsing content. Used to reset information about the + current directive context on the build environment. + """ + pass + + def run(self): + self.desctype = self.name + self.env = self.state.document.settings.env + self.indexnode = addnodes.index(entries=[]) + + node = addnodes.desc() + node.document = self.state.document + node['desctype'] = self.desctype + node['noindex'] = noindex = ('noindex' in self.options) + + self.names = [] + signatures = self.get_signatures() + for i, sig in enumerate(signatures): + # add a signature node for each signature in the current unit + # and add a reference target for it + signode = addnodes.desc_signature(sig, '') + signode['first'] = False + node.append(signode) + try: + # name can also be a tuple, e.g. (classname, objname) + name = self.parse_signature(sig, signode) + except ValueError, err: + # signature parsing failed signode.clear() signode += addnodes.desc_name(sig, sig) - continue + continue # we don't want an index entry here + if not noindex and name not in self.names: + # only add target and index entry if this is the first + # description of the object with this name in this desc block + self.names.append(name) + self.add_target_and_index(name, sig, signode) + + contentnode = addnodes.desc_content() + node.append(contentnode) + if self.names: + # needed for association of version{added,changed} directives + self.env.currdesc = self.names[0] + self.before_content() + self.state.nested_parse(self.content, self.content_offset, contentnode) + self.handle_doc_fields(contentnode) + self.env.currdesc = None + self.after_content() + return [self.indexnode, node] + + +class PythonDesc(DescDirective): + """ + Description of a general Python object. + """ + + def get_signature_prefix(self, sig): + """ + May return a prefix to put before the object name in the signature. + """ + return '' + + def needs_arglist(self): + """ + May return true if an empty argument list is to be generated even if + the document contains none. + """ + return False + + def parse_signature(self, sig, signode): + """ + Transform a Python signature into RST nodes. + Returns (fully qualified name of the thing, classname if any). + + If inside a class, the current class name is handled intelligently: + * it is stripped from the displayed name if present + * it is added to the full name (return value) if not present + """ + m = py_sig_re.match(sig) + if m is None: + raise ValueError + classname, name, arglist, retann = m.groups() + + if self.env.currclass: + add_module = False + if classname and classname.startswith(self.env.currclass): + fullname = classname + name + # class name is given again in the signature + classname = classname[len(self.env.currclass):].lstrip('.') + elif classname: + # class name is given in the signature, but different + # (shouldn't happen) + fullname = self.env.currclass + '.' + classname + name else: - # another registered generic x-ref directive - rolename, indextemplate, parse_node = additional_xref_types[desctype] - if parse_node: - fullname = parse_node(env, sig, signode) + # class name is not given in the signature + fullname = self.env.currclass + '.' + name + else: + add_module = True + fullname = classname and classname + name or name + + prefix = self.get_signature_prefix(sig) + if prefix: + signode += addnodes.desc_annotation(prefix, prefix) + + if classname: + signode += addnodes.desc_addname(classname, classname) + # exceptions are a special case, since they are documented in the + # 'exceptions' module. + elif add_module and self.env.config.add_module_names: + modname = self.options.get('module', self.env.currmodule) + if modname and modname != 'exceptions': + nodetext = modname + '.' + signode += addnodes.desc_addname(nodetext, nodetext) + + signode += addnodes.desc_name(name, name) + if not arglist: + if self.needs_arglist(): + # for callables, add an empty parameter list + signode += addnodes.desc_parameterlist() + if retann: + signode += addnodes.desc_returns(retann, retann) + return fullname, classname + signode += addnodes.desc_parameterlist() + + stack = [signode[-1]] + for token in py_paramlist_re.split(arglist): + if token == '[': + opt = addnodes.desc_optional() + stack[-1] += opt + stack.append(opt) + elif token == ']': + try: + stack.pop() + except IndexError: + raise ValueError + elif not token or token == ',' or token.isspace(): + pass + else: + token = token.strip() + stack[-1] += addnodes.desc_parameter(token, token) + if len(stack) != 1: + raise ValueError + if retann: + signode += addnodes.desc_returns(retann, retann) + return fullname, classname + + def get_index_text(self, modname, name): + """ + Return the text for the index entry of the object. + """ + raise NotImplementedError('must be implemented in subclasses') + + def add_target_and_index(self, name_cls, sig, signode): + modname = self.options.get('module', self.env.currmodule) + fullname = (modname and modname + '.' or '') + name_cls[0] + # note target + if fullname not in self.state.document.ids: + signode['names'].append(fullname) + signode['ids'].append(fullname) + signode['first'] = (not self.names) + self.state.document.note_explicit_target(signode) + self.env.note_descref(fullname, self.desctype, self.lineno) + + indextext = self.get_index_text(modname, name_cls) + if indextext: + self.indexnode['entries'].append(('single', indextext, + fullname, fullname)) + + def before_content(self): + # needed for automatic qualification of members (reset in subclasses) + self.clsname_set = False + + def after_content(self): + if self.clsname_set: + self.env.currclass = None + + +class ModulelevelDesc(PythonDesc): + """ + Description of an object on module level (functions, data). + """ + + def needs_arglist(self): + return self.desctype == 'function' + + def get_index_text(self, modname, name_cls): + if self.desctype == 'function': + if not modname: + return _('%s() (built-in function)') % name_cls[0] + return _('%s() (in module %s)') % (name_cls[0], modname) + elif self.desctype == 'data': + if not modname: + return _('%s (built-in variable)') % name_cls[0] + return _('%s (in module %s)') % (name_cls[0], modname) + else: + return '' + + +class ClasslikeDesc(PythonDesc): + """ + Description of a class-like object (classes, interfaces, exceptions). + """ + + def get_signature_prefix(self, sig): + return self.desctype + ' ' + + def get_index_text(self, modname, name_cls): + if self.desctype == 'class': + if not modname: + return _('%s (built-in class)') % name_cls[0] + return _('%s (class in %s)') % (name_cls[0], modname) + elif self.desctype == 'exception': + return name_cls[0] + else: + return '' + + def before_content(self): + PythonDesc.before_content(self) + if self.names: + self.env.currclass = self.names[0][0] + self.clsname_set = True + + +class ClassmemberDesc(PythonDesc): + """ + Description of a class member (methods, attributes). + """ + + def needs_arglist(self): + return self.desctype.endswith('method') + + def get_signature_prefix(self, sig): + if self.desctype == 'staticmethod': + return 'static ' + elif self.desctype == 'classmethod': + return 'classmethod ' + return '' + + def get_index_text(self, modname, name_cls): + name, cls = name_cls + add_modules = self.env.config.add_module_names + if self.desctype == 'method': + try: + clsname, methname = name.rsplit('.', 1) + except ValueError: + if modname: + return _('%s() (in module %s)') % (name, modname) else: - signode.clear() - signode += addnodes.desc_name(sig, sig) - # normalize whitespace like xfileref_role does - fullname = ws_re.sub('', sig) - if not noindex: - targetname = '%s-%s' % (rolename, fullname) - signode['ids'].append(targetname) - state.document.note_explicit_target(signode) - if indextemplate: - indexentry = _(indextemplate) % (fullname,) - indextype = 'single' - colon = indexentry.find(':') - if colon != -1: - indextype = indexentry[:colon].strip() - indexentry = indexentry[colon+1:].strip() - inode['entries'].append((indextype, indexentry, - targetname, targetname)) - env.note_reftarget(rolename, fullname, targetname) - # don't use object indexing below - continue - except ValueError, err: - # signature parsing failed + return '%s()' % name + if modname and add_modules: + return _('%s() (%s.%s method)') % (methname, modname, clsname) + else: + return _('%s() (%s method)') % (methname, clsname) + elif self.desctype == 'staticmethod': + try: + clsname, methname = name.rsplit('.', 1) + except ValueError: + if modname: + return _('%s() (in module %s)') % (name, modname) + else: + return '%s()' % name + if modname and add_modules: + return _('%s() (%s.%s static method)') % (methname, modname, + clsname) + else: + return _('%s() (%s static method)') % (methname, clsname) + elif self.desctype == 'classmethod': + try: + clsname, methname = name.rsplit('.', 1) + except ValueError: + if modname: + return '%s() (in module %s)' % (name, modname) + else: + return '%s()' % name + if modname: + return '%s() (%s.%s class method)' % (methname, modname, + clsname) + else: + return '%s() (%s class method)' % (methname, clsname) + elif self.desctype == 'attribute': + try: + clsname, attrname = name.rsplit('.', 1) + except ValueError: + if modname: + return _('%s (in module %s)') % (name, modname) + else: + return name + if modname and add_modules: + return _('%s (%s.%s attribute)') % (attrname, modname, clsname) + else: + return _('%s (%s attribute)') % (attrname, clsname) + else: + return '' + + def before_content(self): + PythonDesc.before_content(self) + if self.names and self.names[-1][1] and not self.env.currclass: + self.env.currclass = self.names[-1][1].strip('.') + self.clsname_set = True + + +class CDesc(DescDirective): + """ + Description of a C language object. + """ + + # These C types aren't described anywhere, so don't try to create + # a cross-reference to them + stopwords = set(('const', 'void', 'char', 'int', 'long', 'FILE', 'struct')) + + def _parse_type(self, node, ctype): + # add cross-ref nodes for all words + for part in filter(None, wsplit_re.split(ctype)): + tnode = nodes.Text(part, part) + if part[0] in string.ascii_letters+'_' and \ + part not in self.stopwords: + pnode = addnodes.pending_xref( + '', reftype='ctype', reftarget=part, + modname=None, classname=None) + pnode += tnode + node += pnode + else: + node += tnode + + def parse_signature(self, sig, signode): + """Transform a C (or C++) signature into RST nodes.""" + # first try the function pointer signature regex, it's more specific + m = c_funcptr_sig_re.match(sig) + if m is None: + m = c_sig_re.match(sig) + if m is None: + raise ValueError('no match') + rettype, name, arglist, const = m.groups() + + signode += addnodes.desc_type('', '') + self._parse_type(signode[-1], rettype) + try: + classname, funcname = name.split('::', 1) + classname += '::' + signode += addnodes.desc_addname(classname, classname) + signode += addnodes.desc_name(funcname, funcname) + # name (the full name) is still both parts + except ValueError: + signode += addnodes.desc_name(name, name) + # clean up parentheses from canonical name + m = c_funcptr_name_re.match(name) + if m: + name = m.group(1) + if not arglist: + if self.desctype == 'cfunction': + # for functions, add an empty parameter list + signode += addnodes.desc_parameterlist() + return name + + paramlist = addnodes.desc_parameterlist() + arglist = arglist.replace('`', '').replace('\\ ', '') # remove markup + # this messes up function pointer types, but not too badly ;) + args = arglist.split(',') + for arg in args: + arg = arg.strip() + param = addnodes.desc_parameter('', '', noemph=True) + try: + ctype, argname = arg.rsplit(' ', 1) + except ValueError: + # no argument name given, only the type + self._parse_type(param, arg) + else: + self._parse_type(param, ctype) + param += nodes.emphasis(' '+argname, ' '+argname) + paramlist += param + signode += paramlist + if const: + signode += addnodes.desc_addname(const, const) + return name + + def get_index_text(self, name): + if self.desctype == 'cfunction': + return _('%s (C function)') % name + elif self.desctype == 'cmember': + return _('%s (C member)') % name + elif self.desctype == 'cmacro': + return _('%s (C macro)') % name + elif self.desctype == 'ctype': + return _('%s (C type)') % name + elif self.desctype == 'cvar': + return _('%s (C variable)') % name + else: + return '' + + def add_target_and_index(self, name, sig, signode): + # note target + if name not in self.state.document.ids: + signode['names'].append(name) + signode['ids'].append(name) + signode['first'] = (not self.names) + self.state.document.note_explicit_target(signode) + self.env.note_descref(name, self.desctype, self.lineno) + + indextext = self.get_index_text(name) + if indextext: + self.indexnode['entries'].append(('single', indextext, name, name)) + + +class CmdoptionDesc(DescDirective): + """ + Description of a command-line option (.. cmdoption). + """ + + def parse_signature(self, sig, signode): + """Transform an option description into RST nodes.""" + count = 0 + firstname = '' + for m in option_desc_re.finditer(sig): + optname, args = m.groups() + if count: + signode += addnodes.desc_addname(', ', ', ') + signode += addnodes.desc_name(optname, optname) + signode += addnodes.desc_addname(args, args) + if not count: + firstname = optname + count += 1 + if not firstname: + raise ValueError + return firstname + + def add_target_and_index(self, name, sig, signode): + targetname = name.replace('/', '-') + if self.env.currprogram: + targetname = '-' + self.env.currprogram + targetname + targetname = 'cmdoption' + targetname + signode['ids'].append(targetname) + self.state.document.note_explicit_target(signode) + self.indexnode['entries'].append( + ('pair', _('%scommand line option; %s') % + ((self.env.currprogram and + self.env.currprogram + ' ' or ''), sig), + targetname, targetname)) + self.env.note_progoption(name, targetname) + + +class GenericDesc(DescDirective): + """ + A generic x-ref directive registered with Sphinx.add_description_unit(). + """ + + def parse_signature(self, sig, signode): + parse_node = additional_xref_types[self.desctype][2] + if parse_node: + name = parse_node(self.env, sig, signode) + else: signode.clear() signode += addnodes.desc_name(sig, sig) - continue # we don't want an index entry here - # only add target and index entry if this is the first description of the - # function name in this desc block - if not noindex and name not in names: - fullname = (module and module + '.' or '') + name - # note target - if fullname not in state.document.ids: - signode['names'].append(fullname) - signode['ids'].append(fullname) - signode['first'] = (not names) - state.document.note_explicit_target(signode) - env.note_descref(fullname, desctype, lineno) - names.append(name) + # normalize whitespace like xfileref_role does + name = ws_re.sub('', sig) + return name - indextext = desc_index_text(desctype, module, name, - env.config.add_module_names) - inode['entries'].append(('single', indextext, fullname, fullname)) + def add_target_and_index(self, name, sig, signode): + rolename, indextemplate = additional_xref_types[self.desctype][:2] + targetname = '%s-%s' % (rolename, name) + signode['ids'].append(targetname) + self.state.document.note_explicit_target(signode) + if indextemplate: + indexentry = _(indextemplate) % (name,) + indextype = 'single' + colon = indexentry.find(':') + if colon != -1: + indextype = indexentry[:colon].strip() + indexentry = indexentry[colon+1:].strip() + self.indexnode['entries'].append((indextype, indexentry, + targetname, targetname)) + self.env.note_reftarget(rolename, name, targetname) - subnode = addnodes.desc_content() - # needed for automatic qualification of members - clsname_set = False - if desctype in ('class', 'exception') and names: - env.currclass = names[0] - clsname_set = True - elif desctype in ('method', 'staticmethod', 'attribute') and \ - clsname and not env.currclass: - env.currclass = clsname.strip('.') - clsname_set = True - # needed for association of version{added,changed} directives - if names: - env.currdesc = names[0] - state.nested_parse(content, content_offset, subnode) - handle_doc_fields(subnode) - if clsname_set: - env.currclass = None - env.currdesc = None - node.append(subnode) - return [inode, node] -desc_directive.content = 1 -desc_directive.arguments = (1, 0, 1) -desc_directive.options = {'noindex': directives.flag, - 'module': directives.unchanged} +class Target(Directive): + """ + Generic target for user-defined cross-reference types. + """ -desctypes = [ - # the Python ones - 'function', - 'data', - 'class', - 'method', - 'staticmethod', - 'attribute', - 'exception', - # the C ones - 'cfunction', - 'cmember', - 'cmacro', - 'ctype', - 'cvar', - # for command line options - 'cmdoption', - # the generic one - 'describe', - 'envvar', -] + has_content = False + required_arguments = 1 + optional_arguments = 0 + final_argument_whitespace = True + option_spec = {} -for _name in desctypes: - directives.register_directive(_name, desc_directive) + def run(self): + env = self.state.document.settings.env + rolename, indextemplate, foo = additional_xref_types[self.name] + # normalize whitespace in fullname like xfileref_role does + fullname = ws_re.sub('', self.arguments[0].strip()) + targetname = '%s-%s' % (rolename, fullname) + node = nodes.target('', '', ids=[targetname]) + self.state.document.note_explicit_target(node) + ret = [node] + if indextemplate: + indexentry = indextemplate % (fullname,) + indextype = 'single' + colon = indexentry.find(':') + if colon != -1: + indextype = indexentry[:colon].strip() + indexentry = indexentry[colon+1:].strip() + inode = addnodes.index(entries=[(indextype, indexentry, + targetname, targetname)]) + ret.insert(0, inode) + env.note_reftarget(rolename, fullname, targetname) + return ret + +# Note: the target directive is not registered here, it is used by the +# application when registering additional xref types. _ = lambda x: x # Generic cross-reference types; they can be registered in the application; -# the directives are either desc_directive or target_directive +# the directives are either desc_directive or target_directive. additional_xref_types = { # directive name: (role name, index text, function to parse the desc node) 'envvar': ('envvar', _('environment variable; %s'), None), @@ -524,33 +748,22 @@ additional_xref_types = { del _ -# ------ target -------------------------------------------------------------------- +directives.register_directive('describe', directive_dwim(DescDirective)) -def target_directive(targettype, arguments, options, content, lineno, - content_offset, block_text, state, state_machine): - """Generic target for user-defined cross-reference types.""" - env = state.document.settings.env - rolename, indextemplate, foo = additional_xref_types[targettype] - # normalize whitespace in fullname like xfileref_role does - fullname = ws_re.sub('', arguments[0].strip()) - targetname = '%s-%s' % (rolename, fullname) - node = nodes.target('', '', ids=[targetname]) - state.document.note_explicit_target(node) - ret = [node] - if indextemplate: - indexentry = indextemplate % (fullname,) - indextype = 'single' - colon = indexentry.find(':') - if colon != -1: - indextype = indexentry[:colon].strip() - indexentry = indexentry[colon+1:].strip() - inode = addnodes.index(entries=[(indextype, indexentry, targetname, targetname)]) - ret.insert(0, inode) - env.note_reftarget(rolename, fullname, targetname) - return ret +directives.register_directive('function', directive_dwim(ModulelevelDesc)) +directives.register_directive('data', directive_dwim(ModulelevelDesc)) +directives.register_directive('class', directive_dwim(ClasslikeDesc)) +directives.register_directive('exception', directive_dwim(ClasslikeDesc)) +directives.register_directive('method', directive_dwim(ClassmemberDesc)) +directives.register_directive('classmethod', directive_dwim(ClassmemberDesc)) +directives.register_directive('staticmethod', directive_dwim(ClassmemberDesc)) +directives.register_directive('attribute', directive_dwim(ClassmemberDesc)) -target_directive.content = 0 -target_directive.arguments = (1, 0, 1) +directives.register_directive('cfunction', directive_dwim(CDesc)) +directives.register_directive('cmember', directive_dwim(CDesc)) +directives.register_directive('cmacro', directive_dwim(CDesc)) +directives.register_directive('ctype', directive_dwim(CDesc)) +directives.register_directive('cvar', directive_dwim(CDesc)) -# note, the target directive is not registered here, it is used by the application -# when registering additional xref types +directives.register_directive('cmdoption', directive_dwim(CmdoptionDesc)) +directives.register_directive('envvar', directive_dwim(GenericDesc)) diff --git a/sphinx/directives/other.py b/sphinx/directives/other.py index 2e64eb0cf..bc9a54dff 100644 --- a/sphinx/directives/other.py +++ b/sphinx/directives/other.py @@ -3,248 +3,329 @@ sphinx.directives.other ~~~~~~~~~~~~~~~~~~~~~~~ - :copyright: 2007-2008 by Georg Brandl. - :license: BSD. + :copyright: Copyright 2007-2009 by the Sphinx team, see AUTHORS. + :license: BSD, see LICENSE for details. """ import re -import posixpath from docutils import nodes from docutils.parsers.rst import directives from sphinx import addnodes -from sphinx.util import patfilter -from sphinx.roles import caption_ref_re from sphinx.locale import pairindextypes -from sphinx.util.compat import make_admonition +from sphinx.util import patfilter, ws_re, caption_ref_re, url_re, docname_join +from sphinx.util.compat import Directive, directive_dwim, make_admonition -# ------ the TOC tree --------------------------------------------------------------- +class TocTree(Directive): + """ + Directive to notify Sphinx about the hierarchical structure of the docs, + and to include a table-of-contents like tree in the current document. + """ -def toctree_directive(name, arguments, options, content, lineno, - content_offset, block_text, state, state_machine): - env = state.document.settings.env - suffix = env.config.source_suffix - dirname = posixpath.dirname(env.docname) - glob = 'glob' in options + has_content = True + required_arguments = 0 + optional_arguments = 0 + final_argument_whitespace = False + option_spec = { + 'maxdepth': int, + 'glob': directives.flag, + 'hidden': directives.flag, + 'numbered': directives.flag, + } - ret = [] - subnode = addnodes.toctree() - includefiles = [] - includetitles = {} - all_docnames = env.found_docs.copy() - # don't add the currently visited file in catch-all patterns - all_docnames.remove(env.docname) - for entry in content: - if not entry: - continue - if not glob: - # look for explicit titles and documents ("Some Title <document>"). - m = caption_ref_re.match(entry) - if m: - docname = m.group(2) - includetitles[docname] = m.group(1) + def run(self): + env = self.state.document.settings.env + suffix = env.config.source_suffix + glob = 'glob' in self.options + + ret = [] + # (title, ref) pairs, where ref may be a document, or an external link, + # and title may be None if the document's title is to be used + entries = [] + includefiles = [] + includetitles = {} + all_docnames = env.found_docs.copy() + # don't add the currently visited file in catch-all patterns + all_docnames.remove(env.docname) + for entry in self.content: + if not entry: + continue + if not glob: + # look for explicit titles ("Some Title <document>") + m = caption_ref_re.match(entry) + if m: + ref = m.group(2) + title = m.group(1) + docname = ref + else: + ref = docname = entry + title = None + # remove suffixes (backwards compatibility) + if docname.endswith(suffix): + docname = docname[:-len(suffix)] + # absolutize filenames + docname = docname_join(env.docname, docname) + if url_re.match(ref) or ref == 'self': + entries.append((title, ref)) + elif docname not in env.found_docs: + ret.append(self.state.document.reporter.warning( + 'toctree references unknown document %r' % docname, + line=self.lineno)) + else: + entries.append((title, docname)) + includefiles.append(docname) else: - docname = entry - # remove suffixes (backwards compatibility) - if docname.endswith(suffix): - docname = docname[:-len(suffix)] - # absolutize filenames - docname = posixpath.normpath(posixpath.join(dirname, docname)) - if docname not in env.found_docs: - ret.append(state.document.reporter.warning( - 'toctree references unknown document %r' % docname, line=lineno)) - else: - includefiles.append(docname) - else: - patname = posixpath.normpath(posixpath.join(dirname, entry)) - docnames = sorted(patfilter(all_docnames, patname)) - for docname in docnames: - all_docnames.remove(docname) # don't include it again - includefiles.append(docname) - if not docnames: - ret.append(state.document.reporter.warning( - 'toctree glob pattern %r didn\'t match any documents' % entry, - line=lineno)) - subnode['includefiles'] = includefiles - subnode['includetitles'] = includetitles - subnode['maxdepth'] = options.get('maxdepth', -1) - subnode['glob'] = glob - ret.append(subnode) - return ret - -toctree_directive.content = 1 -toctree_directive.options = {'maxdepth': int, 'glob': directives.flag} -directives.register_directive('toctree', toctree_directive) + patname = docname_join(env.docname, entry) + docnames = sorted(patfilter(all_docnames, patname)) + for docname in docnames: + all_docnames.remove(docname) # don't include it again + entries.append((None, docname)) + includefiles.append(docname) + if not docnames: + ret.append(self.state.document.reporter.warning( + 'toctree glob pattern %r didn\'t match any documents' + % entry, line=self.lineno)) + subnode = addnodes.toctree() + subnode['parent'] = env.docname + # entries contains all entries (self references, external links etc.) + subnode['entries'] = entries + # includefiles only entries that are documents + subnode['includefiles'] = includefiles + subnode['maxdepth'] = self.options.get('maxdepth', -1) + subnode['glob'] = glob + subnode['hidden'] = 'hidden' in self.options + subnode['numbered'] = 'numbered' in self.options + ret.append(subnode) + return ret -# ------ section metadata ---------------------------------------------------------- +class Module(Directive): + """ + Directive to mark description of a new module. + """ -def module_directive(name, arguments, options, content, lineno, - content_offset, block_text, state, state_machine): - env = state.document.settings.env - modname = arguments[0].strip() - noindex = 'noindex' in options - env.currmodule = modname - env.note_module(modname, options.get('synopsis', ''), - options.get('platform', ''), - 'deprecated' in options) - modulenode = addnodes.module() - modulenode['modname'] = modname - modulenode['synopsis'] = options.get('synopsis', '') - targetnode = nodes.target('', '', ids=['module-' + modname]) - state.document.note_explicit_target(targetnode) - ret = [modulenode, targetnode] - if 'platform' in options: - modulenode['platform'] = options['platform'] - node = nodes.paragraph() - node += nodes.emphasis('', _('Platforms: ')) - node += nodes.Text(options['platform'], options['platform']) - ret.append(node) - # the synopsis isn't printed; in fact, it is only used in the modindex currently - if not noindex: - indextext = _('%s (module)') % modname - inode = addnodes.index(entries=[('single', indextext, - 'module-' + modname, modname)]) - ret.insert(0, inode) - return ret + has_content = False + required_arguments = 1 + optional_arguments = 0 + final_argument_whitespace = False + option_spec = { + 'platform': lambda x: x, + 'synopsis': lambda x: x, + 'noindex': directives.flag, + 'deprecated': directives.flag, + } -module_directive.arguments = (1, 0, 0) -module_directive.options = {'platform': lambda x: x, - 'synopsis': lambda x: x, - 'noindex': directives.flag, - 'deprecated': directives.flag} -directives.register_directive('module', module_directive) - - -def currentmodule_directive(name, arguments, options, content, lineno, - content_offset, block_text, state, state_machine): - # This directive is just to tell people that we're documenting - # stuff in module foo, but links to module foo won't lead here. - env = state.document.settings.env - modname = arguments[0].strip() - if modname == 'None': - env.currmodule = None - else: + def run(self): + env = self.state.document.settings.env + modname = self.arguments[0].strip() + noindex = 'noindex' in self.options env.currmodule = modname - return [] - -currentmodule_directive.arguments = (1, 0, 0) -directives.register_directive('currentmodule', currentmodule_directive) + env.note_module(modname, self.options.get('synopsis', ''), + self.options.get('platform', ''), + 'deprecated' in self.options) + modulenode = addnodes.module() + modulenode['modname'] = modname + modulenode['synopsis'] = self.options.get('synopsis', '') + targetnode = nodes.target('', '', ids=['module-' + modname], ismod=True) + self.state.document.note_explicit_target(targetnode) + ret = [modulenode, targetnode] + if 'platform' in self.options: + platform = self.options['platform'] + modulenode['platform'] = platform + node = nodes.paragraph() + node += nodes.emphasis('', _('Platforms: ')) + node += nodes.Text(platform, platform) + ret.append(node) + # the synopsis isn't printed; in fact, it is only used in the + # modindex currently + if not noindex: + indextext = _('%s (module)') % modname + inode = addnodes.index(entries=[('single', indextext, + 'module-' + modname, modname)]) + ret.insert(0, inode) + return ret -def author_directive(name, arguments, options, content, lineno, - content_offset, block_text, state, state_machine): - # Show authors only if the show_authors option is on - env = state.document.settings.env - if not env.config.show_authors: - return [] - para = nodes.paragraph() - emph = nodes.emphasis() - para += emph - if name == 'sectionauthor': - text = _('Section author: ') - elif name == 'moduleauthor': - text = _('Module author: ') - else: - text = _('Author: ') - emph += nodes.Text(text, text) - inodes, messages = state.inline_text(arguments[0], lineno) - emph.extend(inodes) - return [para] + messages +class CurrentModule(Directive): + """ + This directive is just to tell Sphinx that we're documenting + stuff in module foo, but links to module foo won't lead here. + """ -author_directive.arguments = (1, 0, 1) -directives.register_directive('sectionauthor', author_directive) -directives.register_directive('moduleauthor', author_directive) + has_content = False + required_arguments = 1 + optional_arguments = 0 + final_argument_whitespace = False + option_spec = {} - -# ------ index markup -------------------------------------------------------------- - -indextypes = [ - 'single', 'pair', 'triple', -] - -def index_directive(name, arguments, options, content, lineno, - content_offset, block_text, state, state_machine): - arguments = arguments[0].split('\n') - env = state.document.settings.env - targetid = 'index-%s' % env.index_num - env.index_num += 1 - targetnode = nodes.target('', '', ids=[targetid]) - state.document.note_explicit_target(targetnode) - indexnode = addnodes.index() - indexnode['entries'] = ne = [] - for entry in arguments: - entry = entry.strip() - for type in pairindextypes: - if entry.startswith(type+':'): - value = entry[len(type)+1:].strip() - value = pairindextypes[type] + '; ' + value - ne.append(('pair', value, targetid, value)) - break + def run(self): + env = self.state.document.settings.env + modname = self.arguments[0].strip() + if modname == 'None': + env.currmodule = None else: - for type in indextypes: + env.currmodule = modname + return [] + + +class Author(Directive): + """ + Directive to give the name of the author of the current document + or section. Shown in the output only if the show_authors option is on. + """ + + has_content = False + required_arguments = 1 + optional_arguments = 0 + final_argument_whitespace = True + option_spec = {} + + def run(self): + env = self.state.document.settings.env + if not env.config.show_authors: + return [] + para = nodes.paragraph() + emph = nodes.emphasis() + para += emph + if self.name == 'sectionauthor': + text = _('Section author: ') + elif self.name == 'moduleauthor': + text = _('Module author: ') + else: + text = _('Author: ') + emph += nodes.Text(text, text) + inodes, messages = self.state.inline_text(self.arguments[0], + self.lineno) + emph.extend(inodes) + return [para] + messages + + +class Program(Directive): + """ + Directive to name the program for which options are documented. + """ + + has_content = False + required_arguments = 1 + optional_arguments = 0 + final_argument_whitespace = True + option_spec = {} + + def run(self): + env = self.state.document.settings.env + program = ws_re.sub('-', self.arguments[0].strip()) + if program == 'None': + env.currprogram = None + else: + env.currprogram = program + return [] + + +class Index(Directive): + """ + Directive to add entries to the index. + """ + + has_content = False + required_arguments = 1 + optional_arguments = 0 + final_argument_whitespace = True + option_spec = {} + + indextypes = [ + 'single', 'pair', 'triple', + ] + + def run(self): + arguments = self.arguments[0].split('\n') + env = self.state.document.settings.env + targetid = 'index-%s' % env.index_num + env.index_num += 1 + targetnode = nodes.target('', '', ids=[targetid]) + self.state.document.note_explicit_target(targetnode) + indexnode = addnodes.index() + indexnode['entries'] = ne = [] + for entry in arguments: + entry = entry.strip() + for type in pairindextypes: if entry.startswith(type+':'): value = entry[len(type)+1:].strip() - ne.append((type, value, targetid, value)) + value = pairindextypes[type] + '; ' + value + ne.append(('pair', value, targetid, value)) break - # shorthand notation for single entries else: - for value in entry.split(','): - ne.append(('single', value.strip(), targetid, value.strip())) - return [indexnode, targetnode] - -index_directive.arguments = (1, 0, 1) -directives.register_directive('index', index_directive) - -# ------ versionadded/versionchanged ----------------------------------------------- - -def version_directive(name, arguments, options, content, lineno, - content_offset, block_text, state, state_machine): - node = addnodes.versionmodified() - node['type'] = name - node['version'] = arguments[0] - if len(arguments) == 2: - inodes, messages = state.inline_text(arguments[1], lineno+1) - node.extend(inodes) - if content: - state.nested_parse(content, content_offset, node) - ret = [node] + messages - else: - ret = [node] - env = state.document.settings.env - env.note_versionchange(node['type'], node['version'], node, lineno) - return ret - -version_directive.arguments = (1, 1, 1) -version_directive.content = 1 - -directives.register_directive('deprecated', version_directive) -directives.register_directive('versionadded', version_directive) -directives.register_directive('versionchanged', version_directive) + for type in self.indextypes: + if entry.startswith(type+':'): + value = entry[len(type)+1:].strip() + ne.append((type, value, targetid, value)) + break + # shorthand notation for single entries + else: + for value in entry.split(','): + value = value.strip() + if not value: + continue + ne.append(('single', value, targetid, value)) + return [indexnode, targetnode] -# ------ see also ------------------------------------------------------------------ +class VersionChange(Directive): + """ + Directive to describe a change/addition/deprecation in a specific version. + """ -def seealso_directive(name, arguments, options, content, lineno, - content_offset, block_text, state, state_machine): - seealsonode = make_admonition( - addnodes.seealso, name, [_('See also')], options, content, - lineno, content_offset, block_text, state, state_machine) - if arguments: - argnodes, msgs = state.inline_text(arguments[0], lineno) - para = nodes.paragraph() - para += argnodes - seealsonode[1:1] = [para] + msgs - return [seealsonode] + has_content = True + required_arguments = 1 + optional_arguments = 1 + final_argument_whitespace = True + option_spec = {} -seealso_directive.content = 1 -seealso_directive.arguments = (0, 1, 1) -directives.register_directive('seealso', seealso_directive) + def run(self): + node = addnodes.versionmodified() + node.document = self.state.document + node['type'] = self.name + node['version'] = self.arguments[0] + if len(self.arguments) == 2: + inodes, messages = self.state.inline_text(self.arguments[1], + self.lineno+1) + node.extend(inodes) + if self.content: + self.state.nested_parse(self.content, self.content_offset, node) + ret = [node] + messages + else: + ret = [node] + env = self.state.document.settings.env + env.note_versionchange(node['type'], node['version'], node, self.lineno) + return ret -# ------ production list (for the reference) --------------------------------------- +class SeeAlso(Directive): + """ + An admonition mentioning things to look at as reference. + """ + + has_content = True + required_arguments = 0 + optional_arguments = 1 + final_argument_whitespace = True + option_spec = {} + + def run(self): + ret = make_admonition( + addnodes.seealso, self.name, [_('See also')], self.options, + self.content, self.lineno, self.content_offset, self.block_text, + self.state, self.state_machine) + if self.arguments: + argnodes, msgs = self.state.inline_text(self.arguments[0], + self.lineno) + para = nodes.paragraph() + para += argnodes + para += msgs + ret[0].insert(1, para) + return ret + token_re = re.compile('`([a-z_]+)`') @@ -267,116 +348,223 @@ def token_xrefs(text, env): retnodes.append(nodes.Text(text[pos:], text[pos:])) return retnodes -def productionlist_directive(name, arguments, options, content, lineno, - content_offset, block_text, state, state_machine): - env = state.document.settings.env - node = addnodes.productionlist() - messages = [] - i = 0 +class ProductionList(Directive): + """ + Directive to list grammar productions. + """ - for rule in arguments[0].split('\n'): - if i == 0 and ':' not in rule: - # production group - continue - i += 1 - try: - name, tokens = rule.split(':', 1) - except ValueError: - break - subnode = addnodes.production() - subnode['tokenname'] = name.strip() - if subnode['tokenname']: - idname = 'grammar-token-%s' % subnode['tokenname'] - if idname not in state.document.ids: - subnode['ids'].append(idname) - state.document.note_implicit_target(subnode, subnode) - env.note_reftarget('token', subnode['tokenname'], idname) - subnode.extend(token_xrefs(tokens, env)) - node.append(subnode) - return [node] + messages + has_content = False + required_arguments = 1 + optional_arguments = 0 + final_argument_whitespace = True + option_spec = {} -productionlist_directive.content = 0 -productionlist_directive.arguments = (1, 0, 1) -directives.register_directive('productionlist', productionlist_directive) + def run(self): + env = self.state.document.settings.env + node = addnodes.productionlist() + messages = [] + i = 0 - -# ------ glossary directive --------------------------------------------------------- - -def glossary_directive(name, arguments, options, content, lineno, - content_offset, block_text, state, state_machine): - """Glossary with cross-reference targets for :term: roles.""" - env = state.document.settings.env - node = addnodes.glossary() - state.nested_parse(content, content_offset, node) - - # the content should be definition lists - dls = [child for child in node if isinstance(child, nodes.definition_list)] - # now, extract definition terms to enable cross-reference creation - for dl in dls: - dl['classes'].append('glossary') - for li in dl.children: - if not li.children or not isinstance(li[0], nodes.term): + for rule in self.arguments[0].split('\n'): + if i == 0 and ':' not in rule: + # production group continue - termtext = li.children[0].astext() - new_id = 'term-' + nodes.make_id(termtext) - if new_id in env.gloss_entries: - new_id = 'term-' + str(len(env.gloss_entries)) - env.gloss_entries.add(new_id) - li[0]['names'].append(new_id) - li[0]['ids'].append(new_id) - state.document.settings.env.note_reftarget('term', termtext.lower(), - new_id) - # add an index entry too - indexnode = addnodes.index() - indexnode['entries'] = [('single', termtext, new_id, termtext)] - li.insert(0, indexnode) - return [node] - -glossary_directive.content = 1 -glossary_directive.arguments = (0, 0, 0) -directives.register_directive('glossary', glossary_directive) + i += 1 + try: + name, tokens = rule.split(':', 1) + except ValueError: + break + subnode = addnodes.production() + subnode['tokenname'] = name.strip() + if subnode['tokenname']: + idname = 'grammar-token-%s' % subnode['tokenname'] + if idname not in self.state.document.ids: + subnode['ids'].append(idname) + self.state.document.note_implicit_target(subnode, subnode) + env.note_reftarget('token', subnode['tokenname'], idname) + subnode.extend(token_xrefs(tokens, env)) + node.append(subnode) + return [node] + messages -# ------ miscellaneous markup ------------------------------------------------------- +class TabularColumns(Directive): + """ + Directive to give an explicit tabulary column definition to LaTeX. + """ -def centered_directive(name, arguments, options, content, lineno, - content_offset, block_text, state, state_machine): - if not arguments: - return [] - subnode = addnodes.centered() - inodes, messages = state.inline_text(arguments[0], lineno) - subnode.extend(inodes) - return [subnode] + messages + has_content = False + required_arguments = 1 + optional_arguments = 0 + final_argument_whitespace = True + option_spec = {} -centered_directive.arguments = (1, 0, 1) -directives.register_directive('centered', centered_directive) + def run(self): + node = addnodes.tabular_col_spec() + node['spec'] = self.arguments[0] + return [node] -def acks_directive(name, arguments, options, content, lineno, - content_offset, block_text, state, state_machine): - node = addnodes.acks() - state.nested_parse(content, content_offset, node) - if len(node.children) != 1 or not isinstance(node.children[0], nodes.bullet_list): - return [state.document.reporter.warning('.. acks content is not a list', - line=lineno)] - return [node] +class Glossary(Directive): + """ + Directive to create a glossary with cross-reference targets + for :term: roles. + """ -acks_directive.content = 1 -acks_directive.arguments = (0, 0, 0) -directives.register_directive('acks', acks_directive) + has_content = True + required_arguments = 0 + optional_arguments = 0 + final_argument_whitespace = False + option_spec = {} + + def run(self): + env = self.state.document.settings.env + node = addnodes.glossary() + node.document = self.state.document + self.state.nested_parse(self.content, self.content_offset, node) + + # the content should be definition lists + dls = [child for child in node + if isinstance(child, nodes.definition_list)] + # now, extract definition terms to enable cross-reference creation + for dl in dls: + dl['classes'].append('glossary') + for li in dl.children: + if not li.children or not isinstance(li[0], nodes.term): + continue + termtext = li.children[0].astext() + new_id = 'term-' + nodes.make_id(termtext) + if new_id in env.gloss_entries: + new_id = 'term-' + str(len(env.gloss_entries)) + env.gloss_entries.add(new_id) + li[0]['names'].append(new_id) + li[0]['ids'].append(new_id) + env.note_reftarget('term', termtext.lower(), new_id) + # add an index entry too + indexnode = addnodes.index() + indexnode['entries'] = [('single', termtext, new_id, termtext)] + li.insert(0, indexnode) + return [node] -def tabularcolumns_directive(name, arguments, options, content, lineno, - content_offset, block_text, state, state_machine): - # support giving explicit tabulary column definition to latex - node = addnodes.tabular_col_spec() - node['spec'] = arguments[0] - return [node] +class Centered(Directive): + """ + Directive to create a centered line of bold text. + """ -tabularcolumns_directive.content = 0 -tabularcolumns_directive.arguments = (1, 0, 1) -directives.register_directive('tabularcolumns', tabularcolumns_directive) + has_content = False + required_arguments = 1 + optional_arguments = 0 + final_argument_whitespace = True + option_spec = {} + def run(self): + if not self.arguments: + return [] + subnode = addnodes.centered() + inodes, messages = self.state.inline_text(self.arguments[0], + self.lineno) + subnode.extend(inodes) + return [subnode] + messages + + + +class Acks(Directive): + """ + Directive for a list of names. + """ + + has_content = True + required_arguments = 0 + optional_arguments = 0 + final_argument_whitespace = False + option_spec = {} + + def run(self): + node = addnodes.acks() + node.document = self.state.document + self.state.nested_parse(self.content, self.content_offset, node) + if len(node.children) != 1 or not isinstance(node.children[0], + nodes.bullet_list): + return [self.state.document.reporter.warning( + '.. acks content is not a list', line=self.lineno)] + return [node] + + +class HList(Directive): + """ + Directive for a list that gets compacted horizontally. + """ + + has_content = True + required_arguments = 0 + optional_arguments = 0 + final_argument_whitespace = False + option_spec = { + 'columns': int, + } + + def run(self): + ncolumns = self.options.get('columns', 2) + node = nodes.paragraph() + node.document = self.state.document + self.state.nested_parse(self.content, self.content_offset, node) + if len(node.children) != 1 or not isinstance(node.children[0], + nodes.bullet_list): + return [self.state.document.reporter.warning( + '.. hlist content is not a list', line=self.lineno)] + fulllist = node.children[0] + # create a hlist node where the items are distributed + npercol, nmore = divmod(len(fulllist), ncolumns) + index = 0 + newnode = addnodes.hlist() + for column in range(ncolumns): + endindex = index + (column < nmore and (npercol+1) or npercol) + col = addnodes.hlistcol() + col += nodes.bullet_list() + col[0] += fulllist.children[index:endindex] + index = endindex + newnode += col + return [newnode] + + +class Only(Directive): + """ + Directive to only include text if the given tag(s) are enabled. + """ + + has_content = True + required_arguments = 1 + optional_arguments = 0 + final_argument_whitespace = True + option_spec = {} + + def run(self): + node = addnodes.only() + node.document = self.state.document + node.line = self.lineno + node['expr'] = self.arguments[0] + self.state.nested_parse(self.content, self.content_offset, node) + return [node] + + +directives.register_directive('toctree', directive_dwim(TocTree)) +directives.register_directive('module', directive_dwim(Module)) +directives.register_directive('currentmodule', directive_dwim(CurrentModule)) +directives.register_directive('sectionauthor', directive_dwim(Author)) +directives.register_directive('moduleauthor', directive_dwim(Author)) +directives.register_directive('program', directive_dwim(Program)) +directives.register_directive('index', directive_dwim(Index)) +directives.register_directive('deprecated', directive_dwim(VersionChange)) +directives.register_directive('versionadded', directive_dwim(VersionChange)) +directives.register_directive('versionchanged', directive_dwim(VersionChange)) +directives.register_directive('seealso', directive_dwim(SeeAlso)) +directives.register_directive('productionlist', directive_dwim(ProductionList)) +directives.register_directive('tabularcolumns', directive_dwim(TabularColumns)) +directives.register_directive('glossary', directive_dwim(Glossary)) +directives.register_directive('centered', directive_dwim(Centered)) +directives.register_directive('acks', directive_dwim(Acks)) +directives.register_directive('hlist', directive_dwim(HList)) +directives.register_directive('only', directive_dwim(Only)) # register the standard rst class directive under a different name diff --git a/sphinx/environment.py b/sphinx/environment.py index 3b7eb91e1..0884eccad 100644 --- a/sphinx/environment.py +++ b/sphinx/environment.py @@ -5,8 +5,8 @@ Global creation environment. - :copyright: 2007-2008 by Georg Brandl. - :license: BSD. + :copyright: Copyright 2007-2009 by the Sphinx team, see AUTHORS. + :license: BSD, see LICENSE for details. """ import re @@ -14,25 +14,25 @@ import os import time import heapq import types +import codecs import imghdr +import string import difflib import cPickle as pickle from os import path from glob import glob -from string import uppercase +from string import ascii_uppercase as uppercase from itertools import izip, groupby try: - import hashlib - md5 = hashlib.md5 + from hashlib import md5 except ImportError: # 2.4 compatibility - import md5 - md5 = md5.new + from md5 import md5 from docutils import nodes from docutils.io import FileInput, NullOutput from docutils.core import Publisher -from docutils.utils import Reporter +from docutils.utils import Reporter, relative_path from docutils.readers import standalone from docutils.parsers.rst import roles from docutils.parsers.rst.languages import en as english @@ -42,14 +42,16 @@ from docutils.transforms import Transform from docutils.transforms.parts import ContentsFilter from sphinx import addnodes -from sphinx.util import get_matching_docs, SEP +from sphinx.util import movefile, get_matching_docs, SEP, ustrftime, \ + docname_join, FilenameUniqDict, url_re +from sphinx.errors import SphinxError from sphinx.directives import additional_xref_types default_settings = { 'embed_stylesheet': False, 'cloak_email_addresses': True, 'pep_base_url': 'http://www.python.org/dev/peps/', - 'rfc_base_url': 'http://rfc.net/', + 'rfc_base_url': 'http://tools.ietf.org/html/', 'input_encoding': 'utf-8', 'doctitle_xform': False, 'sectsubtitle_xform': False, @@ -57,7 +59,7 @@ default_settings = { # This is increased every time an environment attribute is added # or changed to properly invalidate pickle files. -ENV_VERSION = 25 +ENV_VERSION = 29 default_substitutions = set([ @@ -69,12 +71,12 @@ default_substitutions = set([ dummy_reporter = Reporter('', 4, 4) -class RedirStream(object): - def __init__(self, writefunc): - self.writefunc = writefunc +class WarningStream(object): + def __init__(self, warnfunc): + self.warnfunc = warnfunc def write(self, text): if text.strip(): - self.writefunc(text) + self.warnfunc(text, None, '') class NoUri(Exception): @@ -99,7 +101,7 @@ class DefaultSubstitutions(Transform): text = config[refname] if refname == 'today' and not text: # special handling: can also specify a strftime format - text = time.strftime(config.today_fmt or _('%B %d, %Y')) + text = ustrftime(config.today_fmt or _('%B %d, %Y')) ref.replace_self(nodes.Text(text, text)) @@ -114,7 +116,8 @@ class MoveModuleTargets(Transform): if not node['ids']: continue if node['ids'][0].startswith('module-') and \ - node.parent.__class__ is nodes.section: + node.parent.__class__ is nodes.section and \ + node.has_key('ismod'): node.parent['ids'] = node['ids'] node.parent.remove(node) @@ -131,6 +134,19 @@ class HandleCodeBlocks(Transform): nodes.doctest_block): node.replace_self(node.children[0]) + +class SortIds(Transform): + """ + Sort secion IDs so that the "id[0-9]+" one comes last. + """ + default_priority = 261 + + def apply(self): + for node in self.document.traverse(nodes.section): + if len(node['ids']) > 1 and node['ids'][0].startswith('id'): + node['ids'] = node['ids'][1:] + [node['ids'][0]] + + class CitationReferences(Transform): """ Handle citation references before the default docutils transform does. @@ -151,7 +167,7 @@ class SphinxStandaloneReader(standalone.Reader): Add our own transforms. """ transforms = [CitationReferences, DefaultSubstitutions, MoveModuleTargets, - HandleCodeBlocks] + HandleCodeBlocks, SortIds] def get_transforms(self): return standalone.Reader.get_transforms(self) + self.transforms @@ -164,14 +180,14 @@ class SphinxDummyWriter(UnfilteredWriter): pass - class SphinxContentsFilter(ContentsFilter): """ Used with BuildEnvironment.add_toc_from() to discard cross-file links within table-of-contents link nodes. """ def visit_pending_xref(self, node): - self.parent.append(nodes.literal(node['reftarget'], node['reftarget'])) + text = node.astext() + self.parent.append(nodes.literal(text, text)) raise nodes.SkipNode @@ -202,7 +218,9 @@ class BuildEnvironment: self.set_warnfunc(None) values = self.config.values del self.config.values - picklefile = open(filename, 'wb') + # first write to a temporary file, so that if dumping fails, + # the existing environment won't be overwritten + picklefile = open(filename + '.tmp', 'wb') # remove potentially pickling-problematic values from config for key, val in vars(self.config).items(): if key.startswith('_') or \ @@ -214,6 +232,7 @@ class BuildEnvironment: pickle.dump(self, picklefile, pickle.HIGHEST_PROTOCOL) finally: picklefile.close() + movefile(filename + '.tmp', filename) # reset attributes self.config.values = values self.set_warnfunc(warnfunc) @@ -238,13 +257,14 @@ class BuildEnvironment: # this is to invalidate old pickles self.version = ENV_VERSION - # All "docnames" here are /-separated and relative and exclude the source suffix. + # All "docnames" here are /-separated and relative and exclude + # the source suffix. self.found_docs = set() # contains all existing docnames self.all_docs = {} # docname -> mtime at the time of build # contains all built docnames - self.dependencies = {} # docname -> set of dependent file names, relative to - # documentation root + self.dependencies = {} # docname -> set of dependent file + # names, relative to documentation root # File metadata self.metadata = {} # docname -> dict of metadata items @@ -253,53 +273,65 @@ class BuildEnvironment: self.titles = {} # docname -> title node self.tocs = {} # docname -> table of contents nodetree self.toc_num_entries = {} # docname -> number of real entries - # used to determine when to show the TOC in a sidebar - # (don't show if it's only one item) + # used to determine when to show the TOC + # in a sidebar (don't show if it's only one item) + self.toc_secnumbers = {} # docname -> dict of sectionid -> number + self.toctree_includes = {} # docname -> list of toctree includefiles - self.files_to_rebuild = {} # docname -> set of files (containing its TOCs) - # to rebuild too + self.files_to_rebuild = {} # docname -> set of files + # (containing its TOCs) to rebuild too self.glob_toctrees = set() # docnames that have :glob: toctrees + self.numbered_toctrees = set() # docnames that have :numbered: toctrees # X-ref target inventory self.descrefs = {} # fullname -> docname, desctype self.filemodules = {} # docname -> [modules] - self.modules = {} # modname -> docname, synopsis, platform, deprecated + self.modules = {} # modname -> docname, synopsis, + # platform, deprecated self.labels = {} # labelname -> docname, labelid, sectionname self.anonlabels = {} # labelname -> docname, labelid + self.progoptions = {} # (program, name) -> docname, labelid self.reftargets = {} # (type, name) -> docname, labelid - # where type is term, token, option, envvar, citation + # type: term, token, envvar, citation # Other inventories self.indexentries = {} # docname -> list of # (type, string, target, aliasname) - self.versionchanges = {} # version -> list of - # (type, docname, lineno, module, descname, content) - self.images = {} # absolute path -> (docnames, unique filename) + self.versionchanges = {} # version -> list of (type, docname, + # lineno, module, descname, content) + + # these map absolute path -> (docnames, unique filename) + self.images = FilenameUniqDict() + self.dlfiles = FilenameUniqDict() # These are set while parsing a file self.docname = None # current document name self.currmodule = None # current module name self.currclass = None # current class name self.currdesc = None # current descref name + self.currprogram = None # current program name self.index_num = 0 # autonumber for index targets self.gloss_entries = set() # existing definition labels # Some magically present labels - self.labels['genindex'] = ('genindex', '', _('Index')) - self.labels['modindex'] = ('modindex', '', _('Module Index')) - self.labels['search'] = ('search', '', _('Search Page')) + def add_magic_label(name, description): + self.labels[name] = (name, '', description) + self.anonlabels[name] = (name, '') + add_magic_label('genindex', _('Index')) + add_magic_label('modindex', _('Module Index')) + add_magic_label('search', _('Search Page')) def set_warnfunc(self, func): self._warnfunc = func - self.settings['warning_stream'] = RedirStream(func) + self.settings['warning_stream'] = WarningStream(func) def warn(self, docname, msg, lineno=None): if docname: if lineno is None: lineno = '' - self._warnfunc('%s:%s: %s' % (self.doc2path(docname), lineno, msg)) + self._warnfunc(msg, '%s:%s' % (self.doc2path(docname), lineno)) else: - self._warnfunc('GLOBAL:: ' + msg) + self._warnfunc(msg) def clear_doc(self, docname): """Remove all traces of a source file in the inventory.""" @@ -309,11 +341,15 @@ class BuildEnvironment: self.dependencies.pop(docname, None) self.titles.pop(docname, None) self.tocs.pop(docname, None) + self.toc_secnumbers.pop(docname, None) self.toc_num_entries.pop(docname, None) self.toctree_includes.pop(docname, None) self.filemodules.pop(docname, None) self.indexentries.pop(docname, None) self.glob_toctrees.discard(docname) + self.numbered_toctrees.discard(docname) + self.images.purge_doc(docname) + self.dlfiles.purge_doc(docname) for subfn, fnset in self.files_to_rebuild.items(): fnset.discard(docname) @@ -331,13 +367,12 @@ class BuildEnvironment: for key, (fn, _) in self.reftargets.items(): if fn == docname: del self.reftargets[key] + for key, (fn, _) in self.progoptions.items(): + if fn == docname: + del self.progoptions[key] for version, changes in self.versionchanges.items(): new = [change for change in changes if change[1] != docname] changes[:] = new - for fullpath, (docs, _) in self.images.items(): - docs.discard(docname) - if not docs: - del self.images[fullpath] def doc2path(self, docname, base=True, suffix=None): """ @@ -349,7 +384,8 @@ class BuildEnvironment: """ suffix = suffix or self.config.source_suffix if base is True: - return path.join(self.srcdir, docname.replace(SEP, path.sep)) + suffix + return path.join(self.srcdir, + docname.replace(SEP, path.sep)) + suffix elif base is None: return docname.replace(SEP, path.sep) + suffix else: @@ -362,8 +398,10 @@ class BuildEnvironment: 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] 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, + 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)) def get_outdated_files(self, config_changed): @@ -415,18 +453,22 @@ class BuildEnvironment: return added, changed, removed def update(self, config, srcdir, doctreedir, app=None): - """(Re-)read all files new or changed since last update. Yields a summary - and then docnames as it processes them. Store all environment docnames - in the canonical format (ie using SEP as a separator in place of - os.path.sep).""" + """ + (Re-)read all files new or changed since last update. Returns a + summary, the total count of documents to reread and an iterator that + yields docnames as it processes them. Store all environment docnames in + the canonical format (ie using SEP as a separator in place of + os.path.sep). + """ config_changed = False if self.config is None: msg = '[new config] ' config_changed = True else: - # check if a config value was changed that affects how doctrees are read - for key, descr in config.config_values.iteritems(): - if not descr[1]: + # check if a config value was changed that affects how + # doctrees are read + for key, descr in config.values.iteritems(): + if descr[1] != 'env': continue if self.config[key] != config[key]: msg = '[config changed] ' @@ -443,6 +485,7 @@ class BuildEnvironment: self.srcdir = srcdir self.doctreedir = doctreedir self.find_files(config) + self.config = config added, changed, removed = self.get_outdated_files(config_changed) @@ -453,43 +496,63 @@ class BuildEnvironment: msg += '%s added, %s changed, %s removed' % (len(added), len(changed), len(removed)) - yield msg - self.config = config - self.app = app + def update_generator(): + self.app = app - # clear all files no longer present - for docname in removed: - self.clear_doc(docname) + # clear all files no longer present + for docname in removed: + if app: + app.emit('env-purge-doc', self, docname) + self.clear_doc(docname) - # read all new and changed files - for docname in sorted(added | changed): - yield docname - self.read_doc(docname, app=app) + # read all new and changed files + to_read = added | changed + for docname in sorted(to_read): + yield docname + self.read_doc(docname, app=app) - if config.master_doc not in self.all_docs: - self.warn(None, 'master file %s not found' % - self.doc2path(config.master_doc)) + if config.master_doc not in self.all_docs: + self.warn(None, 'master file %s not found' % + self.doc2path(config.master_doc)) - self.app = None + self.app = None + if app: + app.emit('env-updated', self) - # remove all non-existing images from inventory - for imgsrc in self.images.keys(): - if not os.access(path.join(self.srcdir, imgsrc), os.R_OK): - del self.images[imgsrc] - - if app: - app.emit('env-updated', self) + return msg, len(added | changed), update_generator() + def check_dependents(self, already): + to_rewrite = self.assign_section_numbers() + for docname in to_rewrite: + if docname not in already: + yield docname # --------- SINGLE FILE READING -------------------------------------------- + def warn_and_replace(self, error): + """ + Custom decoding error handler that warns and replaces. + """ + linestart = error.object.rfind('\n', None, error.start) + lineend = error.object.find('\n', error.start) + if lineend == -1: lineend = len(error.object) + lineno = error.object.count('\n', 0, error.start) + 1 + self.warn(self.docname, 'undecodable source characters, ' + 'replacing with "?": %r' % + (error.object[linestart+1:error.start] + '>>>' + + error.object[error.start:error.end] + '<<<' + + error.object[error.end:lineend]), lineno) + return (u'?', error.end) + def read_doc(self, docname, src_path=None, save_parsed=True, app=None): """ Parse a file and add/update inventory entries for the doctree. If srcpath is given, read from a different source file. """ # remove all inventory entries for that file + if app: + app.emit('env-purge-doc', self, docname) self.clear_doc(docname) if src_path is None: @@ -506,15 +569,27 @@ class BuildEnvironment: self.docname = docname self.settings['input_encoding'] = self.config.source_encoding + self.settings['trim_footnote_reference_space'] = \ + self.config.trim_footnote_reference_space + + codecs.register_error('sphinx', self.warn_and_replace) + + codecs.register_error('sphinx', self.warn_and_replace) class SphinxSourceClass(FileInput): - def read(self): - data = FileInput.read(self) + def decode(self_, data): + return data.decode(self_.encoding, 'sphinx') + + def read(self_): + data = FileInput.read(self_) if app: arg = [data] app.emit('source-read', docname, arg) data = arg[0] - return data + if self.config.rst_epilog: + return data + '\n' + self.config.rst_epilog + '\n' + else: + return data # publish manually pub = Publisher(reader=SphinxStandaloneReader(), @@ -529,11 +604,12 @@ class BuildEnvironment: pub.publish() doctree = pub.document except UnicodeError, err: - from sphinx.application import SphinxError - raise SphinxError(err.message) + import pdb; pdb.set_trace() + raise SphinxError(str(err)) self.filter_messages(doctree) self.process_dependencies(docname, doctree) self.process_images(docname, doctree) + self.process_downloads(docname, doctree) self.process_metadata(docname, doctree) self.create_title_from(docname, doctree) self.note_labels_from(docname, doctree) @@ -565,7 +641,8 @@ class BuildEnvironment: if save_parsed: # save the parsed doctree - doctree_filename = self.doc2path(docname, self.doctreedir, '.doctree') + doctree_filename = self.doc2path(docname, self.doctreedir, + '.doctree') dirname = path.dirname(doctree_filename) if not path.isdir(dirname): os.makedirs(dirname) @@ -590,19 +667,42 @@ class BuildEnvironment: """ Process docutils-generated dependency info. """ + cwd = os.getcwd() + frompath = path.join(path.normpath(self.srcdir), 'dummy') deps = doctree.settings.record_dependencies if not deps: return - docdir = path.dirname(self.doc2path(docname, base=None)) for dep in deps.list: - dep = path.join(docdir, dep) - self.dependencies.setdefault(docname, set()).add(dep) + # the dependency path is relative to the working dir, so get + # one relative to the srcdir + relpath = relative_path(frompath, + path.normpath(path.join(cwd, dep))) + self.dependencies.setdefault(docname, set()).add(relpath) + + def process_downloads(self, docname, doctree): + """ + Process downloadable file paths. + """ + docdir = path.dirname(self.doc2path(docname, base=None)) + for node in doctree.traverse(addnodes.download_reference): + targetname = node['reftarget'] + if targetname.startswith('/') or targetname.startswith(os.sep): + # absolute + filepath = targetname[1:] + else: + filepath = path.normpath(path.join(docdir, node['reftarget'])) + self.dependencies.setdefault(docname, set()).add(filepath) + if not os.access(path.join(self.srcdir, filepath), os.R_OK): + self.warn(docname, 'download file not readable: %s' % filepath, + getattr(node, 'line', None)) + continue + uniquename = self.dlfiles.add_file(docname, filepath) + node['filename'] = uniquename def process_images(self, docname, doctree): """ Process and rewrite image URIs. """ - existing_names = set(v[1] for v in self.images.itervalues()) docdir = path.dirname(self.doc2path(docname, base=None)) for node in doctree.traverse(nodes.image): # Map the mimetype to the corresponding image. The writer may @@ -612,44 +712,48 @@ class BuildEnvironment: node['candidates'] = candidates = {} imguri = node['uri'] if imguri.find('://') != -1: - self.warn(docname, 'Nonlocal image URI found: %s' % imguri, node.line) + self.warn(docname, 'nonlocal image URI found: %s' % imguri, + node.line) candidates['?'] = imguri continue - imgpath = path.normpath(path.join(docdir, imguri)) + # imgpath is the image path *from srcdir* + if imguri.startswith('/') or imguri.startswith(os.sep): + # absolute path (= relative to srcdir) + imgpath = path.normpath(imguri[1:]) + else: + imgpath = path.normpath(path.join(docdir, imguri)) + # set imgpath as default URI node['uri'] = imgpath if imgpath.endswith(os.extsep + '*'): for filename in glob(path.join(self.srcdir, imgpath)): - dir, base = path.split(filename) - if base.lower().endswith('.pdf'): - candidates['application/pdf'] = path.join(docdir, base) - elif base.lower().endswith('.svg'): - candidates['image/svg+xml'] = path.join(docdir, base) + new_imgpath = relative_path(self.srcdir, filename) + if filename.lower().endswith('.pdf'): + candidates['application/pdf'] = new_imgpath + elif filename.lower().endswith('.svg'): + candidates['image/svg+xml'] = new_imgpath else: - f = open(filename, 'rb') try: - imgtype = imghdr.what(f) - finally: - f.close() + f = open(filename, 'rb') + try: + imgtype = imghdr.what(f) + finally: + f.close() + except (OSError, IOError): + self.warn(docname, + 'image file %s not readable' % filename) if imgtype: - candidates['image/' + imgtype] = path.join(docdir, base) + candidates['image/' + imgtype] = new_imgpath else: candidates['*'] = imgpath + # map image paths to unique image names (so that they can be put + # into a single directory) for imgpath in candidates.itervalues(): self.dependencies.setdefault(docname, set()).add(imgpath) if not os.access(path.join(self.srcdir, imgpath), os.R_OK): - self.warn(docname, 'Image file not readable: %s' % imgpath, + self.warn(docname, 'image file not readable: %s' % imgpath, node.line) - if imgpath in self.images: - self.images[imgpath][0].add(docname) continue - uniquename = path.basename(imgpath) - base, ext = path.splitext(uniquename) - i = 0 - while uniquename in existing_names: - i += 1 - uniquename = '%s%s%s' % (base, i, ext) - self.images[imgpath] = (set([docname]), uniquename) - existing_names.add(uniquename) + self.images.add_file(docname, imgpath) def process_metadata(self, docname, doctree): """ @@ -701,7 +805,8 @@ class BuildEnvironment: continue if name in self.labels: self.warn(docname, 'duplicate label %s, ' % name + - 'other instance in %s' % self.doc2path(self.labels[name][0]), + 'other instance in ' + + self.doc2path(self.labels[name][0]), node.line) self.anonlabels[name] = docname, labelid if node.tagname == 'section': @@ -737,6 +842,8 @@ class BuildEnvironment: file relations from it.""" if toctreenode['glob']: self.glob_toctrees.add(docname) + if toctreenode.get('numbered'): + self.numbered_toctrees.add(docname) includefiles = toctreenode['includefiles'] for includefile in includefiles: # note that if the included file is rebuilt, this one must be @@ -753,20 +860,32 @@ class BuildEnvironment: except ValueError: maxdepth = 0 + def traverse_in_section(node, cls): + """Like traverse(), but stay within the same section.""" + result = [] + if isinstance(node, cls): + result.append(node) + for child in node.children: + if isinstance(child, nodes.section): + continue + result.extend(traverse_in_section(child, cls)) + return result + def build_toc(node, depth=1): entries = [] - for subnode in node: - if isinstance(subnode, addnodes.toctree): - # just copy the toctree node which is then resolved - # in self.get_and_resolve_doctree - item = subnode.copy() - entries.append(item) - # do the inventory stuff - self.note_toctree(docname, subnode) + for sectionnode in node: + # find all toctree nodes in this section and add them + # to the toc (just copying the toctree node which is then + # resolved in self.get_and_resolve_doctree) + if not isinstance(sectionnode, nodes.section): + for toctreenode in traverse_in_section(sectionnode, + addnodes.toctree): + item = toctreenode.copy() + entries.append(item) + # important: do the inventory stuff + self.note_toctree(docname, toctreenode) continue - if not isinstance(subnode, nodes.section): - continue - title = subnode[0] + title = sectionnode[0] # copy the contents of the section title, but without references # and unnecessary stuff visitor = SphinxContentsFilter(document) @@ -777,7 +896,7 @@ class BuildEnvironment: # as it is the file's title anyway anchorname = '' else: - anchorname = '#' + subnode['ids'][0] + anchorname = '#' + sectionnode['ids'][0] numentries[0] += 1 reference = nodes.reference('', '', refuri=docname, anchorname=anchorname, @@ -785,7 +904,7 @@ class BuildEnvironment: para = addnodes.compact_paragraph('', '', reference) item = nodes.list_item('', para) if maxdepth == 0 or depth < maxdepth: - item += build_toc(subnode, depth+1) + item += build_toc(sectionnode, depth+1) entries.append(item) if entries: return nodes.bullet_list('', *entries) @@ -804,6 +923,15 @@ class BuildEnvironment: node['refuri'] = node['anchorname'] return toc + def get_toctree_for(self, docname, builder, collapse): + """Return the global TOC nodetree.""" + doctree = self.get_doctree(self.config.master_doc) + for toctreenode in doctree.traverse(addnodes.toctree): + result = self.resolve_toctree(docname, builder, toctreenode, + prune=True, collapse=collapse) + if result is not None: + return result + # ------- # these are called from docutils directives and therefore use self.docname # @@ -811,7 +939,8 @@ class BuildEnvironment: if fullname in self.descrefs: self.warn(self.docname, 'duplicate canonical description name %s, ' % fullname + - 'other instance in %s' % self.doc2path(self.descrefs[fullname][0]), + 'other instance in ' + + self.doc2path(self.descrefs[fullname][0]), line) self.descrefs[fullname] = (self.docname, desctype) @@ -819,17 +948,18 @@ class BuildEnvironment: self.modules[modname] = (self.docname, synopsis, platform, deprecated) self.filemodules.setdefault(self.docname, []).append(modname) + def note_progoption(self, optname, labelid): + self.progoptions[self.currprogram, optname] = (self.docname, labelid) + def note_reftarget(self, type, name, labelid): self.reftargets[type, name] = (self.docname, labelid) def note_versionchange(self, type, version, node, lineno): self.versionchanges.setdefault(version, []).append( - (type, self.docname, lineno, self.currmodule, self.currdesc, node.astext())) + (type, self.docname, lineno, self.currmodule, self.currdesc, + node.astext())) def note_dependency(self, filename): - basename = path.dirname(self.doc2path(self.docname, base=None)) - # this will do the right thing when filename is absolute too - filename = path.join(basename, filename) self.dependencies.setdefault(self.docname, set()).add(filename) # ------- @@ -845,7 +975,7 @@ class BuildEnvironment: f.close() doctree.settings.env = self doctree.reporter = Reporter(self.doc2path(docname), 2, 4, - stream=RedirStream(self._warnfunc)) + stream=WarningStream(self._warnfunc)) return doctree @@ -871,7 +1001,7 @@ class BuildEnvironment: return doctree def resolve_toctree(self, docname, builder, toctree, prune=True, maxdepth=0, - titles_only=False): + titles_only=False, collapse=False): """ Resolve a *toctree* node into individual bullet lists with titles as items, returning None (if no containing titles are found) or @@ -881,50 +1011,102 @@ class BuildEnvironment: to the value of the *maxdepth* option on the *toctree* node. If *titles_only* is True, only toplevel document titles will be in the resulting tree. + If *collapse* is True, all branches not containing docname will + be collapsed. """ + if toctree.get('hidden', False): + return None - def _walk_depth(node, depth, maxdepth, titleoverrides): + def _walk_depth(node, depth, maxdepth): """Utility: Cut a TOC at a specified depth.""" for subnode in node.children[:]: - if isinstance(subnode, (addnodes.compact_paragraph, nodes.list_item)): - _walk_depth(subnode, depth, maxdepth, titleoverrides) + if isinstance(subnode, (addnodes.compact_paragraph, + nodes.list_item)): + subnode['classes'].append('toctree-l%d' % (depth-1)) + _walk_depth(subnode, depth, maxdepth) elif isinstance(subnode, nodes.bullet_list): - if depth > maxdepth: + if maxdepth > 0 and depth > maxdepth: subnode.parent.replace(subnode, []) else: - _walk_depth(subnode, depth+1, maxdepth, titleoverrides) + _walk_depth(subnode, depth+1, maxdepth) - def _entries_from_toctree(toctreenode, separate=False): + # cull sub-entries whose parents aren't 'current' + if (collapse and + depth > 1 and + 'current' not in subnode.parent['classes']): + subnode.parent.remove(subnode) + + elif isinstance(subnode, nodes.reference): + # identify the toc entry pointing to the current document + if subnode['refuri'] == docname and \ + not subnode['anchorname']: + # tag the whole branch as 'current' + p = subnode + while p: + p['classes'].append('current') + p = p.parent + + def _entries_from_toctree(toctreenode, separate=False, subtree=False): """Return TOC entries for a toctree node.""" - includefiles = map(str, toctreenode['includefiles']) - + refs = [(e[0], str(e[1])) for e in toctreenode['entries']] entries = [] - for includefile in includefiles: + for (title, ref) in refs: try: - toc = self.tocs[includefile].deepcopy() + if url_re.match(ref): + reference = nodes.reference('', '', + refuri=ref, anchorname='', + *[nodes.Text(title)]) + para = addnodes.compact_paragraph('', '', reference) + item = nodes.list_item('', para) + toc = nodes.bullet_list('', item) + elif ref == 'self': + # 'self' refers to the document from which this + # toctree originates + ref = toctreenode['parent'] + if not title: + title = self.titles[ref].astext() + reference = nodes.reference('', '', + refuri=ref, + anchorname='', + *[nodes.Text(title)]) + para = addnodes.compact_paragraph('', '', reference) + item = nodes.list_item('', para) + # don't show subitems + toc = nodes.bullet_list('', item) + else: + toc = self.tocs[ref].deepcopy() + if title and toc.children and len(toc.children) == 1: + child = toc.children[0] + for refnode in child.traverse(nodes.reference): + if refnode['refuri'] == ref and \ + not refnode['anchorname']: + refnode.children = [nodes.Text(title)] if not toc.children: # empty toc means: no titles will show up in the toctree - self.warn(docname, 'toctree contains reference to document ' - '%r that doesn\'t have a title: no link will be ' - 'generated' % includefile) + self.warn(docname, + 'toctree contains reference to document ' + '%r that doesn\'t have a title: no link ' + 'will be generated' % ref) except KeyError: # this is raised if the included file does not exist - self.warn(docname, 'toctree contains reference to nonexisting ' - 'document %r' % includefile) + self.warn(docname, 'toctree contains reference to ' + 'nonexisting document %r' % ref) else: # if titles_only is given, only keep the main title and # sub-toctrees if titles_only: - # delete everything but the toplevel title(s) and toctrees + # delete everything but the toplevel title(s) + # and toctrees for toplevel in toc: # nodes with length 1 don't have any children anyway if len(toplevel) > 1: - subtoctrees = toplevel.traverse(addnodes.toctree) - toplevel[1][:] = subtoctrees + subtrees = toplevel.traverse(addnodes.toctree) + toplevel[1][:] = subtrees # resolve all sub-toctrees for toctreenode in toc.traverse(addnodes.toctree): i = toctreenode.parent.index(toctreenode) + 1 - for item in _entries_from_toctree(toctreenode): + for item in _entries_from_toctree(toctreenode, + subtree=True): toctreenode.parent.insert(i, item) i += 1 toctreenode.parent.remove(toctreenode) @@ -932,36 +1114,41 @@ class BuildEnvironment: entries.append(toc) else: entries.extend(toc.children) + if not subtree and not separate: + ret = nodes.bullet_list() + ret += entries + return [ret] return entries maxdepth = maxdepth or toctree.get('maxdepth', -1) - titleoverrides = toctree.get('includetitles', {}) - tocentries = _entries_from_toctree(toctree, separate=True) + # NOTE: previously, this was separate=True, but that leads to artificial + # separation when two or more toctree entries form a logical unit, so + # separating mode is no longer used -- it's kept here for history's sake + tocentries = _entries_from_toctree(toctree, separate=False) if not tocentries: return None newnode = addnodes.compact_paragraph('', '', *tocentries) newnode['toctree'] = True - # prune the tree to maxdepth and replace titles - if maxdepth > 0 and prune: - _walk_depth(newnode, 1, maxdepth, titleoverrides) - # replace titles, if needed, and set the target paths in the - # toctrees (they are not known at TOC generation time) + + # prune the tree to maxdepth and replace titles, also set level classes + _walk_depth(newnode, 1, prune and maxdepth or 0) + + # set the target paths in the toctrees (they are not known at TOC + # generation time) for refnode in newnode.traverse(nodes.reference): - refnode['refuri'] = builder.get_relative_uri( - docname, refnode['refuri']) + refnode['anchorname'] - if titleoverrides and not refnode['anchorname'] \ - and refnode['refuri'] in titleoverrides: - newtitle = titleoverrides[refnode['refuri']] - refnode.children = [nodes.Text(newtitle)] + if not url_re.match(refnode['refuri']): + refnode['refuri'] = builder.get_relative_uri( + docname, refnode['refuri']) + refnode['anchorname'] return newnode - descroles = frozenset(('data', 'exc', 'func', 'class', 'const', 'attr', 'obj', - 'meth', 'cfunc', 'cmember', 'cdata', 'ctype', 'cmacro')) + descroles = frozenset(('data', 'exc', 'func', 'class', 'const', + 'attr', 'obj', 'meth', 'cfunc', 'cmember', + 'cdata', 'ctype', 'cmacro')) def resolve_references(self, doctree, fromdocname, builder): - reftarget_roles = set(('token', 'term', 'option', 'citation')) + reftarget_roles = set(('token', 'term', 'citation')) # add all custom xref types too reftarget_roles.update(i[0] for i in additional_xref_types.values()) @@ -975,30 +1162,33 @@ class BuildEnvironment: try: if typ == 'ref': if node['refcaption']: - # reference to anonymous label; the reference uses the supplied - # link caption + # reference to anonymous label; the reference uses + # the supplied link caption docname, labelid = self.anonlabels.get(target, ('','')) sectname = node.astext() if not docname: - newnode = doctree.reporter.system_message( - 2, 'undefined label: %s' % target) + self.warn(fromdocname, 'undefined label: %s' % + target, node.line) else: - # reference to the named label; the final node will contain the - # section name after the label - docname, labelid, sectname = self.labels.get(target, ('','','')) + # reference to the named label; the final node will + # contain the section name after the label + docname, labelid, sectname = self.labels.get(target, + ('','','')) if not docname: - newnode = doctree.reporter.system_message( - 2, 'undefined label: %s -- if you don\'t ' % target + - 'give a link caption the label must precede a section ' - 'header.') + self.warn( + fromdocname, + 'undefined label: %s' % target + ' -- if you ' + 'don\'t give a link caption the label must ' + 'precede a section header.', node.line) if docname: newnode = nodes.reference('', '') innernode = nodes.emphasis(sectname, sectname) if docname == fromdocname: newnode['refid'] = labelid else: - # set more info in contnode in case the get_relative_uri call - # raises NoUri, the builder will then have to resolve these + # set more info in contnode; in case the + # get_relative_uri call raises NoUri, + # the builder will then have to resolve these contnode = addnodes.pending_xref('') contnode['refdocname'] = docname contnode['refsectname'] = sectname @@ -1007,6 +1197,27 @@ class BuildEnvironment: if labelid: newnode['refuri'] += '#' + labelid newnode.append(innernode) + else: + newnode = contnode + elif typ == 'doc': + # directly reference to document by source name; + # can be absolute or relative + docname = docname_join(fromdocname, target) + if docname not in self.all_docs: + self.warn(fromdocname, '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() + innernode = nodes.emphasis(caption, caption) + newnode = nodes.reference('', '') + newnode['refuri'] = builder.get_relative_uri( + fromdocname, docname) + newnode.append(innernode) elif typ == 'keyword': # keywords are referenced by named labels docname, labelid, _ = self.labels.get(target, ('','','')) @@ -1021,14 +1232,31 @@ class BuildEnvironment: newnode['refuri'] = builder.get_relative_uri( fromdocname, docname) + '#' + labelid newnode.append(contnode) + elif typ == 'option': + progname = node['refprogram'] + docname, labelid = self.progoptions.get((progname, target), + ('', '')) + if not docname: + newnode = contnode + else: + newnode = nodes.reference('', '') + if docname == fromdocname: + newnode['refid'] = labelid + else: + newnode['refuri'] = builder.get_relative_uri( + fromdocname, docname) + '#' + labelid + newnode.append(contnode) elif typ in reftarget_roles: - docname, labelid = self.reftargets.get((typ, target), ('', '')) + docname, labelid = self.reftargets.get((typ, target), + ('', '')) if not docname: if typ == 'term': - self.warn(fromdocname, 'term not in glossary: %s' % target, + self.warn(fromdocname, + 'term not in glossary: %s' % target, node.line) elif typ == 'citation': - self.warn(fromdocname, 'citation not found: %s' % target, + self.warn(fromdocname, + 'citation not found: %s' % target, node.line) newnode = contnode else: @@ -1042,24 +1270,18 @@ class BuildEnvironment: elif typ == 'mod': docname, synopsis, platform, deprecated = \ self.modules.get(target, ('','','', '')) - # just link to an anchor if there are multiple modules in one file - # because the anchor is generally below the heading which is ugly - # but can't be helped easily - anchor = '' if not docname: - newnode = builder.app.emit_firstresult('missing-reference', - self, node, contnode) + newnode = builder.app.emit_firstresult( + 'missing-reference', self, node, contnode) if not newnode: newnode = contnode elif docname == fromdocname: # don't link to self newnode = contnode else: - if len(self.filemodules[docname]) > 1: - anchor = '#' + 'module-' + target newnode = nodes.reference('', '') - newnode['refuri'] = ( - builder.get_relative_uri(fromdocname, docname) + anchor) + newnode['refuri'] = builder.get_relative_uri( + fromdocname, docname) + '#module-' + target newnode['reftitle'] = '%s%s%s' % ( (platform and '(%s) ' % platform), synopsis, (deprecated and ' (deprecated)' or '')) @@ -1072,8 +1294,8 @@ class BuildEnvironment: name, desc = self.find_desc(modname, clsname, target, typ, searchorder) if not desc: - newnode = builder.app.emit_firstresult('missing-reference', - self, node, contnode) + newnode = builder.app.emit_firstresult( + 'missing-reference', self, node, contnode) if not newnode: newnode = contnode else: @@ -1087,15 +1309,80 @@ class BuildEnvironment: newnode['reftitle'] = name newnode.append(contnode) else: - raise RuntimeError('unknown xfileref node encountered: %s' % node) + raise RuntimeError('unknown xfileref node encountered: %s' + % node) except NoUri: newnode = contnode if newnode: node.replace_self(newnode) + for node in doctree.traverse(addnodes.only): + try: + ret = builder.tags.eval_condition(node['expr']) + except Exception, err: + self.warn(fromdocname, 'exception while evaluating only ' + 'directive expression: %s' % err, node.line) + node.replace_self(node.children) + else: + if ret: + node.replace_self(node.children) + else: + node.replace_self([]) + # allow custom references to be resolved builder.app.emit('doctree-resolved', doctree, fromdocname) + def assign_section_numbers(self): + """Assign a section number to each heading under a numbered toctree.""" + # a list of all docnames whose section numbers changed + rewrite_needed = [] + + old_secnumbers = self.toc_secnumbers + self.toc_secnumbers = {} + + def _walk_toc(node, secnums, titlenode=None): + # titlenode is the title of the document, it will get assigned a + # secnumber too, so that it shows up in next/prev/parent rellinks + for subnode in node.children: + if isinstance(subnode, nodes.bullet_list): + numstack.append(0) + _walk_toc(subnode, secnums, titlenode) + numstack.pop() + titlenode = None + elif isinstance(subnode, nodes.list_item): + _walk_toc(subnode, secnums, titlenode) + titlenode = None + elif isinstance(subnode, addnodes.compact_paragraph): + numstack[-1] += 1 + secnums[subnode[0]['anchorname']] = \ + subnode[0]['secnumber'] = tuple(numstack) + if titlenode: + titlenode['secnumber'] = tuple(numstack) + titlenode = None + elif isinstance(subnode, addnodes.toctree): + _walk_toctree(subnode) + + def _walk_toctree(toctreenode): + for (title, ref) in toctreenode['entries']: + if url_re.match(ref) or ref == 'self': + # don't mess with those + continue + if ref in self.tocs: + secnums = self.toc_secnumbers[ref] = {} + _walk_toc(self.tocs[ref], secnums, self.titles.get(ref)) + if secnums != old_secnumbers.get(ref): + rewrite_needed.append(ref) + + for docname in self.numbered_toctrees: + doctree = self.get_doctree(docname) + for toctreenode in doctree.traverse(addnodes.toctree): + if toctreenode.get('numbered'): + # every numbered toctree gets new numbering + numstack = [0] + _walk_toctree(toctreenode) + + return rewrite_needed + def create_index(self, builder, _fixre=re.compile(r'(.*) ([(][^()]*[)])')): """Create the real index from the collected index entries.""" new = {} @@ -1114,25 +1401,42 @@ class BuildEnvironment: pass for fn, entries in self.indexentries.iteritems(): - # new entry types must be listed in directives.py! + # new entry types must be listed in directives/other.py! for type, string, tid, alias in entries: if type == 'single': try: entry, subentry = string.split(';', 1) except ValueError: entry, subentry = string, '' + if not entry: + self.warn(fn, 'invalid index entry %r' % string) + continue add_entry(entry.strip(), subentry.strip()) elif type == 'pair': - first, second = map(lambda x: x.strip(), string.split(';', 1)) + try: + first, second = map(lambda x: x.strip(), + string.split(';', 1)) + if not first or not second: + raise ValueError + except ValueError: + self.warn(fn, 'invalid pair index entry %r' % string) + continue add_entry(first, second) add_entry(second, first) elif type == 'triple': - first, second, third = map(lambda x: x.strip(), string.split(';', 2)) + try: + first, second, third = map(lambda x: x.strip(), + string.split(';', 2)) + if not first or not second or not third: + raise ValueError + except ValueError: + self.warn(fn, 'invalid triple index entry %r' % string) + continue add_entry(first, second+' '+third) add_entry(second, third+', '+first) add_entry(third, first+' '+second) else: - self.warn(fn, "unknown index entry type %r" % type) + self.warn(fn, 'unknown index entry type %r' % type) newlist = new.items() newlist.sort(key=lambda t: t[0].lower()) @@ -1154,8 +1458,10 @@ class BuildEnvironment: m = _fixre.match(key) if m: if oldkey == m.group(1): - # prefixes match: add entry as subitem of the previous entry - oldsubitems.setdefault(m.group(2), [[], {}])[0].extend(targets) + # prefixes match: add entry as subitem of the + # previous entry + oldsubitems.setdefault(m.group(2), [[], {}])[0].\ + extend(targets) del newlist[i] continue oldkey = m.group(1) @@ -1175,7 +1481,8 @@ class BuildEnvironment: else: # get all other symbols under one heading return 'Symbols' - return [(key, list(group)) for (key, group) in groupby(newlist, keyfunc)] + return [(key, list(group)) + for (key, group) in groupby(newlist, keyfunc)] def collect_relations(self): relations = {} @@ -1214,7 +1521,8 @@ class BuildEnvironment: # else it will stay None # same for children if includes: - for subindex, args in enumerate(izip(includes, [None] + includes, + for subindex, args in enumerate(izip(includes, + [None] + includes, includes[1:] + [None])): collect([(docname, subindex)] + parents, *args) relations[docname] = [parents[0][0], previous, next] @@ -1282,14 +1590,16 @@ class BuildEnvironment: def find_keyword(self, keyword, avoid_fuzzy=False, cutoff=0.6, n=20): """ - Find keyword matches for a keyword. If there's an exact match, just return - it, else return a list of fuzzy matches if avoid_fuzzy isn't True. + Find keyword matches for a keyword. If there's an exact match, + just return it, else return a list of fuzzy matches if avoid_fuzzy + isn't True. Keywords searched are: first modules, then descrefs. Returns: None if nothing found (type, docname, anchorname) if exact match found - list of (quality, type, docname, anchorname, description) if fuzzy + list of (quality, type, docname, anchorname, description) + if fuzzy """ if keyword in self.modules: diff --git a/sphinx/errors.py b/sphinx/errors.py new file mode 100644 index 000000000..d9b8b6b87 --- /dev/null +++ b/sphinx/errors.py @@ -0,0 +1,48 @@ +# -*- coding: utf-8 -*- +""" + sphinx.errors + ~~~~~~~~~~~~~ + + 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. + :license: BSD, see LICENSE for details. +""" + +class SphinxError(Exception): + """ + Base class for Sphinx errors that are shown to the user in a nicer + way than normal exceptions. + """ + category = 'Sphinx error' + + +class SphinxWarning(SphinxError): + """Raised for warnings if warnings are treated as errors.""" + category = 'Warning, treated as error' + + +class ExtensionError(SphinxError): + """Raised if something's wrong with the configuration.""" + category = 'Extension error' + + def __init__(self, message, orig_exc=None): + super(ExtensionError, self).__init__(message) + self.orig_exc = orig_exc + + def __repr__(self): + if self.orig_exc: + return '%s(%r, %r)' % (self.__class__.__name__, + self.message, self.orig_exc) + return '%s(%r)' % (self.__class__.__name__, self.message) + + def __str__(self): + parent_str = super(ExtensionError, self).__str__() + if self.orig_exc: + return '%s (exception: %s)' % (parent_str, self.orig_exc) + return parent_str + + +class ThemeError(SphinxError): + category = 'Theme error' diff --git a/sphinx/ext/__init__.py b/sphinx/ext/__init__.py index d111f11b9..c6e239518 100644 --- a/sphinx/ext/__init__.py +++ b/sphinx/ext/__init__.py @@ -5,6 +5,6 @@ Contains Sphinx features not activated by default. - :copyright: 2008 by Georg Brandl. - :license: BSD. + :copyright: Copyright 2007-2009 by the Sphinx team, see AUTHORS. + :license: BSD, see LICENSE for details. """ diff --git a/sphinx/ext/autodoc.py b/sphinx/ext/autodoc.py index f77be89c8..43c4b26a9 100644 --- a/sphinx/ext/autodoc.py +++ b/sphinx/ext/autodoc.py @@ -7,46 +7,82 @@ the doctree, thus avoiding duplication between docstrings and documentation for those who like elaborate docstrings. - :copyright: 2008 by Georg Brandl, Pauli Virtanen, Martin Hans. - :license: BSD. + :copyright: Copyright 2007-2009 by the Sphinx team, see AUTHORS. + :license: BSD, see LICENSE for details. """ import re import sys -import types import inspect -import linecache -from types import FunctionType, BuiltinMethodType, MethodType +from types import ModuleType, FunctionType, BuiltinFunctionType, MethodType, \ + ClassType from docutils import nodes -from docutils.parsers.rst import directives +from docutils.utils import assemble_option_dict from docutils.statemachine import ViewList -from sphinx.util import rpartition -from sphinx.directives.desc import py_sig_re +from sphinx.util import rpartition, nested_parse_with_titles, force_decode +from sphinx.pycode import ModuleAnalyzer, PycodeError +from sphinx.application import ExtensionError +from sphinx.util.compat import Directive +from sphinx.util.docstrings import prepare_docstring + try: base_exception = BaseException except NameError: base_exception = Exception -_charset_re = re.compile(r'coding[:=]\s*([-\w.]+)') -_module_charsets = {} + +#: extended signature RE: with explicit module name separated by :: +py_ext_sig_re = re.compile( + r'''^ ([\w.]+::)? # explicit module name + ([\w.]+\.)? # module and/or class name(s) + (\w+) \s* # thing name + (?: \((.*)\) # optional: arguments + (?:\s* -> \s* (.*))? # return annotation + )? $ # and nothing more + ''', re.VERBOSE) -class Options(object): - pass - - -def is_static_method(obj): - """Check if the object given is a static method.""" - if isinstance(obj, (FunctionType, classmethod)): +class DefDict(dict): + """A dict that returns a default on nonexisting keys.""" + def __init__(self, default): + dict.__init__(self) + self.default = default + def __getitem__(self, key): + try: + return dict.__getitem__(self, key) + except KeyError: + return self.default + def __nonzero__(self): + # docutils check "if option_spec" return True - elif isinstance(obj, BuiltinMethodType): - return obj.__self__ is not None - elif isinstance(obj, MethodType): - return obj.im_self is not None - return False + +identity = lambda x: x + + +class Options(dict): + """A dict/attribute hybrid that returns None on nonexisting keys.""" + def __getattr__(self, name): + try: + return self[name.replace('_', '-')] + except KeyError: + return None + + +ALL = object() + +def members_option(arg): + """Used to convert the :members: option to auto directives.""" + if arg is None: + return ALL + return [x.strip() for x in arg.split(',')] + +def bool_option(arg): + """Used to convert flag options to auto directives. (Instead of + directives.flag(), which returns None.)""" + return True class AutodocReporter(object): @@ -155,504 +191,913 @@ def between(marker, what=None, keepempty=False): def isdescriptor(x): """Check if the object is some kind of descriptor.""" for item in '__get__', '__set__', '__delete__': - if callable(getattr(x, item, None)): + if hasattr(getattr(x, item, None), '__call__'): return True return False -def prepare_docstring(s): +class Documenter(object): """ - Convert a docstring into lines of parseable reST. Return it as a list of - lines usable for inserting into a docutils ViewList (used as argument - of nested_parse().) An empty line is added to act as a separator between - this docstring and following content. + A Documenter knows how to autodocument a single object type. When + registered with the AutoDirective, it will be used to document objects + of that type when needed by autodoc. + + Its *objtype* attribute selects what auto directive it is assigned to + (the directive name is 'auto' + objtype), and what directive it generates + by default, though that can be overridden by an attribute called + *directivetype*. + + A Documenter has an *option_spec* that works like a docutils directive's; + in fact, it will be used to parse an auto directive's options that matches + the documenter. """ - lines = s.expandtabs().splitlines() - # Find minimum indentation of any non-blank lines after first line. - margin = sys.maxint - for line in lines[1:]: - content = len(line.lstrip()) - if content: - indent = len(line) - content - margin = min(margin, indent) - # Remove indentation. - if lines: - lines[0] = lines[0].lstrip() - if margin < sys.maxint: - for i in range(1, len(lines)): lines[i] = lines[i][margin:] - # Remove any leading blank lines. - while lines and not lines[0]: - lines.pop(0) - # make sure there is an empty line at the end - if lines and lines[-1]: - lines.append('') - return lines + #: name by which the directive is called (auto...) and the default + #: generated directive name + objtype = 'object' + #: indentation by which to indent the directive content + content_indent = u' ' + #: priority if multiple documenters return True from can_document_member + priority = 0 + #: order if autodoc_member_order is set to 'groupwise' + member_order = 0 + option_spec = {'noindex': bool_option} -def get_module_charset(module): - """Return the charset of the given module (cached in _module_charsets).""" - if module in _module_charsets: - return _module_charsets[module] - try: - filename = __import__(module, None, None, ['foo']).__file__ - except (ImportError, AttributeError): - return None - if filename[-4:].lower() in ('.pyc', '.pyo'): - filename = filename[:-1] - for line in [linecache.getline(filename, x) for x in (1, 2)]: - match = _charset_re.search(line) - if match is not None: - charset = match.group(1) - break - else: - charset = 'ascii' - _module_charsets[module] = charset - return charset + @staticmethod + def get_attr(obj, name, *defargs): + """getattr() override for types such as Zope interfaces.""" + for typ, func in AutoDirective._special_attrgetters.iteritems(): + if isinstance(obj, typ): + return func(obj, name, *defargs) + return getattr(obj, name, *defargs) + @classmethod + def can_document_member(cls, member, membername, isattr, parent): + """Called to see if a member can be documented by this documenter.""" + raise NotImplementedError('must be implemented in subclasses') -class RstGenerator(object): - def __init__(self, options, document, lineno): - self.options = options - self.env = document.settings.env - self.reporter = document.reporter - self.lineno = lineno - self.filename_set = set() - self.warnings = [] - self.result = ViewList() + def __init__(self, directive, name, indent=u''): + self.directive = directive + self.env = directive.env + self.options = directive.genopt + self.name = name + self.indent = indent + # the module and object path within the module, and the fully + # qualified name (all set after resolve_name succeeds) + self.modname = None + self.module = None + self.objpath = None + self.fullname = None + # extra signature items (arguments and return annotation, + # also set after resolve_name succeeds) + self.args = None + self.retann = None + # the object to document (set after import_object succeeds) + self.object = None + # the module analyzer to get at attribute docs, or None + self.analyzer = None - def warn(self, msg): - self.warnings.append(self.reporter.warning(msg, line=self.lineno)) + def add_line(self, line, source, *lineno): + """Append one line of generated reST to the output.""" + self.directive.result.append(self.indent + line, source, *lineno) - def get_doc(self, what, name, obj): - """Format and yield lines of the docstring(s) for the object.""" - docstrings = [] - if getattr(obj, '__doc__', None): - docstrings.append(obj.__doc__) - # skip some lines in module docstrings if configured - if what == 'module' and self.env.config.automodule_skip_lines and docstrings: - docstrings[0] = '\n'.join(docstrings[0].splitlines() - [self.env.config.automodule_skip_lines:]) - # for classes, what the "docstring" is can be controlled via an option - if what in ('class', 'exception'): - content = self.env.config.autoclass_content - if content in ('both', 'init'): - initdocstring = getattr(obj, '__init__', None).__doc__ - # for new-style classes, no __init__ means default __init__ - if initdocstring == object.__init__.__doc__: - initdocstring = None - if initdocstring: - if content == 'init': - docstrings = [initdocstring] - else: - docstrings.append('\n\n' + initdocstring) - # the default is only the class docstring + def resolve_name(self, modname, parents, path, base): + """ + Resolve the module and name of the object to document given by the + arguments and the current module/class. - # decode the docstrings using the module's source encoding - charset = None - module = getattr(obj, '__module__', None) - if module is not None: - charset = get_module_charset(module) + Must return a pair of the module name and a chain of attributes; for + example, it would return ``('zipfile', ['ZipFile', 'open'])`` for the + ``zipfile.ZipFile.open`` method. + """ + raise NotImplementedError('must be implemented in subclasses') - for docstring in docstrings: - if isinstance(docstring, str): - if charset: - docstring = docstring.decode(charset) - else: - try: - # try decoding with utf-8, should only work for real UTF-8 - docstring = docstring.decode('utf-8') - except UnicodeError: - # last resort -- can't fail - docstring = docstring.decode('latin1') - docstringlines = prepare_docstring(docstring) - if self.env.app: - # let extensions preprocess docstrings - self.env.app.emit('autodoc-process-docstring', - what, name, obj, self.options, docstringlines) - for line in docstringlines: - yield line - - def resolve_name(self, what, name): + def parse_name(self): """ Determine what module to import and what attribute to document. - Returns a tuple of: the full name, the module name, a path of - names to get via getattr, the signature and return annotation. + Returns True and sets *self.modname*, *self.objpath*, *self.fullname*, + *self.args* and *self.retann* if parsing and resolving was successful. """ - # first, parse the definition -- auto directives for classes and functions - # can contain a signature which is then used instead of an autogenerated one + # first, parse the definition -- auto directives for classes and + # functions can contain a signature which is then used instead of + # an autogenerated one try: - path, base, args, retann = py_sig_re.match(name).groups() - except: - self.warn('invalid signature for auto%s (%r)' % (what, name)) - return - # fullname is the fully qualified name, base the name after the last dot - fullname = (path or '') + base - - if what == 'module': - if args or retann: - self.warn('ignoring signature arguments and return annotation ' - 'for automodule %s' % fullname) - return fullname, fullname, [], None, None - - elif what in ('class', 'exception', 'function'): - if path: - mod = path.rstrip('.') - else: - mod = None - # if documenting a toplevel object without explicit module, it can - # be contained in another auto directive ... - if hasattr(self.env, 'autodoc_current_module'): - mod = self.env.autodoc_current_module - # ... or in the scope of a module directive - if not mod: - mod = self.env.currmodule - return fullname, mod, [base], args, retann + explicit_modname, path, base, args, retann = \ + py_ext_sig_re.match(self.name).groups() + except AttributeError: + self.directive.warn('invalid signature for auto%s (%r)' % + (self.objtype, self.name)) + return False + # support explicit module and class name separation via :: + if explicit_modname is not None: + modname = explicit_modname[:-2] + parents = path and path.rstrip('.').split('.') or [] else: - if path: - mod_cls = path.rstrip('.') - else: - mod_cls = None - # if documenting a class-level object without path, there must be a - # current class, either from a parent auto directive ... - if hasattr(self.env, 'autodoc_current_class'): - mod_cls = self.env.autodoc_current_class - # ... or from a class directive - if mod_cls is None: - mod_cls = self.env.currclass - mod, cls = rpartition(mod_cls, '.') - # if the module name is still missing, get it like above - if not mod and hasattr(self.env, 'autodoc_current_module'): - mod = self.env.autodoc_current_module - if not mod: - mod = self.env.currmodule - return fullname, mod, [cls, base], args, retann + modname = None + parents = [] - def format_signature(self, what, name, obj, args, retann): - """ - Return the signature of the object, formatted for display. - """ - if what not in ('class', 'method', 'function'): - return '' + self.modname, self.objpath = \ + self.resolve_name(modname, parents, path, base) - err = None - if args is not None: + if not self.modname: + return False + + self.args = args + self.retann = retann + self.fullname = (self.modname or '') + \ + (self.objpath and '.' + '.'.join(self.objpath) or '') + return True + + def import_object(self): + """ + Import the object given by *self.modname* and *self.objpath* and sets + it as *self.object*. + + Returns True if successful, False if an error occurred. + """ + try: + __import__(self.modname) + obj = self.module = sys.modules[self.modname] + for part in self.objpath: + obj = self.get_attr(obj, part) + self.object = obj + return True + except (ImportError, AttributeError), err: + self.directive.warn( + 'autodoc can\'t import/find %s %r, it reported error: ' + '"%s", please check your spelling and sys.path' % + (self.objtype, str(self.fullname), err)) + return False + + def get_real_modname(self): + """ + Get the real module name of an object to document. (It can differ + from the name of the module through which the object was imported.) + """ + return self.get_attr(self.object, '__module__', None) or self.modname + + def check_module(self): + """ + Check if *self.object* is really defined in the module given by + *self.modname*. + """ + modname = self.get_attr(self.object, '__module__', None) + if modname and modname != self.modname: + return False + return True + + def format_args(self): + """ + Format the argument signature of *self.object*. Should return None if + the object does not have a signature. + """ + return None + + def format_signature(self): + """ + Format the signature (arguments and return annotation) of the object. + Let the user process it via the ``autodoc-process-signature`` event. + """ + if self.args is not None: # signature given explicitly - args = "(%s)" % args + args = "(%s)" % self.args else: # try to introspect the signature - try: - args = None - getargs = True - if what == 'class': - # for classes, the relevant signature is the __init__ method's - obj = getattr(obj, '__init__', None) - # classes without __init__ method, default __init__ or - # __init__ written in C? - if obj is None or obj is object.__init__ or not \ - (inspect.ismethod(obj) or inspect.isfunction(obj)): - getargs = False - elif inspect.isbuiltin(obj) or inspect.ismethoddescriptor(obj): - # can never get arguments of a C function or method - getargs = False - if getargs: - argspec = inspect.getargspec(obj) - if what in ('class', 'method') and argspec[0] and \ - argspec[0][0] in ('cls', 'self'): - del argspec[0][0] - args = inspect.formatargspec(*argspec) - except Exception, e: - args = None - err = e + args = self.format_args() + if args is None: + return '' + retann = self.retann - result = self.env.app.emit_firstresult('autodoc-process-signature', what, - name, obj, self.options, args, retann) + result = self.env.app.emit_firstresult( + 'autodoc-process-signature', self.objtype, self.fullname, + self.object, self.options, args, retann) if result: args, retann = result if args is not None: - return '%s%s' % (args, retann or '') - elif err: - # re-raise the error for perusal of the handler in generate() - raise RuntimeError(err) + return args + (retann and (' -> %s' % retann) or '') else: return '' - def generate(self, what, name, members, add_content, indent=u'', check_module=False): - """ - Generate reST for the object in self.result. - """ - fullname, mod, objpath, args, retann = self.resolve_name(what, name) - if not mod: - # need a module to import - self.warn('don\'t know which module to import for autodocumenting %r ' - '(try placing a "module" or "currentmodule" directive in the ' - 'document, or giving an explicit module name)' % fullname) - return - - # the name to put into the generated directive -- doesn't contain the module - name_in_directive = '.'.join(objpath) or mod - - # now, import the module and get object to document - try: - todoc = module = __import__(mod, None, None, ['foo']) - if hasattr(module, '__file__') and module.__file__: - modfile = module.__file__ - if modfile[-4:].lower() in ('.pyc', '.pyo'): - modfile = modfile[:-1] - self.filename_set.add(modfile) - else: - modfile = None # e.g. for builtin and C modules - for part in objpath: - todoc = getattr(todoc, part) - except (ImportError, AttributeError), err: - self.warn('autodoc can\'t import/find %s %r, it reported error: "%s", ' - 'please check your spelling and sys.path' % - (what, str(fullname), err)) - return - - # check __module__ of object if wanted (for members not given explicitly) - if check_module: - if hasattr(todoc, '__module__'): - if todoc.__module__ != mod: - return - - # format the object's signature, if any - try: - sig = self.format_signature(what, name, todoc, args, retann) - except Exception, err: - self.warn('error while formatting signature for %s: %s' % - (fullname, err)) - sig = '' - - # make sure that the result starts with an empty line. This is - # necessary for some situations where another directive preprocesses - # reST and no starting newline is present - self.result.append(u'', '') - - # now, create the directive header - directive = (what == 'method' and is_static_method(todoc)) \ - and 'staticmethod' or what - self.result.append(indent + u'.. %s:: %s%s' % - (directive, name_in_directive, sig), '<autodoc>') - if what == 'module': - # Add some module-specific options - if self.options.synopsis: - self.result.append(indent + u' :synopsis: ' + self.options.synopsis, - '<autodoc>') - if self.options.platform: - self.result.append(indent + u' :platform: ' + self.options.platform, - '<autodoc>') - if self.options.deprecated: - self.result.append(indent + u' :deprecated:', '<autodoc>') - else: - # Be explicit about the module, this is necessary since .. class:: doesn't - # support a prepended module name - self.result.append(indent + u' :module: %s' % mod, '<autodoc>') + def add_directive_header(self, sig): + """Add the directive header and options to the generated content.""" + directive = getattr(self, 'directivetype', self.objtype) + # the name to put into the generated directive -- doesn't contain + # the module (except for module directive of course) + name_in_directive = '.'.join(self.objpath) or self.modname + self.add_line(u'.. %s:: %s%s' % (directive, name_in_directive, sig), + '<autodoc>') if self.options.noindex: - self.result.append(indent + u' :noindex:', '<autodoc>') - self.result.append(u'', '<autodoc>') + self.add_line(u' :noindex:', '<autodoc>') + if self.objpath: + # Be explicit about the module, this is necessary since .. class:: + # etc. don't support a prepended module name + self.add_line(u' :module: %s' % self.modname, '<autodoc>') - if self.options.show_inheritance and what in ('class', 'exception'): - if len(todoc.__bases__): - bases = [b.__module__ == '__builtin__' and - u':class:`%s`' % b.__name__ or - u':class:`%s.%s`' % (b.__module__, b.__name__) - for b in todoc.__bases__] - self.result.append(indent + u' Bases: %s' % ', '.join(bases), - '<autodoc>') - self.result.append(u'', '<autodoc>') + def get_doc(self, encoding=None): + """Decode and return lines of the docstring(s) for the object.""" + docstring = self.get_attr(self.object, '__doc__', None) + if docstring: + # make sure we have Unicode docstrings, then sanitize and split + # into lines + return [prepare_docstring(force_decode(docstring, encoding))] + return [] - # the module directive doesn't have content - if what != 'module': - indent += u' ' + def process_doc(self, docstrings): + """Let the user process the docstrings before adding them.""" + for docstringlines in docstrings: + if self.env.app: + # let extensions preprocess docstrings + self.env.app.emit('autodoc-process-docstring', + self.objtype, self.fullname, self.object, + self.options, docstringlines) + for line in docstringlines: + yield line - if modfile: - sourcename = '%s:docstring of %s' % (modfile, fullname) + def add_content(self, more_content, no_docstring=False): + """Add content from docstrings, attribute documentation and user.""" + # set sourcename and add content from attribute documentation + if self.analyzer: + # prevent encoding errors when the file name is non-ASCII + filename = unicode(self.analyzer.srcname, + sys.getfilesystemencoding(), 'replace') + sourcename = u'%s:docstring of %s' % (filename, self.fullname) + + attr_docs = self.analyzer.find_attr_docs() + if self.objpath: + key = ('.'.join(self.objpath[:-1]), self.objpath[-1]) + if key in attr_docs: + no_docstring = True + docstrings = [attr_docs[key]] + for i, line in enumerate(self.process_doc(docstrings)): + self.add_line(line, sourcename, i) else: - sourcename = 'docstring of %s' % fullname + sourcename = u'docstring of %s' % self.fullname # add content from docstrings - for i, line in enumerate(self.get_doc(what, fullname, todoc)): - self.result.append(indent + line, sourcename, i) + if not no_docstring: + encoding = self.analyzer and self.analyzer.encoding + docstrings = self.get_doc(encoding) + for i, line in enumerate(self.process_doc(docstrings)): + self.add_line(line, sourcename, i) - # add source content, if present - if add_content: - for line, src in zip(add_content.data, add_content.items): - self.result.append(indent + line, src[0], src[1]) + # add additional content (e.g. from document), if present + if more_content: + for line, src in zip(more_content.data, more_content.items): + self.add_line(line, src[0], src[1]) - # document members? - if not members or what in ('function', 'method', 'attribute'): - return + def get_object_members(self, want_all): + """ + Return `(members_check_module, members)` where `members` is a + list of `(membername, member)` pairs of the members of *self.object*. - # set current namespace for finding members - self.env.autodoc_current_module = mod - if objpath: - self.env.autodoc_current_class = objpath[0] - - # add members, if possible - _all = members == ['__all__'] - members_check_module = False - if _all: - # unqualified :members: given - if what == 'module': - if hasattr(todoc, '__all__'): - members_check_module = False - all_members = [] - for mname in todoc.__all__: - try: - all_members.append((mname, getattr(todoc, mname))) - except AttributeError: - self.warn('missing attribute mentioned in __all__: ' - 'module %s, attribute %s' % - (todoc.__name__, mname)) - else: - # for implicit module members, check __module__ to avoid - # documenting imported objects - members_check_module = True - all_members = inspect.getmembers(todoc) - else: - if self.options.inherited_members: - # getmembers() uses dir() which pulls in members from all - # base classes - all_members = inspect.getmembers(todoc) - else: - # __dict__ contains only the members directly defined in the class - all_members = sorted(todoc.__dict__.iteritems()) + If *want_all* is True, return all members. Else, only return those + members given by *self.options.members* (which may also be none). + """ + if not want_all: + if not self.options.members: + return False, [] + # specific members given + ret = [] + for mname in self.options.members: + try: + ret.append((mname, self.get_attr(self.object, mname))) + except AttributeError: + self.directive.warn('missing attribute %s in object %s' + % (mname, self.fullname)) + return False, ret + elif self.options.inherited_members: + # getmembers() uses dir() which pulls in members from all + # base classes + return False, inspect.getmembers(self.object) else: - all_members = [(mname, getattr(todoc, mname)) for mname in members] - for (membername, member) in all_members: - # ignore members whose name starts with _ by default - if _all and membername.startswith('_'): - continue + # __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) + return False, sorted([ + (mname, self.get_attr(self.object, mname)) + for mname in self.get_attr(self.object, '__dict__')]) - # ignore undocumented members if :undoc-members: is not given - doc = getattr(member, '__doc__', None) - skip = not self.options.undoc_members and not doc - # give the user a chance to decide whether this member should be skipped + def filter_members(self, members, want_all): + """ + Filter the given member list: members are skipped if + + - they are private (except if given explicitly) + - they are undocumented (except if undoc-members is given) + + The user can override the skipping decision by connecting to the + ``autodoc-skip-member`` event. + """ + ret = [] + + # search for members in source code too + namespace = '.'.join(self.objpath) # will be empty for modules + + if self.analyzer: + attr_docs = self.analyzer.find_attr_docs() + else: + attr_docs = {} + + # process members and determine which to skip + for (membername, member) in members: + # if isattr is True, the member is documented as an attribute + isattr = False + + if want_all and membername.startswith('_'): + # ignore members whose name starts with _ by default + skip = True + elif (namespace, membername) in attr_docs: + # keep documented attributes + skip = False + isattr = True + else: + # ignore undocumented members if :undoc-members: + # is not given + doc = self.get_attr(member, '__doc__', None) + skip = not self.options.undoc_members and not doc + + # give the user a chance to decide whether this member + # should be skipped if self.env.app: # let extensions preprocess docstrings skip_user = self.env.app.emit_firstresult( - 'autodoc-skip-member', what, membername, member, skip, self.options) + 'autodoc-skip-member', self.objtype, membername, member, + skip, self.options) if skip_user is not None: skip = skip_user if skip: continue - if what == 'module': - if isinstance(member, types.FunctionType): - memberwhat = 'function' - elif isinstance(member, types.ClassType) or \ - isinstance(member, type): - if issubclass(member, base_exception): - memberwhat = 'exception' - else: - memberwhat = 'class' - else: - # XXX: todo -- attribute docs - continue - else: - if callable(member): - memberwhat = 'method' - elif isdescriptor(member): - memberwhat = 'attribute' - else: - # XXX: todo -- attribute docs - continue - full_membername = fullname + '.' + membername - self.generate(memberwhat, full_membername, ['__all__'], None, indent, - check_module=members_check_module) + ret.append((membername, member, isattr)) + return ret + + def document_members(self, all_members=False): + """ + Generate reST for member documentation. If *all_members* is True, + do all members, else those given by *self.options.members*. + """ + # set current namespace for finding members + self.env.autodoc_current_module = self.modname + if self.objpath: + self.env.autodoc_current_class = self.objpath[0] + + want_all = all_members or self.options.inherited_members or \ + self.options.members is ALL + # find out which members are documentable + members_check_module, members = self.get_object_members(want_all) + + # document non-skipped members + memberdocumenters = [] + for (mname, member, isattr) in self.filter_members(members, want_all): + classes = [cls for cls in AutoDirective._registry.itervalues() + if cls.can_document_member(member, mname, isattr, self)] + if not classes: + # don't know how to document this member + continue + # prefer the documenter with the highest priority + classes.sort(key=lambda cls: cls.priority) + # give explicitly separated module name, so that members + # of inner classes can be documented + full_mname = self.modname + '::' + \ + '.'.join(self.objpath + [mname]) + memberdocumenters.append( + classes[-1](self.directive, full_mname, self.indent)) + + if (self.options.member_order or self.env.config.autodoc_member_order) \ + == 'groupwise': + # sort by group; relies on stable sort to keep items in the + # same group sorted alphabetically + memberdocumenters.sort(key=lambda d: d.member_order) + + for documenter in memberdocumenters: + documenter.generate(all_members=True, + real_modname=self.real_modname, + check_module=members_check_module) + + # reset current objects self.env.autodoc_current_module = None self.env.autodoc_current_class = None + def generate(self, more_content=None, real_modname=None, + check_module=False, all_members=False): + """ + Generate reST for the object given by *self.name*, and possibly members. -def _auto_directive(dirname, arguments, options, content, lineno, - content_offset, block_text, state, state_machine): - what = dirname[4:] # strip "auto" - name = arguments[0] - genopt = Options() - members = options.get('members', []) - genopt.inherited_members = 'inherited-members' in options - if genopt.inherited_members and not members: - # :inherited-members: implies :members: - members = ['__all__'] - genopt.undoc_members = 'undoc-members' in options - genopt.show_inheritance = 'show-inheritance' in options - genopt.noindex = 'noindex' in options - genopt.synopsis = options.get('synopsis', '') - genopt.platform = options.get('platform', '') - genopt.deprecated = 'deprecated' in options + If *more_content* is given, include that content. If *real_modname* is + given, use that module name to find attribute docs. If *check_module* is + True, only generate if the object is defined in the module name it is + imported from. If *all_members* is True, document all members. + """ + if not self.parse_name(): + # need a module to import + self.directive.warn( + 'don\'t know which module to import for autodocumenting ' + '%r (try placing a "module" or "currentmodule" directive ' + 'in the document, or giving an explicit module name)' + % self.name) + return - generator = RstGenerator(genopt, state.document, lineno) - generator.generate(what, name, members, content) - if not generator.result: - return generator.warnings + # now, import the module and get object to document + if not self.import_object(): + return - # record all filenames as dependencies -- this will at least partially make - # automatic invalidation possible - for fn in generator.filename_set: - state.document.settings.env.note_dependency(fn) + # If there is no real module defined, figure out which to use. + # The real module is used in the module analyzer to look up the module + # where the attribute documentation would actually be found in. + # This is used for situations where you have a module that collects the + # functions and classes of internal submodules. + self.real_modname = real_modname or self.get_real_modname() - # use a custom reporter that correctly assigns lines to source and lineno - old_reporter = state.memo.reporter - state.memo.reporter = AutodocReporter(generator.result, state.memo.reporter) - if dirname == 'automodule': - node = nodes.section() - # hack around title style bookkeeping - surrounding_title_styles = state.memo.title_styles - surrounding_section_level = state.memo.section_level - state.memo.title_styles = [] - state.memo.section_level = 0 - state.nested_parse(generator.result, 0, node, match_titles=1) - state.memo.title_styles = surrounding_title_styles - state.memo.section_level = surrounding_section_level - else: - node = nodes.paragraph() - state.nested_parse(generator.result, 0, node) - state.memo.reporter = old_reporter - return generator.warnings + node.children + # try to also get a source code analyzer for attribute docs + try: + self.analyzer = ModuleAnalyzer.for_module(self.real_modname) + # parse right now, to get PycodeErrors on parsing + self.analyzer.parse() + except PycodeError, err: + # no source file -- e.g. for builtin and C modules + self.analyzer = None + else: + self.directive.filename_set.add(self.analyzer.srcname) -def auto_directive(*args, **kwds): - return _auto_directive(*args, **kwds) + # check __module__ of object (for members not given explicitly) + if check_module: + if not self.check_module(): + return -def automodule_directive(*args, **kwds): - return _auto_directive(*args, **kwds) + # make sure that the result starts with an empty line. This is + # necessary for some situations where another directive preprocesses + # reST and no starting newline is present + self.add_line(u'', '') -def autoclass_directive(*args, **kwds): - return _auto_directive(*args, **kwds) + # format the object's signature, if any + try: + sig = self.format_signature() + except Exception, err: + self.directive.warn('error while formatting signature for ' + '%s: %s' % (self.fullname, err)) + sig = '' + + # generate the directive header and options, if applicable + self.add_directive_header(sig) + self.add_line(u'', '<autodoc>') + + # e.g. the module directive doesn't have content + self.indent += self.content_indent + + # add all content (from docstrings, attribute docs etc.) + self.add_content(more_content) + + # document members, if possible + self.document_members(all_members) -def members_option(arg): - if arg is None: - return ['__all__'] - return [x.strip() for x in arg.split(',')] +class ModuleDocumenter(Documenter): + """ + Specialized Documenter subclass for modules. + """ + objtype = 'module' + content_indent = u'' + + option_spec = { + 'members': members_option, 'undoc-members': bool_option, + 'noindex': bool_option, 'inherited-members': bool_option, + 'show-inheritance': bool_option, 'synopsis': identity, + 'platform': identity, 'deprecated': bool_option, + 'member-order': identity, + } + + @classmethod + def can_document_member(cls, member, membername, isattr, parent): + # don't document submodules automatically + return False + + def resolve_name(self, modname, parents, path, base): + if modname is not None: + self.directive.warn('"::" in automodule name doesn\'t make sense') + return (path or '') + base, [] + + def parse_name(self): + ret = Documenter.parse_name(self) + if self.args or self.retann: + self.directive.warn('signature arguments or return annotation ' + 'given for automodule %s' % self.fullname) + return ret + + def add_directive_header(self, sig): + Documenter.add_directive_header(self, sig) + + # add some module-specific options + if self.options.synopsis: + self.add_line( + u' :synopsis: ' + self.options.synopsis, '<autodoc>') + if self.options.platform: + self.add_line( + u' :platform: ' + self.options.platform, '<autodoc>') + if self.options.deprecated: + self.add_line(u' :deprecated:', '<autodoc>') + + def get_object_members(self, want_all): + if want_all: + if not hasattr(self.object, '__all__'): + # for implicit module members, check __module__ to avoid + # documenting imported objects + return True, inspect.getmembers(self.object) + else: + memberlist = self.object.__all__ + else: + memberlist = self.options.members or [] + ret = [] + for mname in memberlist: + try: + ret.append((mname, getattr(self.object, mname))) + except AttributeError: + self.directive.warn('missing attribute mentioned in :members: ' + 'or __all__: module %s, attribute %s' % + (self.object.__name__, mname)) + return False, ret + + +class ModuleLevelDocumenter(Documenter): + """ + Specialized Documenter subclass for objects on module level (functions, + classes, data/constants). + """ + def resolve_name(self, modname, parents, path, base): + if modname is None: + if path: + modname = path.rstrip('.') + else: + # if documenting a toplevel object without explicit module, + # it can be contained in another auto directive ... + if hasattr(self.env, 'autodoc_current_module'): + modname = self.env.autodoc_current_module + # ... or in the scope of a module directive + if not modname: + modname = self.env.currmodule + # ... else, it stays None, which means invalid + return modname, parents + [base] + + +class ClassLevelDocumenter(Documenter): + """ + Specialized Documenter subclass for objects on class level (methods, + attributes). + """ + def resolve_name(self, modname, parents, path, base): + if modname is None: + if path: + mod_cls = path.rstrip('.') + else: + mod_cls = None + # if documenting a class-level object without path, + # there must be a current class, either from a parent + # auto directive ... + if hasattr(self.env, 'autodoc_current_class'): + mod_cls = self.env.autodoc_current_class + # ... or from a class directive + if mod_cls is None: + mod_cls = self.env.currclass + # ... if still None, there's no way to know + if mod_cls is None: + return None, [] + modname, cls = rpartition(mod_cls, '.') + parents = [cls] + # if the module name is still missing, get it like above + if not modname and hasattr(self.env, 'autodoc_current_module'): + modname = self.env.autodoc_current_module + if not modname: + modname = self.env.currmodule + # ... else, it stays None, which means invalid + return modname, parents + [base] + + +class FunctionDocumenter(ModuleLevelDocumenter): + """ + Specialized Documenter subclass for functions. + """ + objtype = 'function' + member_order = 30 + + @classmethod + def can_document_member(cls, member, membername, isattr, parent): + return isinstance(member, (FunctionType, BuiltinFunctionType)) + + def format_args(self): + if inspect.isbuiltin(self.object) or \ + inspect.ismethoddescriptor(self.object): + # can never get arguments of a C function or method + return None + try: + argspec = inspect.getargspec(self.object) + except TypeError: + # if a class should be documented as function (yay duck + # typing) we try to use the constructor signature as function + # signature without the first argument. + try: + argspec = inspect.getargspec(self.object.__new__) + except TypeError: + argspec = inspect.getargspec(self.object.__init__) + if argspec[0]: + del argspec[0][0] + return inspect.formatargspec(*argspec) + + def document_members(self, all_members=False): + pass + + +class ClassDocumenter(ModuleLevelDocumenter): + """ + Specialized Documenter subclass for classes. + """ + objtype = 'class' + member_order = 20 + option_spec = { + 'members': members_option, 'undoc-members': bool_option, + 'noindex': bool_option, 'inherited-members': bool_option, + 'show-inheritance': bool_option, 'member-order': identity, + } + + @classmethod + def can_document_member(cls, member, membername, isattr, parent): + return isinstance(member, (type, ClassType)) + + def import_object(self): + ret = ModuleLevelDocumenter.import_object(self) + # if the class is documented under another name, document it + # as data/attribute + if ret: + self.doc_as_attr = (self.objpath[-1] != self.object.__name__) + return ret + + def format_args(self): + args = None + # for classes, the relevant signature is the __init__ method's + initmeth = self.get_attr(self.object, '__init__', None) + # classes without __init__ method, default __init__ or + # __init__ written in C? + if initmeth is None or initmeth is object.__init__ or not \ + (inspect.ismethod(initmeth) or inspect.isfunction(initmeth)): + return None + argspec = inspect.getargspec(initmeth) + if argspec[0] and argspec[0][0] in ('cls', 'self'): + del argspec[0][0] + return inspect.formatargspec(*argspec) + + def format_signature(self): + if self.doc_as_attr: + return '' + return ModuleLevelDocumenter.format_signature(self) + + def add_directive_header(self, sig): + if self.doc_as_attr: + self.directivetype = 'attribute' + Documenter.add_directive_header(self, sig) + + # add inheritance info, if wanted + if not self.doc_as_attr and self.options.show_inheritance: + self.add_line(u'', '<autodoc>') + if len(self.object.__bases__): + bases = [b.__module__ == '__builtin__' and + u':class:`%s`' % b.__name__ or + u':class:`%s.%s`' % (b.__module__, b.__name__) + for b in self.object.__bases__] + self.add_line(_(u' Bases: %s') % ', '.join(bases), + '<autodoc>') + + def get_doc(self, encoding=None): + content = self.env.config.autoclass_content + + docstrings = [] + docstring = self.get_attr(self.object, '__doc__', None) + if docstring: + docstrings.append(docstring) + + # for classes, what the "docstring" is can be controlled via a + # config value; the default is only the class docstring + if content in ('both', 'init'): + initdocstring = self.get_attr( + self.get_attr(self.object, '__init__', None), '__doc__') + # for new-style classes, no __init__ means default __init__ + if initdocstring == object.__init__.__doc__: + initdocstring = None + if initdocstring: + if content == 'init': + docstrings = [initdocstring] + else: + docstrings.append(initdocstring) + + return [prepare_docstring(force_decode(docstring, encoding)) + for docstring in docstrings] + + def add_content(self, more_content, no_docstring=False): + if self.doc_as_attr: + content = ViewList( + [_('alias of :class:`%s`') % self.object.__name__], source='') + ModuleLevelDocumenter.add_content(self, content, no_docstring=True) + else: + ModuleLevelDocumenter.add_content(self, more_content) + + def document_members(self, all_members=False): + if self.doc_as_attr: + return + ModuleLevelDocumenter.document_members(self, all_members) + + +class ExceptionDocumenter(ClassDocumenter): + """ + Specialized ClassDocumenter subclass for exceptions. + """ + objtype = 'exception' + member_order = 10 + + # needs a higher priority than ClassDocumenter + priority = 10 + + @classmethod + def can_document_member(cls, member, membername, isattr, parent): + return isinstance(member, (type, ClassType)) and \ + issubclass(member, base_exception) + + +class DataDocumenter(ModuleLevelDocumenter): + """ + Specialized Documenter subclass for data items. + """ + objtype = 'data' + member_order = 40 + + @classmethod + def can_document_member(cls, member, membername, isattr, parent): + return isinstance(parent, ModuleDocumenter) and isattr + + def document_members(self, all_members=False): + pass + + +class MethodDocumenter(ClassLevelDocumenter): + """ + Specialized Documenter subclass for methods (normal, static and class). + """ + objtype = 'method' + member_order = 50 + + @classmethod + def can_document_member(cls, member, membername, isattr, parent): + # other attributes are recognized via the module analyzer + return inspect.isroutine(member) and \ + not isinstance(parent, ModuleDocumenter) + + def import_object(self): + ret = ClassLevelDocumenter.import_object(self) + if isinstance(self.object, classmethod) or \ + (isinstance(self.object, MethodType) and + self.object.im_self is not None): + self.directivetype = 'classmethod' + # document class and static members before ordinary ones + self.member_order = self.member_order - 1 + elif isinstance(self.object, FunctionType) or \ + (isinstance(self.object, BuiltinFunctionType) and + self.object.__self__ is not None): + self.directivetype = 'staticmethod' + # document class and static members before ordinary ones + self.member_order = self.member_order - 1 + else: + self.directivetype = 'method' + return ret + + def format_args(self): + if inspect.isbuiltin(self.object) or \ + inspect.ismethoddescriptor(self.object): + # can never get arguments of a C function or method + return None + argspec = inspect.getargspec(self.object) + if argspec[0] and argspec[0][0] in ('cls', 'self'): + del argspec[0][0] + return inspect.formatargspec(*argspec) + + def document_members(self, all_members=False): + pass + + +class AttributeDocumenter(ClassLevelDocumenter): + """ + Specialized Documenter subclass for attributes. + """ + objtype = 'attribute' + member_order = 60 + + @classmethod + def can_document_member(cls, member, membername, isattr, parent): + return (isdescriptor(member) and not + isinstance(member, (FunctionType, BuiltinFunctionType))) \ + or (not isinstance(parent, ModuleDocumenter) and isattr) + + def document_members(self, all_members=False): + pass + + +class AutoDirective(Directive): + """ + The AutoDirective class is used for all autodoc directives. It dispatches + most of the work to one of the Documenters, which it selects through its + *_registry* dictionary. + + The *_special_attrgetters* attribute is used to customize ``getattr()`` + calls that the Documenters make; its entries are of the form ``type: + getattr_function``. + + Note: When importing an object, all items along the import chain are + accessed using the descendant's *_special_attrgetters*, thus this + dictionary should include all necessary functions for accessing + attributes of the parents. + """ + # a registry of objtype -> documenter class + _registry = {} + + # a registry of type -> getattr function + _special_attrgetters = {} + + # standard docutils directive settings + has_content = True + required_arguments = 1 + optional_arguments = 0 + final_argument_whitespace = True + # allow any options to be passed; the options are parsed further + # by the selected Documenter + option_spec = DefDict(identity) + + def warn(self, msg): + self.warnings.append(self.reporter.warning(msg, line=self.lineno)) + + def run(self): + self.filename_set = set() # a set of dependent filenames + self.reporter = self.state.document.reporter + self.env = self.state.document.settings.env + self.warnings = [] + self.result = ViewList() + + # find out what documenter to call + objtype = self.name[4:] + doc_class = self._registry[objtype] + # process the options with the selected documenter's option_spec + self.genopt = Options(assemble_option_dict( + self.options.items(), doc_class.option_spec)) + # generate the output + documenter = doc_class(self, self.arguments[0]) + documenter.generate(more_content=self.content) + if not self.result: + return self.warnings + + # record all filenames as dependencies -- this will at least + # partially make automatic invalidation possible + for fn in self.filename_set: + self.env.note_dependency(fn) + + # use a custom reporter that correctly assigns lines to source + # filename/description and lineno + old_reporter = self.state.memo.reporter + self.state.memo.reporter = AutodocReporter(self.result, + self.state.memo.reporter) + + if self.name == 'automodule': + node = nodes.section() + # necessary so that the child nodes get the right source/line set + node.document = self.state.document + nested_parse_with_titles(self.state, self.result, node) + else: + node = nodes.paragraph() + node.document = self.state.document + self.state.nested_parse(self.result, 0, node) + self.state.memo.reporter = old_reporter + return self.warnings + node.children + + +def add_documenter(cls): + """Register a new Documenter.""" + if not issubclass(cls, Documenter): + raise ExtensionError('autodoc documenter %r must be a subclass ' + 'of Documenter' % cls) + # actually, it should be possible to override Documenters + #if cls.objtype in AutoDirective._registry: + # raise ExtensionError('autodoc documenter for %r is already ' + # 'registered' % cls.objtype) + AutoDirective._registry[cls.objtype] = cls def setup(app): - mod_options = {'members': members_option, 'undoc-members': directives.flag, - 'noindex': directives.flag, 'inherited-members': directives.flag, - 'show-inheritance': directives.flag, 'synopsis': lambda x: x, - 'platform': lambda x: x, 'deprecated': directives.flag} - cls_options = {'members': members_option, 'undoc-members': directives.flag, - 'noindex': directives.flag, 'inherited-members': directives.flag, - 'show-inheritance': directives.flag} - app.add_directive('automodule', automodule_directive, - 1, (1, 0, 1), **mod_options) - app.add_directive('autoclass', autoclass_directive, - 1, (1, 0, 1), **cls_options) - app.add_directive('autoexception', autoclass_directive, - 1, (1, 0, 1), **cls_options) - app.add_directive('autofunction', auto_directive, 1, (1, 0, 1), - noindex=directives.flag) - app.add_directive('automethod', auto_directive, 1, (1, 0, 1), - noindex=directives.flag) - app.add_directive('autoattribute', auto_directive, 1, (1, 0, 1), - noindex=directives.flag) - # deprecated: remove in some future version. - app.add_config_value('automodule_skip_lines', 0, True) + app.add_autodocumenter(ModuleDocumenter) + app.add_autodocumenter(ClassDocumenter) + app.add_autodocumenter(ExceptionDocumenter) + app.add_autodocumenter(DataDocumenter) + app.add_autodocumenter(FunctionDocumenter) + app.add_autodocumenter(MethodDocumenter) + app.add_autodocumenter(AttributeDocumenter) + app.add_config_value('autoclass_content', 'class', True) + app.add_config_value('autodoc_member_order', 'alphabetic', True) app.add_event('autodoc-process-docstring') app.add_event('autodoc-process-signature') app.add_event('autodoc-skip-member') diff --git a/sphinx/ext/coverage.py b/sphinx/ext/coverage.py index f03dbc1e2..964e58eec 100644 --- a/sphinx/ext/coverage.py +++ b/sphinx/ext/coverage.py @@ -6,8 +6,8 @@ Check Python modules and C API for coverage. Mostly written by Josip Dzolonga for the Google Highly Open Participation contest. - :copyright: 2008 by Josip Dzolonga, Georg Brandl. - :license: BSD. + :copyright: Copyright 2007-2009 by the Sphinx team, see AUTHORS. + :license: BSD, see LICENSE for details. """ import re @@ -16,7 +16,7 @@ import inspect import cPickle as pickle from os import path -from sphinx.builder import Builder +from sphinx.builders import Builder # utility @@ -53,17 +53,17 @@ class CoverageBuilder(Builder): self.c_ignorexps = {} for (name, exps) in self.config.coverage_ignore_c_items.iteritems(): - self.c_ignorexps[name] = compile_regex_list('coverage_ignore_c_items', - exps, self.warn) - self.mod_ignorexps = compile_regex_list('coverage_ignore_modules', - self.config.coverage_ignore_modules, - self.warn) - self.cls_ignorexps = compile_regex_list('coverage_ignore_classes', - self.config.coverage_ignore_classes, - self.warn) - self.fun_ignorexps = compile_regex_list('coverage_ignore_functions', - self.config.coverage_ignore_functions, - self.warn) + self.c_ignorexps[name] = compile_regex_list( + 'coverage_ignore_c_items', exps, self.warn) + self.mod_ignorexps = compile_regex_list( + 'coverage_ignore_modules', self.config.coverage_ignore_modules, + self.warn) + self.cls_ignorexps = compile_regex_list( + 'coverage_ignore_classes', self.config.coverage_ignore_classes, + self.warn) + self.fun_ignorexps = compile_regex_list( + 'coverage_ignore_functions', self.config.coverage_ignore_functions, + self.warn) def get_outdated_docs(self): return 'coverage overview' @@ -128,7 +128,8 @@ class CoverageBuilder(Builder): try: mod = __import__(mod_name, fromlist=['foo']) except ImportError, err: - self.warn('module %s could not be imported: %s' % (mod_name, err)) + self.warn('module %s could not be imported: %s' % + (mod_name, err)) self.py_undoc[mod_name] = {'error': err} continue @@ -168,7 +169,8 @@ class CoverageBuilder(Builder): attrs = [] - for attr_name, attr in inspect.getmembers(obj, inspect.ismethod): + for attr_name, attr in inspect.getmembers( + obj, inspect.ismethod): if attr_name[0] == '_': # starts with an underscore, ignore it continue diff --git a/sphinx/ext/doctest.py b/sphinx/ext/doctest.py index badd50ffd..51463661a 100644 --- a/sphinx/ext/doctest.py +++ b/sphinx/ext/doctest.py @@ -6,13 +6,14 @@ Mimic doctest by automatically executing code snippets and checking their results. - :copyright: 2008 by Georg Brandl. - :license: BSD. + :copyright: Copyright 2007-2009 by the Sphinx team, see AUTHORS. + :license: BSD, see LICENSE for details. """ import re import sys import time +import codecs import StringIO from os import path # circumvent relative import @@ -21,7 +22,8 @@ doctest = __import__('doctest') from docutils import nodes from docutils.parsers.rst import directives -from sphinx.builder import Builder +from sphinx.builders import Builder +from sphinx.util.compat import Directive from sphinx.util.console import bold blankline_re = re.compile(r'^\s*<BLANKLINE>', re.MULTILINE) @@ -29,63 +31,77 @@ doctestopt_re = re.compile(r'#\s*doctest:.+$', re.MULTILINE) # set up the necessary directives -def test_directive(name, arguments, options, content, lineno, - content_offset, block_text, state, state_machine): - # use ordinary docutils nodes for test code: they get special attributes - # so that our builder recognizes them, and the other builders are happy. - code = '\n'.join(content) - test = None - if name == 'doctest': - if '<BLANKLINE>' in code: - # convert <BLANKLINE>s to ordinary blank lines for presentation - test = code - code = blankline_re.sub('', code) - if doctestopt_re.search(code): - if not test: +class TestDirective(Directive): + """ + Base class for doctest-related directives. + """ + + has_content = True + required_arguments = 0 + optional_arguments = 1 + final_argument_whitespace = True + + def run(self): + # use ordinary docutils nodes for test code: they get special attributes + # so that our builder recognizes them, and the other builders are happy. + code = '\n'.join(self.content) + test = None + if self.name == 'doctest': + if '<BLANKLINE>' in code: + # convert <BLANKLINE>s to ordinary blank lines for presentation test = code - code = doctestopt_re.sub('', code) - nodetype = nodes.literal_block - if name == 'testsetup' or 'hide' in options: - nodetype = nodes.comment - if arguments: - groups = [x.strip() for x in arguments[0].split(',')] - else: - groups = ['default'] - node = nodetype(code, code, testnodetype=name, groups=groups) - node.line = lineno - if test is not None: - # only save if it differs from code - node['test'] = test - if name == 'testoutput': - # don't try to highlight output - node['language'] = 'none' - node['options'] = {} - if name in ('doctest', 'testoutput') and 'options' in options: - # parse doctest-like output comparison flags - option_strings = options['options'].replace(',', ' ').split() - for option in option_strings: - if (option[0] not in '+-' or option[1:] not in - doctest.OPTIONFLAGS_BY_NAME): - # XXX warn? - continue - flag = doctest.OPTIONFLAGS_BY_NAME[option[1:]] - node['options'][flag] = (option[0] == '+') - return [node] + code = blankline_re.sub('', code) + if doctestopt_re.search(code): + if not test: + test = code + code = doctestopt_re.sub('', code) + nodetype = nodes.literal_block + if self.name == 'testsetup' or 'hide' in self.options: + nodetype = nodes.comment + if self.arguments: + groups = [x.strip() for x in self.arguments[0].split(',')] + else: + groups = ['default'] + node = nodetype(code, code, testnodetype=self.name, groups=groups) + node.line = self.lineno + if test is not None: + # only save if it differs from code + node['test'] = test + if self.name == 'testoutput': + # don't try to highlight output + node['language'] = 'none' + node['options'] = {} + if self.name in ('doctest', 'testoutput') and 'options' in self.options: + # parse doctest-like output comparison flags + option_strings = self.options['options'].replace(',', ' ').split() + for option in option_strings: + if (option[0] not in '+-' or option[1:] not in + doctest.OPTIONFLAGS_BY_NAME): + # XXX warn? + continue + flag = doctest.OPTIONFLAGS_BY_NAME[option[1:]] + node['options'][flag] = (option[0] == '+') + return [node] -# need to have individual functions for each directive due to different -# options they accept +class TestsetupDirective(TestDirective): + option_spec = {} -def testsetup_directive(*args): - return test_directive(*args) +class DoctestDirective(TestDirective): + option_spec = { + 'hide': directives.flag, + 'options': directives.unchanged, + } -def doctest_directive(*args): - return test_directive(*args) +class TestcodeDirective(TestDirective): + option_spec = { + 'hide': directives.flag, + } -def testcode_directive(*args): - return test_directive(*args) - -def testoutput_directive(*args): - return test_directive(*args) +class TestoutputDirective(TestDirective): + option_spec = { + 'hide': directives.flag, + 'options': directives.unchanged, + } parser = doctest.DocTestParser() @@ -98,9 +114,12 @@ class TestGroup(object): self.setup = [] self.tests = [] - def add_code(self, code): + def add_code(self, code, prepend=False): if code.type == 'testsetup': - self.setup.append(code) + if prepend: + self.setup.insert(0, code) + else: + self.setup.append(code) elif code.type == 'doctest': self.tests.append([code]) elif code.type == 'testcode': @@ -169,7 +188,8 @@ class DocTestBuilder(Builder): date = time.strftime('%Y-%m-%d %H:%M:%S') - self.outfile = file(path.join(self.outdir, 'output.txt'), 'w') + self.outfile = codecs.open(path.join(self.outdir, 'output.txt'), + 'w', encoding='utf-8') self.outfile.write('''\ Results of doctest builder run on %s ==================================%s @@ -179,6 +199,12 @@ Results of doctest builder run on %s self.info(text, nonl=True) self.outfile.write(text) + def _warn_out(self, text): + self.info(text, nonl=True) + if self.app.quiet: + self.warn(text) + self.outfile.write(text) + def get_target_uri(self, docname, typ=None): return '' @@ -200,6 +226,9 @@ Doctest summary self.setup_failures, s(self.setup_failures))) self.outfile.close() + if self.total_failures or self.setup_failures: + self.app.statuscode = 1 + sys.path[0:0] = self.config.doctest_path def write(self, build_docnames, updated_docnames, method='update'): @@ -229,8 +258,12 @@ Doctest summary return isinstance(node, (nodes.literal_block, nodes.comment)) \ and node.has_key('testnodetype') for node in doctree.traverse(condition): - code = TestCode(node.has_key('test') and node['test'] or node.astext(), - type=node.get('testnodetype', 'doctest'), + source = node.has_key('test') and node['test'] or node.astext() + if not source: + self.warn('no code/output in %s block at %s:%s' % + (node.get('testnodetype', 'doctest'), + self.env.doc2path(docname), node.line)) + code = TestCode(source, type=node.get('testnodetype', 'doctest'), lineno=node.line, options=node.get('options')) node_groups = node.get('groups', ['default']) if '*' in node_groups: @@ -243,10 +276,16 @@ Doctest summary for code in add_to_all_groups: for group in groups.itervalues(): group.add_code(code) + if self.config.doctest_global_setup: + code = TestCode(self.config.doctest_global_setup, + 'testsetup', lineno=0) + for group in groups.itervalues(): + group.add_code(code, prepend=True) if not groups: return - self._out('\nDocument: %s\n----------%s\n' % (docname, '-'*len(docname))) + self._out('\nDocument: %s\n----------%s\n' % + (docname, '-'*len(docname))) for group in groups.itervalues(): self.test_group(group, self.env.doc2path(docname, base=None)) # Separately count results from setup code @@ -265,7 +304,8 @@ Doctest summary ns = {} examples = [] for setup in group.setup: - examples.append(doctest.Example(setup.code, '', lineno=setup.lineno)) + examples.append(doctest.Example(setup.code, '', + lineno=setup.lineno)) if examples: # simulate a doctest with the setup code setup_doctest = doctest.DocTest(examples, {}, @@ -274,7 +314,7 @@ Doctest summary setup_doctest.globs = ns old_f = self.setup_runner.failures self.type = 'exec' # the snippet may contain multiple statements - self.setup_runner.run(setup_doctest, out=self._out, + self.setup_runner.run(setup_doctest, out=self._warn_out, clear_globs=False) if self.setup_runner.failures > old_f: # don't run the group @@ -284,8 +324,6 @@ Doctest summary test = parser.get_doctest(code[0].code, {}, group.name, filename, code[0].lineno) if not test.examples: - self._out('WARNING: no examples in doctest block at ' - + filename + ', line %s\n' % code[0].lineno) continue for example in test.examples: # apply directive's comparison options @@ -307,18 +345,16 @@ Doctest summary # DocTest.__init__ copies the globs namespace, which we don't want test.globs = ns # also don't clear the globs namespace after running the doctest - self.test_runner.run(test, out=self._out, clear_globs=False) + self.test_runner.run(test, out=self._warn_out, clear_globs=False) def setup(app): - app.add_directive('testsetup', testsetup_directive, 1, (0, 1, 1)) - app.add_directive('doctest', doctest_directive, 1, (0, 1, 1), - hide=directives.flag, options=directives.unchanged) - app.add_directive('testcode', testcode_directive, 1, (0, 1, 1), - hide=directives.flag) - app.add_directive('testoutput', testoutput_directive, 1, (0, 1, 1), - hide=directives.flag, options=directives.unchanged) + app.add_directive('testsetup', TestsetupDirective) + app.add_directive('doctest', DoctestDirective) + app.add_directive('testcode', TestcodeDirective) + app.add_directive('testoutput', TestoutputDirective) app.add_builder(DocTestBuilder) # this config value adds to sys.path app.add_config_value('doctest_path', [], False) app.add_config_value('doctest_test_doctest_blocks', 'default', False) + app.add_config_value('doctest_global_setup', '', False) diff --git a/sphinx/ext/graphviz.py b/sphinx/ext/graphviz.py new file mode 100644 index 000000000..d51e2ed5f --- /dev/null +++ b/sphinx/ext/graphviz.py @@ -0,0 +1,185 @@ +# -*- coding: utf-8 -*- +""" + sphinx.ext.graphviz + ~~~~~~~~~~~~~~~~~~~ + + Allow graphviz-formatted graphs to be included in Sphinx-generated + documents inline. + + :copyright: Copyright 2007-2009 by the Sphinx team, see AUTHORS. + :license: BSD, see LICENSE for details. +""" + +import os +import re +import sys +import posixpath +from os import path +from subprocess import Popen, PIPE +try: + from hashlib import sha1 as sha +except ImportError: + from sha import sha + +from docutils import nodes + +from sphinx.errors import SphinxError +from sphinx.util import ensuredir +from sphinx.util.compat import Directive + + +mapname_re = re.compile(r'<map id="(.*?)"') + + +class GraphvizError(SphinxError): + category = 'Graphviz error' + + +class graphviz(nodes.General, nodes.Element): + pass + + +class Graphviz(Directive): + """ + Directive to insert arbitrary dot markup. + """ + has_content = True + required_arguments = 0 + optional_arguments = 0 + final_argument_whitespace = False + option_spec = {} + + def run(self): + node = graphviz() + node['code'] = '\n'.join(self.content) + node['options'] = [] + return [node] + + +class GraphvizSimple(Directive): + """ + Directive to insert arbitrary dot markup. + """ + has_content = True + required_arguments = 1 + optional_arguments = 0 + final_argument_whitespace = False + option_spec = {} + + def run(self): + node = graphviz() + node['code'] = '%s %s {\n%s\n}\n' % \ + (self.name, self.arguments[0], '\n'.join(self.content)) + node['options'] = [] + return [node] + + +def render_dot(self, code, options, format, prefix='graphviz'): + """ + Render graphviz code into a PNG or PDF output file. + """ + hashkey = code.encode('utf-8') + str(options) + \ + str(self.builder.config.graphviz_dot_args) + fname = '%s-%s.%s' % (prefix, sha(hashkey).hexdigest(), format) + if hasattr(self.builder, 'imgpath'): + # HTML + relfn = posixpath.join(self.builder.imgpath, fname) + outfn = path.join(self.builder.outdir, '_images', fname) + else: + # LaTeX + relfn = fname + outfn = path.join(self.builder.outdir, fname) + + if path.isfile(outfn): + return relfn + + if hasattr(self.builder, '_graphviz_warned_dot') or \ + hasattr(self.builder, '_graphviz_warned_ps2pdf'): + return None + + ensuredir(path.dirname(outfn)) + + dot_args = [self.builder.config.graphviz_dot] + dot_args.extend(self.builder.config.graphviz_dot_args) + dot_args.extend(options) + dot_args.extend(['-T' + format, '-o' + outfn]) + if format == 'png': + dot_args.extend(['-Tcmapx', '-o%s.map' % outfn]) + try: + p = Popen(dot_args, stdout=PIPE, stdin=PIPE, stderr=PIPE) + except OSError, err: + if err.errno != 2: # No such file or directory + raise + self.builder.warn('dot command %r cannot be run (needed for graphviz ' + 'output), check the graphviz_dot setting' % + self.builder.config.graphviz_dot) + self.builder._graphviz_warned_dot = True + return None + # graphviz expects UTF-8 by default + if isinstance(code, unicode): + code = code.encode('utf-8') + stdout, stderr = p.communicate(code) + if p.returncode != 0: + raise GraphvizError('dot exited with error:\n[stderr]\n%s\n' + '[stdout]\n%s' % (stderr, stdout)) + return relfn + + +def render_dot_html(self, node, code, options, prefix='graphviz', imgcls=None): + try: + fname = render_dot(self, code, options, 'png', prefix) + except GraphvizError, exc: + self.builder.warn('dot code %r: ' % code + str(exc)) + raise nodes.SkipNode + + self.body.append(self.starttag(node, 'p', CLASS='graphviz')) + if fname is None: + self.body.append(self.encode(code)) + else: + mapfile = open(path.join(self.builder.outdir, fname) + '.map', 'rb') + imgmap = mapfile.readlines() + 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)) + 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) + self.body.append('</p>\n') + raise nodes.SkipNode + + +def html_visit_graphviz(self, node): + render_dot_html(self, node, node['code'], node['options']) + + +def render_dot_latex(self, node, code, options, prefix='graphviz'): + try: + fname = render_dot(self, code, options, 'pdf', prefix) + except GraphvizError, exc: + self.builder.warn('dot code %r: ' % code + str(exc)) + raise nodes.SkipNode + + if fname is not None: + self.body.append('\\includegraphics{%s}' % fname) + raise nodes.SkipNode + + +def latex_visit_graphviz(self, node): + render_dot_latex(self, node, node['code'], node['options']) + +def setup(app): + app.add_node(graphviz, + html=(html_visit_graphviz, None), + latex=(latex_visit_graphviz, None)) + app.add_directive('graphviz', Graphviz) + app.add_directive('graph', GraphvizSimple) + app.add_directive('digraph', GraphvizSimple) + app.add_config_value('graphviz_dot', 'dot', 'html') + app.add_config_value('graphviz_dot_args', [], 'html') diff --git a/sphinx/ext/ifconfig.py b/sphinx/ext/ifconfig.py index 204178f2f..90cd2b2c4 100644 --- a/sphinx/ext/ifconfig.py +++ b/sphinx/ext/ifconfig.py @@ -13,26 +13,36 @@ This stuff is only included in the built docs for unstable versions. The argument for ``ifconfig`` is a plain Python expression, evaluated in the - namespace of the project configuration (that is, all variables from ``conf.py`` - are available.) + namespace of the project configuration (that is, all variables from + ``conf.py`` are available.) - :copyright: 2008 by Georg Brandl. - :license: BSD. + :copyright: Copyright 2007-2009 by the Sphinx team, see AUTHORS. + :license: BSD, see LICENSE for details. """ from docutils import nodes +from sphinx.util.compat import Directive + class ifconfig(nodes.Element): pass -def ifconfig_directive(name, arguments, options, content, lineno, - content_offset, block_text, state, state_machine): - node = ifconfig() - node.line = lineno - node['expr'] = arguments[0] - state.nested_parse(content, content_offset, node) - return [node] +class IfConfig(Directive): + + has_content = True + required_arguments = 1 + optional_arguments = 0 + final_argument_whitespace = True + option_spec = {} + + def run(self): + node = ifconfig() + node.document = self.state.document + node.line = self.lineno + node['expr'] = self.arguments[0] + self.state.nested_parse(self.content, self.content_offset, node) + return [node] def process_ifconfig_nodes(app, doctree, docname): @@ -58,5 +68,5 @@ def process_ifconfig_nodes(app, doctree, docname): def setup(app): app.add_node(ifconfig) - app.add_directive('ifconfig', ifconfig_directive, 1, (1, 0, 1)) + app.add_directive('ifconfig', IfConfig) app.connect('doctree-resolved', process_ifconfig_nodes) diff --git a/sphinx/ext/inheritance_diagram.py b/sphinx/ext/inheritance_diagram.py new file mode 100644 index 000000000..8183359d4 --- /dev/null +++ b/sphinx/ext/inheritance_diagram.py @@ -0,0 +1,367 @@ +""" + sphinx.ext.inheritance_diagram + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + Defines a docutils directive for inserting inheritance diagrams. + + Provide the directive with one or more classes or modules (separated + by whitespace). For modules, all of the classes in that module will + be used. + + Example:: + + Given the following classes: + + class A: pass + class B(A): pass + class C(A): pass + class D(B, C): pass + class E(B): pass + + .. inheritance-diagram: D E + + Produces a graph like the following: + + A + / \ + B C + / \ / + E D + + 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. + :license: BSD, see LICENSE for details. +""" + +import os +import re +import sys +import inspect +import subprocess +try: + from hashlib import md5 +except ImportError: + from md5 import md5 + +from docutils import nodes +from docutils.parsers.rst import directives + +from sphinx.roles import xfileref_role +from sphinx.ext.graphviz import render_dot_html, render_dot_latex +from sphinx.util.compat import Directive + + +class_sig_re = re.compile(r'''^([\w.]*\.)? # module names + (\w+) \s* $ # class/final module name + ''', re.VERBOSE) + + +class InheritanceException(Exception): + pass + + +class InheritanceGraph(object): + """ + Given a list of classes, determines the set of classes that they inherit + from all the way to the root "object", and then is able to generate a + graphviz dot graph from them. + """ + def __init__(self, class_names, currmodule, show_builtins=False): + """ + *class_names* is a list of child classes to show bases from. + + If *show_builtins* is True, then Python builtins will be shown + in the graph. + """ + self.class_names = class_names + self.classes = self._import_classes(class_names, currmodule) + self.all_classes = self._all_classes(self.classes) + if len(self.all_classes) == 0: + raise InheritanceException('No classes found for ' + 'inheritance diagram') + self.show_builtins = show_builtins + + def _import_class_or_module(self, name, currmodule): + """ + Import a class using its fully-qualified *name*. + """ + try: + path, base = class_sig_re.match(name).groups() + except ValueError: + raise InheritanceException('Invalid class or module %r specified ' + 'for inheritance diagram' % name) + + fullname = (path or '') + base + path = (path and path.rstrip('.') or '') + + # two possibilities: either it is a module, then import it + try: + module = __import__(fullname) + todoc = sys.modules[fullname] + except ImportError: + # else it is a class, then import the module + if not path: + if currmodule: + # try the current module + path = currmodule + else: + raise InheritanceException( + 'Could not import class %r specified for ' + 'inheritance diagram' % base) + try: + module = __import__(path) + todoc = getattr(sys.modules[path], base) + except (ImportError, AttributeError): + raise InheritanceException( + 'Could not import class or module %r specified for ' + 'inheritance diagram' % (path + '.' + base)) + + # If a class, just return it + if inspect.isclass(todoc): + return [todoc] + elif inspect.ismodule(todoc): + classes = [] + for cls in todoc.__dict__.values(): + if inspect.isclass(cls) and cls.__module__ == todoc.__name__: + classes.append(cls) + return classes + raise InheritanceException('%r specified for inheritance diagram is ' + 'not a class or module' % name) + + def _import_classes(self, class_names, currmodule): + """ + Import a list of classes. + """ + classes = [] + for name in class_names: + classes.extend(self._import_class_or_module(name, currmodule)) + return classes + + def _all_classes(self, classes): + """ + Return a list of all classes that are ancestors of *classes*. + """ + all_classes = {} + + def recurse(cls): + all_classes[cls] = None + for c in cls.__bases__: + if c not in all_classes: + recurse(c) + + for cls in classes: + recurse(cls) + + return all_classes.keys() + + def class_name(self, cls, parts=0): + """ + Given a class object, return a fully-qualified name. This + works for things I've tested in matplotlib so far, but may not + be completely general. + """ + module = cls.__module__ + if module == '__builtin__': + fullname = cls.__name__ + else: + fullname = '%s.%s' % (module, cls.__name__) + if parts == 0: + return fullname + name_parts = fullname.split('.') + return '.'.join(name_parts[-parts:]) + + def get_all_class_names(self): + """ + Get all of the class names involved in the graph. + """ + return [self.class_name(x) for x in self.all_classes] + + # These are the default attrs for graphviz + default_graph_attrs = { + 'rankdir': 'LR', + 'size': '"8.0, 12.0"', + } + default_node_attrs = { + 'shape': 'box', + 'fontsize': 10, + 'height': 0.25, + 'fontname': 'Vera Sans, DejaVu Sans, Liberation Sans, ' + 'Arial, Helvetica, sans', + 'style': '"setlinewidth(0.5)"', + } + default_edge_attrs = { + 'arrowsize': 0.5, + 'style': '"setlinewidth(0.5)"', + } + + def _format_node_attrs(self, attrs): + return ','.join(['%s=%s' % x for x in attrs.items()]) + + def _format_graph_attrs(self, attrs): + return ''.join(['%s=%s;\n' % x for x in attrs.items()]) + + def generate_dot(self, name, parts=0, urls={}, env=None, + graph_attrs={}, node_attrs={}, edge_attrs={}): + """ + Generate a graphviz dot graph from the classes that + were passed in to __init__. + + *name* is the name of the graph. + + *urls* is a dictionary mapping class names to HTTP URLs. + + *graph_attrs*, *node_attrs*, *edge_attrs* are dictionaries containing + key/value pairs to pass on as graphviz properties. + """ + g_attrs = self.default_graph_attrs.copy() + n_attrs = self.default_node_attrs.copy() + e_attrs = self.default_edge_attrs.copy() + g_attrs.update(graph_attrs) + n_attrs.update(node_attrs) + e_attrs.update(edge_attrs) + if env: + g_attrs.update(env.config.inheritance_graph_attrs) + n_attrs.update(env.config.inheritance_node_attrs) + e_attrs.update(env.config.inheritance_edge_attrs) + + res = [] + res.append('digraph %s {\n' % name) + res.append(self._format_graph_attrs(g_attrs)) + + for cls in self.all_classes: + if not self.show_builtins and cls in __builtins__.values(): + continue + + name = self.class_name(cls, parts) + + # Write the node + this_node_attrs = n_attrs.copy() + url = urls.get(self.class_name(cls)) + if url is not None: + this_node_attrs['URL'] = '"%s"' % url + res.append(' "%s" [%s];\n' % + (name, self._format_node_attrs(this_node_attrs))) + + # Write the edges + for base in cls.__bases__: + if not self.show_builtins and base in __builtins__.values(): + continue + + base_name = self.class_name(base, parts) + res.append(' "%s" -> "%s" [%s];\n' % + (base_name, name, + self._format_node_attrs(e_attrs))) + res.append('}\n') + return ''.join(res) + + +class inheritance_diagram(nodes.General, nodes.Element): + """ + A docutils node to use as a placeholder for the inheritance diagram. + """ + pass + + +class InheritanceDiagram(Directive): + """ + Run when the inheritance_diagram directive is first encountered. + """ + has_content = False + required_arguments = 1 + optional_arguments = 0 + final_argument_whitespace = True + option_spec = { + 'parts': directives.nonnegative_int, + } + + def run(self): + node = inheritance_diagram() + node.document = self.state.document + env = self.state.document.settings.env + class_names = self.arguments[0].split() + + # Create a graph starting with the list of classes + try: + graph = InheritanceGraph(class_names, env.currmodule) + except InheritanceException, err: + return [node.document.reporter.warning(err.args[0], + line=self.lineno)] + + # Create xref nodes for each target of the graph's image map and + # add them to the doc tree so that Sphinx can resolve the + # references to real URLs later. These nodes will eventually be + # removed from the doctree after we're done with them. + for name in graph.get_all_class_names(): + refnodes, x = xfileref_role( + 'class', ':class:`%s`' % name, name, 0, self.state) + node.extend(refnodes) + # Store the graph object so we can use it to generate the + # dot file later + node['graph'] = graph + # Store the original content for use as a hash + node['parts'] = self.options.get('parts', 0) + node['content'] = ' '.join(class_names) + return [node] + + +def get_graph_hash(node): + return md5(node['content'] + str(node['parts'])).hexdigest()[-10:] + + +def html_visit_inheritance_diagram(self, node): + """ + Output the graph for HTML. This will insert a PNG with clickable + image map. + """ + graph = node['graph'] + parts = node['parts'] + + graph_hash = get_graph_hash(node) + name = 'inheritance%s' % graph_hash + + # Create a mapping from fully-qualified class names to URLs. + urls = {} + for child in node: + if child.get('refuri') is not None: + urls[child['reftitle']] = child.get('refuri') + elif child.get('refid') is not None: + 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') + raise nodes.SkipNode + + +def latex_visit_inheritance_diagram(self, node): + """ + Output the graph for LaTeX. This will insert a PDF. + """ + graph = node['graph'] + parts = node['parts'] + + graph_hash = get_graph_hash(node) + name = 'inheritance%s' % graph_hash + + dotcode = graph.generate_dot(name, parts, urls, env=self.builder.env, + graph_attrs={'size': '"6.0,6.0"'}) + render_dot_latex(self, node, dotcode, [], 'inheritance') + raise nodes.SkipNode + + +def skip(self, node): + raise nodes.SkipNode + + +def setup(app): + app.setup_extension('sphinx.ext.graphviz') + app.add_node( + inheritance_diagram, + latex=(latex_visit_inheritance_diagram, None), + html=(html_visit_inheritance_diagram, None), + text=(skip, None)) + app.add_directive('inheritance-diagram', InheritanceDiagram) + app.add_config_value('inheritance_graph_attrs', {}, False), + app.add_config_value('inheritance_node_attrs', {}, False), + app.add_config_value('inheritance_edge_attrs', {}, False), diff --git a/sphinx/ext/intersphinx.py b/sphinx/ext/intersphinx.py index 0c034e0d5..5340a55ec 100644 --- a/sphinx/ext/intersphinx.py +++ b/sphinx/ext/intersphinx.py @@ -20,8 +20,8 @@ also be specified individually, e.g. if the docs should be buildable without Internet access. - :copyright: 2008 by Georg Brandl. - :license: BSD. + :copyright: Copyright 2007-2009 by the Sphinx team, see AUTHORS. + :license: BSD, see LICENSE for details. """ import time @@ -31,7 +31,7 @@ from os import path from docutils import nodes -from sphinx.builder import INVENTORY_FILENAME +from sphinx.builders.html import INVENTORY_FILENAME def fetch_inventory(app, uri, inv): @@ -125,7 +125,7 @@ def missing_reference(app, env, node, contnode): if target not in env.intersphinx_inventory: return None type, proj, version, uri = env.intersphinx_inventory[target] - print "Intersphinx hit:", target, uri + # print "Intersphinx hit:", target, uri newnode = nodes.reference('', '') newnode['refuri'] = uri + '#' + target newnode['reftitle'] = '(in %s v%s)' % (proj, version) diff --git a/sphinx/ext/jsmath.py b/sphinx/ext/jsmath.py index bd2579de5..e51af4550 100644 --- a/sphinx/ext/jsmath.py +++ b/sphinx/ext/jsmath.py @@ -6,8 +6,8 @@ Set up everything for use of JSMath to display math in HTML via JavaScript. - :copyright: 2008 by Georg Brandl. - :license: BSD. + :copyright: Copyright 2007-2009 by the Sphinx team, see AUTHORS. + :license: BSD, see LICENSE for details. """ from docutils import nodes @@ -32,7 +32,8 @@ def html_visit_displaymath(self, node): if i == 0: # necessary to e.g. set the id property correctly if node['number']: - self.body.append('<span class="eqno">(%s)</span>' % node['number']) + self.body.append('<span class="eqno">(%s)</span>' % + node['number']) self.body.append(self.starttag(node, 'div', CLASS='math')) else: # but only once! diff --git a/sphinx/ext/mathbase.py b/sphinx/ext/mathbase.py index fc002c604..fea786e3e 100644 --- a/sphinx/ext/mathbase.py +++ b/sphinx/ext/mathbase.py @@ -5,13 +5,15 @@ Set up math support in source files and LaTeX/text output. - :copyright: 2008 by Georg Brandl. - :license: BSD. + :copyright: Copyright 2007-2009 by the Sphinx team, see AUTHORS. + :license: BSD, see LICENSE for details. """ from docutils import nodes, utils from docutils.parsers.rst import directives +from sphinx.util.compat import Directive + class math(nodes.Inline, nodes.TextElement): pass @@ -45,22 +47,33 @@ def eq_role(role, rawtext, text, lineno, inliner, options={}, content=[]): node['docname'] = inliner.document.settings.env.docname return [node], [] -def math_directive(name, arguments, options, content, lineno, - content_offset, block_text, state, state_machine): - latex = '\n'.join(content) - if arguments and arguments[0]: - latex = arguments[0] + '\n\n' + latex - node = displaymath() - node['latex'] = latex - node['label'] = options.get('label', None) - node['nowrap'] = 'nowrap' in options - node['docname'] = state.document.settings.env.docname - ret = [node] - if node['label']: - tnode = nodes.target('', '', ids=['equation-' + node['label']]) - state.document.note_explicit_target(tnode) - ret.insert(0, tnode) - return ret + +class MathDirective(Directive): + + has_content = True + required_arguments = 0 + optional_arguments = 1 + final_argument_whitespace = True + option_spec = { + 'label': directives.unchanged, + 'nowrap': directives.flag, + } + + def run(self): + latex = '\n'.join(self.content) + if self.arguments and self.arguments[0]: + latex = self.arguments[0] + '\n\n' + latex + node = displaymath() + node['latex'] = latex + node['label'] = self.options.get('label', None) + node['nowrap'] = 'nowrap' in self.options + node['docname'] = self.state.document.settings.env.docname + ret = [node] + if node['label']: + tnode = nodes.target('', '', ids=['equation-' + node['label']]) + self.state.document.note_explicit_target(tnode) + ret.insert(0, tnode) + return ret def latex_visit_math(self, node): @@ -134,6 +147,5 @@ def setup(app, htmlinlinevisitors, htmldisplayvisitors): html=(html_visit_eqref, html_depart_eqref)) app.add_role('math', math_role) app.add_role('eq', eq_role) - app.add_directive('math', math_directive, 1, (0, 1, 1), - label=directives.unchanged, nowrap=directives.flag) + app.add_directive('math', MathDirective) app.connect('doctree-resolved', number_equations) diff --git a/sphinx/ext/pngmath.py b/sphinx/ext/pngmath.py index 9f628e110..745bdba41 100644 --- a/sphinx/ext/pngmath.py +++ b/sphinx/ext/pngmath.py @@ -5,16 +5,15 @@ Render math in HTML via dvipng. - :copyright: 2008 by Georg Brandl. - :license: BSD. + :copyright: Copyright 2007-2009 by the Sphinx team, see AUTHORS. + :license: BSD, see LICENSE for details. """ import re -import shlex import shutil import tempfile import posixpath -from os import path +from os import path, getcwd, chdir from subprocess import Popen, PIPE try: from hashlib import sha1 as sha @@ -23,8 +22,9 @@ except ImportError: from docutils import nodes +from sphinx.errors import SphinxError from sphinx.util import ensuredir -from sphinx.application import SphinxError +from sphinx.util.png import read_png_depth, write_png_depth from sphinx.ext.mathbase import setup as mathbase_setup, wrap_displaymath class MathExtError(SphinxError): @@ -75,9 +75,17 @@ def render_math(self, math): """ use_preview = self.builder.config.pngmath_use_preview - shasum = "%s.png" % sha(math).hexdigest() + shasum = "%s.png" % sha(math.encode('utf-8')).hexdigest() relfn = posixpath.join(self.builder.imgpath, 'math', shasum) outfn = path.join(self.builder.outdir, '_images', 'math', shasum) + if path.isfile(outfn): + depth = read_png_depth(outfn) + return relfn, depth + + # if latex or dvipng has failed once, don't bother to try again + if hasattr(self.builder, '_mathpng_warned_latex') or \ + hasattr(self.builder, '_mathpng_warned_dvipng'): + return None, None latex = DOC_HEAD + self.builder.config.pngmath_latex_preamble latex += (use_preview and DOC_BODY_PREVIEW or DOC_BODY) % math @@ -96,28 +104,39 @@ def render_math(self, math): tf.write(latex) tf.close() - ltx_args = shlex.split(self.builder.config.pngmath_latex) - ltx_args += ['--interaction=nonstopmode', '--output-directory=' + tempdir, - 'math.tex'] + # build latex command; old versions of latex don't have the + # --output-directory option, so we have to manually chdir to the + # temp dir to run it. + ltx_args = [self.builder.config.pngmath_latex, '--interaction=nonstopmode'] + # add custom args from the config file + ltx_args.extend(self.builder.config.pngmath_latex_args) + ltx_args.append('math.tex') + + curdir = getcwd() + chdir(tempdir) + try: - p = Popen(ltx_args, stdout=PIPE, stderr=PIPE) - except OSError, err: - if err.errno != 2: # No such file or directory - raise - if not hasattr(self.builder, '_mathpng_warned_latex'): + try: + p = Popen(ltx_args, stdout=PIPE, stderr=PIPE) + except OSError, err: + if err.errno != 2: # No such file or directory + raise self.builder.warn('LaTeX command %r cannot be run (needed for math ' 'display), check the pngmath_latex setting' % self.builder.config.pngmath_latex) self.builder._mathpng_warned_latex = True - return relfn, None + return None, None + finally: + chdir(curdir) + stdout, stderr = p.communicate() if p.returncode != 0: - raise MathExtError('latex exited with error:\n[stderr]\n%s\n[stdout]\n%s' - % (stderr, stdout)) + raise MathExtError('latex exited with error:\n[stderr]\n%s\n' + '[stdout]\n%s' % (stderr, stdout)) ensuredir(path.dirname(outfn)) # use some standard dvipng arguments - dvipng_args = shlex.split(self.builder.config.pngmath_dvipng) + dvipng_args = [self.builder.config.pngmath_dvipng] dvipng_args += ['-o', outfn, '-T', 'tight', '-z9'] # add custom ones from config value dvipng_args.extend(self.builder.config.pngmath_dvipng_args) @@ -130,22 +149,22 @@ def render_math(self, math): except OSError, err: if err.errno != 2: # No such file or directory raise - if not hasattr(self.builder, '_mathpng_warned_dvipng'): - self.builder.warn('dvipng command %r cannot be run (needed for math ' - 'display), check the pngmath_dvipng setting' % - self.builder.config.pngmath_dvipng) - self.builder._mathpng_warned_dvipng = True - return relfn, None + self.builder.warn('dvipng command %r cannot be run (needed for math ' + 'display), check the pngmath_dvipng setting' % + self.builder.config.pngmath_dvipng) + self.builder._mathpng_warned_dvipng = True + return None, None stdout, stderr = p.communicate() if p.returncode != 0: - raise MathExtError('dvipng exited with error:\n[stderr]\n%s\n[stdout]\n%s' - % (stderr, stdout)) + raise MathExtError('dvipng exited with error:\n[stderr]\n%s\n' + '[stdout]\n%s' % (stderr, stdout)) depth = None if use_preview: for line in stdout.splitlines(): m = depth_re.match(line) if m: depth = int(m.group(1)) + write_png_depth(outfn, depth) break return relfn, depth @@ -161,10 +180,28 @@ def cleanup_tempdir(app, exc): pass def html_visit_math(self, node): - fname, depth = render_math(self, '$'+node['latex']+'$') - self.body.append('<img src="%s" alt="%s" %s/>' % - (fname, self.encode(node['latex']), - depth and 'style="vertical-align: %dpx" ' % (-depth) or '')) + try: + fname, depth = render_math(self, '$'+node['latex']+'$') + except MathExtError, exc: + sm = nodes.system_message(str(exc), type='WARNING', level=2, + backrefs=[], source=node['latex']) + sm.walkabout(self) + self.builder.warn('display latex %r: ' % node['latex'] + str(exc)) + raise nodes.SkipNode + if fname is None: + # something failed -- use text-only as a bad substitute + self.body.append('<span class="math">%s</span>' % + self.encode(node['latex']).strip()) + else: + if depth is None: + self.body.append( + '<img class="math" src="%s" alt="%s"/>' % + (fname, self.encode(node['latex']).strip())) + else: + self.body.append( + '<img class="math" src="%s" alt="%s" ' + 'style="vertical-align: %dpx"/>' % + (fname, self.encode(node['latex']).strip(), -depth)) raise nodes.SkipNode def html_visit_displaymath(self, node): @@ -172,13 +209,25 @@ def html_visit_displaymath(self, node): latex = node['latex'] else: latex = wrap_displaymath(node['latex'], None) - fname, depth = render_math(self, latex) + try: + fname, depth = render_math(self, latex) + except MathExtError, exc: + sm = nodes.system_message(str(exc), type='WARNING', level=2, + backrefs=[], source=node['latex']) + sm.walkabout(self) + self.builder.warn('inline latex %r: ' % node['latex'] + str(exc)) + raise nodes.SkipNode self.body.append(self.starttag(node, 'div', CLASS='math')) self.body.append('<p>') if node['number']: self.body.append('<span class="eqno">(%s)</span>' % node['number']) - self.body.append('<img src="%s" alt="%s" />\n</div>' % - (fname, self.encode(node['latex']))) + if fname is None: + # something failed -- use text-only as a bad substitute + self.body.append('<span class="math">%s</span>' % + self.encode(node['latex']).strip()) + else: + self.body.append('<img src="%s" alt="%s" />\n</div>' % + (fname, self.encode(node['latex']).strip())) self.body.append('</p>') raise nodes.SkipNode @@ -188,6 +237,7 @@ def setup(app): app.add_config_value('pngmath_dvipng', 'dvipng', False) app.add_config_value('pngmath_latex', 'latex', False) app.add_config_value('pngmath_use_preview', False, False) - app.add_config_value('pngmath_dvipng_args', [], False) + app.add_config_value('pngmath_dvipng_args', ['-gamma 1.5', '-D 110'], False) + app.add_config_value('pngmath_latex_args', [], False) app.add_config_value('pngmath_latex_preamble', '', False) app.connect('build-finished', cleanup_tempdir) diff --git a/sphinx/ext/refcounting.py b/sphinx/ext/refcounting.py index c6e5a76fc..cad9d7f1a 100644 --- a/sphinx/ext/refcounting.py +++ b/sphinx/ext/refcounting.py @@ -9,8 +9,8 @@ Usage: Set the `refcount_file` config value to the path to the reference count data file. - :copyright: 2008 by Georg Brandl. - :license: BSD. + :copyright: Copyright 2007-2009 by the Sphinx team, see AUTHORS. + :license: BSD, see LICENSE for details. """ from os import path @@ -55,7 +55,8 @@ class Refcounts(dict): refcount = None else: refcount = int(refcount) - # Update the entry with the new parameter or the result information. + # Update the entry with the new parameter or the result + # information. if arg: entry.args.append((arg, type, refcount)) else: @@ -81,7 +82,8 @@ class Refcounts(dict): if entry.result_refs is None: rc += "Always NULL." else: - rc += (entry.result_refs and "New" or "Borrowed") + " reference." + rc += (entry.result_refs and "New" or "Borrowed") + \ + " reference." node.insert(0, refcount(rc, rc)) diff --git a/sphinx/ext/todo.py b/sphinx/ext/todo.py new file mode 100644 index 000000000..61dd4d673 --- /dev/null +++ b/sphinx/ext/todo.py @@ -0,0 +1,147 @@ +# -*- coding: utf-8 -*- +""" + sphinx.ext.todo + ~~~~~~~~~~~~~~~ + + Allow todos to be inserted into your documentation. Inclusion of todos can + be switched of by a configuration variable. The todolist directive collects + 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. + :license: BSD, see LICENSE for details. +""" + +from docutils import nodes + +from sphinx.util.compat import Directive, make_admonition + +class todo_node(nodes.Admonition, nodes.Element): pass +class todolist(nodes.General, nodes.Element): pass + + +class Todo(Directive): + """ + A todo entry, displayed (if configured) in the form of an admonition. + """ + + has_content = True + required_arguments = 0 + optional_arguments = 0 + final_argument_whitespace = False + option_spec = {} + + def run(self): + env = self.state.document.settings.env + + targetid = "todo-%s" % env.index_num + env.index_num += 1 + targetnode = nodes.target('', '', ids=[targetid]) + + 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) + + # 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 = [] + env.todo_all_todos.append({ + 'docname': env.docname, + 'lineno': self.lineno, + 'todo': ad[0].deepcopy(), + 'target': targetnode, + }) + + return [targetnode] + ad + + +class TodoList(Directive): + """ + A list of all todo entries. + """ + + has_content = False + required_arguments = 0 + optional_arguments = 0 + final_argument_whitespace = False + option_spec = {} + + def run(self): + # Simply insert an empty todolist node which will be replaced later + # when process_todo_nodes is called + return [todolist('')] + + +def process_todo_nodes(app, doctree, fromdocname): + if not app.config['todo_include_todos']: + for node in doctree.traverse(todo_node): + node.parent.remove(node) + + # Replace all todolist nodes with a list of the collected todos. + # Augment each todo with a backlink to the original location. + env = app.builder.env + + if not hasattr(env, 'todo_all_todos'): + env.todo_all_todos = [] + + for node in doctree.traverse(todolist): + if not app.config['todo_include_todos']: + node.replace_self([]) + continue + + content = [] + + for todo_info in env.todo_all_todos: + para = nodes.paragraph() + filename = env.doc2path(todo_info['docname'], base=None) + description = ( + _('(The original entry is located in %s, line %d and ' + 'can be found ') % (filename, todo_info['lineno'])) + para += nodes.Text(description, description) + + # Create a reference + newnode = nodes.reference('', '') + innernode = nodes.emphasis(_('here'), _('here')) + newnode['refdocname'] = todo_info['docname'] + newnode['refuri'] = app.builder.get_relative_uri( + fromdocname, todo_info['docname']) + newnode['refuri'] += '#' + todo_info['target']['refid'] + newnode.append(innernode) + para += newnode + para += nodes.Text('.)', '.)') + + # Insert into the todolist + content.append(todo_info['todo']) + content.append(para) + + node.replace_self(content) + + +def purge_todos(app, env, docname): + if not hasattr(env, 'todo_all_todos'): + return + env.todo_all_todos = [todo for todo in env.todo_all_todos + if todo['docname'] != docname] + + +def visit_todo_node(self, node): + self.visit_admonition(node) + +def depart_todo_node(self, node): + self.depart_admonition(node) + +def setup(app): + app.add_config_value('todo_include_todos', False, False) + + app.add_node(todolist) + app.add_node(todo_node, + html=(visit_todo_node, depart_todo_node), + latex=(visit_todo_node, depart_todo_node), + text=(visit_todo_node, depart_todo_node)) + + app.add_directive('todo', Todo) + app.add_directive('todolist', TodoList) + app.connect('doctree-resolved', process_todo_nodes) + app.connect('env-purge-doc', purge_todos) + diff --git a/sphinx/highlighting.py b/sphinx/highlighting.py index 1637b2c3f..61c413d7a 100644 --- a/sphinx/highlighting.py +++ b/sphinx/highlighting.py @@ -5,8 +5,8 @@ Highlight code blocks using Pygments. - :copyright: 2007-2008 by Georg Brandl. - :license: BSD. + :copyright: Copyright 2007-2009 by the Sphinx team, see AUTHORS. + :license: BSD, see LICENSE for details. """ import sys @@ -30,6 +30,8 @@ try: from pygments.token import Generic, Comment, Number except ImportError: pygments = None + lexers = None + HtmlFormatter = LatexFormatter = None else: class SphinxStyle(Style): """ @@ -47,12 +49,15 @@ else: Number: '#208050', }) + class NoneStyle(Style): + """Style without any styling.""" + lexers = dict( none = TextLexer(), python = PythonLexer(), pycon = PythonConsoleLexer(), - # the python3 option exists as of Pygments 0.12, but it doesn't - # do any harm in previous versions + # the python3 option exists as of Pygments 1.0, + # but it doesn't do any harm in previous versions pycon3 = PythonConsoleLexer(python3=True), rest = RstLexer(), c = CLexer(), @@ -81,22 +86,33 @@ if sys.version_info < (2, 5): class PygmentsBridge(object): + # Set these attributes if you want to have different Pygments formatters + # than the default ones. + html_formatter = HtmlFormatter + latex_formatter = LatexFormatter + def __init__(self, dest='html', stylename='sphinx'): self.dest = dest if not pygments: return - if stylename == 'sphinx': + if stylename is None or stylename == 'sphinx': style = SphinxStyle + elif stylename == 'none': + style = NoneStyle elif '.' in stylename: module, stylename = stylename.rsplit('.', 1) - style = getattr(__import__(module, None, None, ['']), stylename) + style = getattr(__import__(module, None, None, ['__name__']), + stylename) else: style = get_style_by_name(stylename) - self.hfmter = {False: HtmlFormatter(style=style), - True: HtmlFormatter(style=style, linenos=True)} - self.lfmter = {False: LatexFormatter(style=style, commandprefix='PYG'), - True: LatexFormatter(style=style, linenos=True, - commandprefix='PYG')} + if dest == 'html': + self.fmter = {False: self.html_formatter(style=style), + True: self.html_formatter(style=style, linenos=True)} + else: + self.fmter = {False: self.latex_formatter(style=style, + commandprefix='PYG'), + True: self.latex_formatter(style=style, linenos=True, + commandprefix='PYG')} def unhighlighted(self, source): if self.dest == 'html': @@ -170,9 +186,9 @@ class PygmentsBridge(object): lexer.add_filter('raiseonerror') try: if self.dest == 'html': - return highlight(source, lexer, self.hfmter[bool(linenos)]) + return highlight(source, lexer, self.fmter[bool(linenos)]) else: - hlsource = highlight(source, lexer, self.lfmter[bool(linenos)]) + hlsource = highlight(source, lexer, self.fmter[bool(linenos)]) return hlsource.translate(tex_hl_escape_map) except ErrorToken: # this is most probably not the selected language, @@ -186,9 +202,9 @@ class PygmentsBridge(object): # no HTML styles needed return '' if self.dest == 'html': - return self.hfmter[0].get_style_defs() + return self.fmter[0].get_style_defs() else: - styledefs = self.lfmter[0].get_style_defs() + styledefs = self.fmter[0].get_style_defs() # workaround for Pygments < 0.12 if styledefs.startswith('\\newcommand\\at{@}'): styledefs += _LATEX_STYLES diff --git a/sphinx/htmlhelp.py b/sphinx/htmlhelp.py deleted file mode 100644 index 33dbd9ff5..000000000 --- a/sphinx/htmlhelp.py +++ /dev/null @@ -1,210 +0,0 @@ -# -*- coding: utf-8 -*- -""" - sphinx.htmlhelp - ~~~~~~~~~~~~~~~ - - Build HTML help support files. - Adapted from the original Doc/tools/prechm.py. - - :copyright: 2007-2008 by Georg Brandl. - :license: BSD. -""" - -import os -import cgi -from os import path - -from docutils import nodes - -from sphinx import addnodes - -# Project file (*.hhp) template. 'outname' is the file basename (like -# the pythlp in pythlp.hhp); 'version' is the doc version number (like -# the 2.2 in Python 2.2). -# The magical numbers in the long line under [WINDOWS] set most of the -# user-visible features (visible buttons, tabs, etc). -# About 0x10384e: This defines the buttons in the help viewer. The -# following defns are taken from htmlhelp.h. Not all possibilities -# actually work, and not all those that work are available from the Help -# Workshop GUI. In particular, the Zoom/Font button works and is not -# available from the GUI. The ones we're using are marked with 'x': -# -# 0x000002 Hide/Show x -# 0x000004 Back x -# 0x000008 Forward x -# 0x000010 Stop -# 0x000020 Refresh -# 0x000040 Home x -# 0x000080 Forward -# 0x000100 Back -# 0x000200 Notes -# 0x000400 Contents -# 0x000800 Locate x -# 0x001000 Options x -# 0x002000 Print x -# 0x004000 Index -# 0x008000 Search -# 0x010000 History -# 0x020000 Favorites -# 0x040000 Jump 1 -# 0x080000 Jump 2 -# 0x100000 Zoom/Font x -# 0x200000 TOC Next -# 0x400000 TOC Prev - -project_template = '''\ -[OPTIONS] -Binary TOC=Yes -Compiled file=%(outname)s.chm -Contents file=%(outname)s.hhc -Default Window=%(outname)s -Default topic=index.html -Display compile progress=No -Full text search stop list file=%(outname)s.stp -Full-text search=Yes -Index file=%(outname)s.hhk -Language=0x409 -Title=%(title)s - -[WINDOWS] -%(outname)s="%(title)s","%(outname)s.hhc","%(outname)s.hhk",\ -"index.html","index.html",,,,,0x63520,220,0x10384e,[0,0,1024,768],,,,,,,0 - -[FILES] -''' - -contents_header = '''\ -<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN"> -<HTML> -<HEAD> -<meta name="GENERATOR" content="Microsoft® HTML Help Workshop 4.1"> -<!-- Sitemap 1.0 --> -</HEAD><BODY> -<OBJECT type="text/site properties"> - <param name="Window Styles" value="0x801227"> - <param name="ImageType" value="Folder"> -</OBJECT> -<UL> -''' - -contents_footer = '''\ -</UL></BODY></HTML> -''' - -object_sitemap = '''\ -<OBJECT type="text/sitemap"> - <param name="Name" value="%s"> - <param name="Local" value="%s"> -</OBJECT> -''' - -# List of words the full text search facility shouldn't index. This -# becomes file outname.stp. Note that this list must be pretty small! -# Different versions of the MS docs claim the file has a maximum size of -# 256 or 512 bytes (including \r\n at the end of each line). -# Note that "and", "or", "not" and "near" are operators in the search -# language, so no point indexing them even if we wanted to. -stopwords = """ -a and are as at -be but by -for -if in into is it -near no not -of on or -such -that the their then there these they this to -was will with -""".split() - - -def build_hhx(builder, outdir, outname): - builder.info('dumping stopword list...') - f = open(path.join(outdir, outname+'.stp'), 'w') - try: - for word in sorted(stopwords): - print >>f, word - finally: - f.close() - - builder.info('writing project file...') - f = open(path.join(outdir, outname+'.hhp'), 'w') - try: - f.write(project_template % {'outname': outname, - 'title': builder.config.html_title, - 'version': builder.config.version, - 'project': builder.config.project}) - if not outdir.endswith(os.sep): - outdir += os.sep - olen = len(outdir) - for root, dirs, files in os.walk(outdir): - staticdir = (root == path.join(outdir, '_static')) - for fn in files: - if (staticdir and not fn.endswith('.js')) or fn.endswith('.html'): - print >>f, path.join(root, fn)[olen:].replace(os.sep, '\\') - finally: - f.close() - - builder.info('writing TOC file...') - f = open(path.join(outdir, outname+'.hhc'), 'w') - try: - f.write(contents_header) - # special books - f.write('<LI> ' + object_sitemap % (builder.config.html_short_title, - 'index.html')) - if builder.config.html_use_modindex: - f.write('<LI> ' + object_sitemap % (_('Global Module Index'), - 'modindex.html')) - # the TOC - tocdoc = builder.env.get_and_resolve_doctree(builder.config.master_doc, builder, - prune_toctrees=False) - def write_toc(node, ullevel=0): - if isinstance(node, nodes.list_item): - f.write('<LI> ') - for subnode in node: - write_toc(subnode, ullevel) - elif isinstance(node, nodes.reference): - link = node['refuri'] - title = cgi.escape(node.astext()).replace('"','"') - item = object_sitemap % (title, link) - f.write(item.encode('ascii', 'xmlcharrefreplace')) - elif isinstance(node, nodes.bullet_list): - if ullevel != 0: - f.write('<UL>\n') - for subnode in node: - write_toc(subnode, ullevel+1) - if ullevel != 0: - f.write('</UL>\n') - elif isinstance(node, addnodes.compact_paragraph): - for subnode in node: - write_toc(subnode, ullevel) - istoctree = lambda node: isinstance(node, addnodes.compact_paragraph) and \ - node.has_key('toctree') - for node in tocdoc.traverse(istoctree): - write_toc(node) - f.write(contents_footer) - finally: - f.close() - - builder.info('writing index file...') - index = builder.env.create_index(builder) - f = open(path.join(outdir, outname+'.hhk'), 'w') - try: - f.write('<UL>\n') - def write_index(title, refs, subitems): - if refs: - f.write('<LI> ') - item = object_sitemap % (cgi.escape(title), refs[0]) - f.write(item.encode('ascii', 'xmlcharrefreplace')) - for ref in refs[1:]: - f.write(object_sitemap % ('[Link]', ref)) - if subitems: - f.write('<UL> ') - for subitem in subitems: - write_index(subitem[0], subitem[1], []) - f.write('</UL>') - for (key, group) in index: - for title, (refs, subitems) in group: - write_index(title, refs, subitems) - f.write('</UL>\n') - finally: - f.close() diff --git a/sphinx/jinja2glue.py b/sphinx/jinja2glue.py new file mode 100644 index 000000000..679447a81 --- /dev/null +++ b/sphinx/jinja2glue.py @@ -0,0 +1,102 @@ +# -*- coding: utf-8 -*- +""" + sphinx.jinja2glue + ~~~~~~~~~~~~~~~~~ + + Glue code for the jinja2 templating engine. + + :copyright: Copyright 2007-2009 by the Sphinx team, see AUTHORS. + :license: BSD, see LICENSE for details. +""" + +import codecs +from os import path +from pprint import pformat + +from jinja2 import FileSystemLoader, BaseLoader, TemplateNotFound, \ + contextfunction +from jinja2.sandbox import SandboxedEnvironment + +from sphinx.util import mtimes_of_files +from sphinx.application import TemplateBridge + + +def _tobool(val): + if isinstance(val, basestring): + return val.lower() in ('true', '1', 'yes', 'on') + return bool(val) + +def accesskey(context, key): + """Helper to output each access key only once.""" + if '_accesskeys' not in context: + context.vars['_accesskeys'] = {} + if key not in context.vars['_accesskeys']: + context.vars['_accesskeys'][key] = 1 + return 'accesskey="%s"' % key + return '' + + +class BuiltinTemplateLoader(TemplateBridge, BaseLoader): + """ + Interfaces the rendering environment of jinja2 for use in Sphinx. + """ + + # TemplateBridge interface + + def init(self, builder, theme=None, dirs=None): + # create a chain of paths to search + if theme: + # the theme's own dir and its bases' dirs + chain = theme.get_dirchain() + # then the theme parent paths + chain.extend(theme.themepath) + elif dirs: + chain = list(dirs) + else: + chain = [] + + # prepend explicit template paths + self.templatepathlen = len(builder.config.templates_path) + if builder.config.templates_path: + chain[0:0] = [path.join(builder.confdir, tp) + for tp in builder.config.templates_path] + + # store it for use in newest_template_mtime + self.pathchain = chain + + # make the paths into loaders + self.loaders = map(FileSystemLoader, chain) + + use_i18n = builder.translator is not None + extensions = use_i18n and ['jinja2.ext.i18n'] or [] + self.environment = SandboxedEnvironment(loader=self, + extensions=extensions) + self.environment.filters['tobool'] = _tobool + self.environment.globals['debug'] = contextfunction(pformat) + self.environment.globals['accesskey'] = contextfunction(accesskey) + if use_i18n: + self.environment.install_gettext_translations(builder.translator) + + def render(self, template, context): + return self.environment.get_template(template).render(context) + + def render_string(self, source, context): + return self.environment.from_string(source).render(context) + + def newest_template_mtime(self): + return max(mtimes_of_files(self.pathchain, '.html')) + + # Loader interface + + def get_source(self, environment, template): + loaders = self.loaders + # exclamation mark starts search from theme + if template.startswith('!'): + loaders = loaders[self.templatepathlen:] + template = template[1:] + for loader in loaders: + try: + return loader.get_source(environment, template) + except TemplateNotFound: + pass + raise TemplateNotFound(template) diff --git a/sphinx/locale/__init__.py b/sphinx/locale/__init__.py index bedade3c9..36fabc615 100644 --- a/sphinx/locale/__init__.py +++ b/sphinx/locale/__init__.py @@ -5,8 +5,8 @@ Locale utilities. - :copyright: 2008 by Georg Brandl. - :license: BSD. + :copyright: Copyright 2007-2009 by the Sphinx team, see AUTHORS. + :license: BSD, see LICENSE for details. """ _ = lambda x: x diff --git a/sphinx/locale/cs/LC_MESSAGES/sphinx.js b/sphinx/locale/cs/LC_MESSAGES/sphinx.js index 9ad7b1365..42fa9abdd 100644 --- a/sphinx/locale/cs/LC_MESSAGES/sphinx.js +++ b/sphinx/locale/cs/LC_MESSAGES/sphinx.js @@ -1 +1 @@ -Documentation.addTranslations({"locale": "cs", "plural_expr": "(n%10==1 && n%100!=11 ? 0 : n%10>=2 && n%10<=4 && (n%100<10 || n%100>=20) ? 1 : 2)", "messages": {"Search Results": "V\u00fdsledky hled\u00e1n\u00ed", "Your search did not match any documents. Please make sure that all words are spelled correctly and that you've selected enough categories.": "", "Getting search index...": "", "Permalink to this headline": "Trval\u00fd odkaz na tento nadpis", "Searching": "hledej", "Permalink to this definition": "Trval\u00fd odkaz na tuto definici", "Hide Search Matches": "", "Search finished, found %s page(s) matching the search query.": ""}}); \ No newline at end of file +Documentation.addTranslations({"locale": "cs", "plural_expr": "(n%10==1 && n%100!=11 ? 0 : n%10>=2 && n%10<=4 && (n%100<10 || n%100>=20) ? 1 : 2)", "messages": {"module, in ": "modul, v", "Preparing search...": "P\u0159ipravuji vyhled\u00e1v\u00e1n\u00ed....", "Your search did not match any documents. Please make sure that all words are spelled correctly and that you've selected enough categories.": "Nenalezli jsme \u017e\u00e1dn\u00fd dokument. Ujist\u011bte se pros\u00edm, \u017ee v\u0161echna slova jsou spr\u00e1vn\u011b a \u017ee jste vybral dostatek kategori\u00ed.", "Search finished, found %s page(s) matching the search query.": "Vyhled\u00e1v\u00e1n\u00ed skon\u010dilo, nalezeno %s stran.", ", in ": ", v", "Permalink to this headline": "Trval\u00fd odkaz na tento nadpis", "Searching": "Hled\u00e1m", "Permalink to this definition": "Trval\u00fd odkaz na tuto definici", "Hide Search Matches": "Skr\u00fdt v\u00fdsledky vyhled\u00e1v\u00e1n\u00ed", "Search Results": "V\u00fdsledky hled\u00e1n\u00ed"}}); \ No newline at end of file diff --git a/sphinx/locale/cs/LC_MESSAGES/sphinx.mo b/sphinx/locale/cs/LC_MESSAGES/sphinx.mo index 1fa64cec4..3dccc2b97 100644 Binary files a/sphinx/locale/cs/LC_MESSAGES/sphinx.mo and b/sphinx/locale/cs/LC_MESSAGES/sphinx.mo differ diff --git a/sphinx/locale/cs/LC_MESSAGES/sphinx.po b/sphinx/locale/cs/LC_MESSAGES/sphinx.po index 8a1cb6210..7d7273993 100644 --- a/sphinx/locale/cs/LC_MESSAGES/sphinx.po +++ b/sphinx/locale/cs/LC_MESSAGES/sphinx.po @@ -7,8 +7,8 @@ msgid "" msgstr "" "Project-Id-Version: Sphinx 0.5\n" "Report-Msgid-Bugs-To: EMAIL@ADDRESS\n" -"POT-Creation-Date: 2008-08-10 11:43+0000\n" -"PO-Revision-Date: 2008-09-06 19:10+0200\n" +"POT-Creation-Date: 2008-11-27 18:39+0100\n" +"PO-Revision-Date: 2009-01-24 18:39+0000\n" "Last-Translator: Pavel Kosina <pavel.kosina@gmail.com>\n" "Language-Team: Pavel Kosina <pavel.kosina@gmail.com>\n" "Plural-Forms: nplurals=3; plural=(n%10==1 && n%100!=11 ? 0 : n%10>=2 && " @@ -18,223 +18,244 @@ msgstr "" "Content-Transfer-Encoding: 8bit\n" "Generated-By: Babel 0.9.3\n" -#: sphinx/builder.py:391 -#, python-format -msgid "%b %d, %Y" -msgstr "%d.%m.%Y" - -#: sphinx/builder.py:410 sphinx/templates/defindex.html:21 -msgid "General Index" -msgstr "Rejstřík indexů" - -#: sphinx/builder.py:410 -msgid "index" -msgstr "index" - -#: sphinx/builder.py:412 sphinx/htmlhelp.py:155 -#: sphinx/templates/defindex.html:19 sphinx/templates/modindex.html:2 -#: sphinx/templates/modindex.html:13 -msgid "Global Module Index" -msgstr "Rejstřík modulů" - -#: sphinx/builder.py:412 -msgid "modules" -msgstr "moduly" - -#: sphinx/builder.py:448 -msgid "next" -msgstr "další" - -#: sphinx/builder.py:455 -msgid "previous" -msgstr "předchozí" - -#: sphinx/builder.py:1092 -msgid "Builtins" -msgstr "Vestavěné funkce" - -#: sphinx/builder.py:1094 -msgid "Module level" -msgstr "Úroveň modulů" - -#: sphinx/environment.py:108 sphinx/latexwriter.py:129 +#: sphinx/environment.py:104 sphinx/writers/latex.py:170 #, python-format msgid "%B %d, %Y" msgstr "%d.%m.%Y" -#: sphinx/htmlwriter.py:73 sphinx/static/doctools.js:143 -msgid "Permalink to this definition" -msgstr "Trvalý odkaz na tuto definici" - -#: sphinx/htmlwriter.py:379 sphinx/static/doctools.js:136 -msgid "Permalink to this headline" -msgstr "Trvalý odkaz na tento nadpis" - -#: sphinx/latexwriter.py:143 -msgid "Release" -msgstr "Vydání" - -#: sphinx/latexwriter.py:188 -msgid "Module index" -msgstr "Rejstřík modulů" - -#: sphinx/latexwriter.py:190 sphinx/templates/genindex-single.html:2 +#: sphinx/environment.py:300 sphinx/templates/genindex-single.html:2 #: sphinx/templates/genindex-split.html:2 #: sphinx/templates/genindex-split.html:5 sphinx/templates/genindex.html:2 #: sphinx/templates/genindex.html:5 sphinx/templates/genindex.html:48 +#: sphinx/templates/layout.html:126 sphinx/writers/latex.py:176 msgid "Index" msgstr "Index" -#: sphinx/roles.py:52 sphinx/directives/desc.py:514 +#: sphinx/environment.py:301 sphinx/writers/latex.py:175 +msgid "Module Index" +msgstr "Rejstřík modulů " + +#: sphinx/environment.py:302 sphinx/templates/defindex.html:16 +msgid "Search Page" +msgstr "Vyhledávací stránka" + +#: sphinx/roles.py:53 sphinx/directives/desc.py:580 #, python-format msgid "environment variable; %s" msgstr "promměná prostředí, %s" -#: sphinx/roles.py:59 +#: sphinx/roles.py:60 #, python-format msgid "Python Enhancement Proposals!PEP %s" msgstr "Python Enhancement Proposals!PEP %s" -#: sphinx/textwriter.py:151 +#: sphinx/builders/changes.py:64 +msgid "Builtins" +msgstr "Vestavěné funkce " + +#: sphinx/builders/changes.py:66 +msgid "Module level" +msgstr "Úroveň modulů" + +#: sphinx/builders/html.py:118 #, python-format -msgid "Platform: %s" -msgstr "Platforma: %s" +msgid "%b %d, %Y" +msgstr "%d.%m.%Y" -#: sphinx/textwriter.py:353 -msgid "[image]" -msgstr "[obrázek]" +#: sphinx/builders/html.py:137 sphinx/templates/defindex.html:21 +msgid "General Index" +msgstr "Rejstřík indexů" -#: sphinx/directives/desc.py:26 +#: sphinx/builders/html.py:137 +msgid "index" +msgstr "index" + +#: sphinx/builders/html.py:139 sphinx/builders/htmlhelp.py:182 +#: sphinx/builders/qthelp.py:131 sphinx/templates/defindex.html:19 +#: sphinx/templates/modindex.html:2 sphinx/templates/modindex.html:13 +msgid "Global Module Index" +msgstr "Celkový rejstřík modulů" + +#: sphinx/builders/html.py:139 +msgid "modules" +msgstr "moduly" + +#: sphinx/builders/html.py:179 +msgid "next" +msgstr "další" + +#: sphinx/builders/html.py:186 +msgid "previous" +msgstr "předchozí" + +#: sphinx/builders/latex.py:155 sphinx/builders/pdf.py:162 +msgid " (in " +msgstr "(v" + +#: sphinx/directives/desc.py:25 #, python-format msgid "%s() (built-in function)" msgstr "%s() (vestavěná funkce)" -#: sphinx/directives/desc.py:27 sphinx/directives/desc.py:41 -#: sphinx/directives/desc.py:53 +#: sphinx/directives/desc.py:26 sphinx/directives/desc.py:42 +#: sphinx/directives/desc.py:54 #, python-format msgid "%s() (in module %s)" msgstr "%s() (v modulu %s)" -#: sphinx/directives/desc.py:30 +#: sphinx/directives/desc.py:29 #, python-format msgid "%s (built-in variable)" msgstr "%s() (vestavěná proměnná)" -#: sphinx/directives/desc.py:31 sphinx/directives/desc.py:65 +#: sphinx/directives/desc.py:30 sphinx/directives/desc.py:78 #, python-format msgid "%s (in module %s)" msgstr "%s() (v modulu %s)" #: sphinx/directives/desc.py:33 #, python-format +msgid "%s (built-in class)" +msgstr "%s () (vestavěná proměnná)" + +#: sphinx/directives/desc.py:34 +#, python-format msgid "%s (class in %s)" msgstr "%s() (třída v %s)" -#: sphinx/directives/desc.py:45 +#: sphinx/directives/desc.py:46 #, python-format msgid "%s() (%s.%s method)" msgstr "%s() (metoda %s.%s)" -#: sphinx/directives/desc.py:47 +#: sphinx/directives/desc.py:48 #, python-format msgid "%s() (%s method)" msgstr "%s() (metoda %s)" -#: sphinx/directives/desc.py:57 +#: sphinx/directives/desc.py:58 #, python-format msgid "%s() (%s.%s static method)" msgstr "%s() (statická metoda %s.%s)" -#: sphinx/directives/desc.py:59 +#: sphinx/directives/desc.py:60 #, python-format msgid "%s() (%s static method)" msgstr "%s() (statická metoda %s)" -#: sphinx/directives/desc.py:69 +#: sphinx/directives/desc.py:82 #, python-format msgid "%s (%s.%s attribute)" msgstr "%s() (atribut %s.%s)" -#: sphinx/directives/desc.py:71 +#: sphinx/directives/desc.py:84 #, python-format msgid "%s (%s attribute)" msgstr "%s() (atribut %s)" -#: sphinx/directives/desc.py:73 +#: sphinx/directives/desc.py:86 #, python-format msgid "%s (C function)" msgstr "%s (C funkce)" -#: sphinx/directives/desc.py:75 +#: sphinx/directives/desc.py:88 #, python-format msgid "%s (C member)" msgstr "%s (člen C)" -#: sphinx/directives/desc.py:77 +#: sphinx/directives/desc.py:90 #, python-format msgid "%s (C macro)" msgstr "%s (C makro)" -#: sphinx/directives/desc.py:79 +#: sphinx/directives/desc.py:92 #, python-format msgid "%s (C type)" msgstr "%s (C typ)" -#: sphinx/directives/desc.py:81 +#: sphinx/directives/desc.py:94 #, python-format msgid "%s (C variable)" msgstr "%s (C proměnná)" -#: sphinx/directives/desc.py:99 +#: sphinx/directives/desc.py:112 msgid "Raises" msgstr "Vyvolá" -#: sphinx/directives/desc.py:103 +#: sphinx/directives/desc.py:116 msgid "Variable" msgstr "Proměnná" -#: sphinx/directives/desc.py:106 +#: sphinx/directives/desc.py:119 msgid "Returns" msgstr "Vrací" -#: sphinx/directives/desc.py:113 +#: sphinx/directives/desc.py:128 msgid "Return type" msgstr "Typ navrácené hodnoty" -#: sphinx/directives/desc.py:140 +#: sphinx/directives/desc.py:213 +#, fuzzy +msgid "Parameter" +msgstr "Parametry" + +#: sphinx/directives/desc.py:217 msgid "Parameters" msgstr "Parametry" -#: sphinx/directives/desc.py:402 +#: sphinx/directives/desc.py:465 #, python-format -msgid "command line option; %s" -msgstr "parametry příkazového řádku; %s" +msgid "%scommand line option; %s" +msgstr "%s parametry příkazového řádku; %s" -#: sphinx/directives/other.py:102 +#: sphinx/directives/other.py:101 msgid "Platforms: " msgstr "Platformy: " -#: sphinx/directives/other.py:107 +#: sphinx/directives/other.py:106 #, python-format msgid "%s (module)" msgstr "%s (module)" -#: sphinx/directives/other.py:147 +#: sphinx/directives/other.py:146 msgid "Section author: " msgstr "Autor sekce: " -#: sphinx/directives/other.py:149 +#: sphinx/directives/other.py:148 msgid "Module author: " msgstr "Autor modulu: " -#: sphinx/directives/other.py:151 +#: sphinx/directives/other.py:150 msgid "Author: " msgstr "Autor: " -#: sphinx/directives/other.py:233 +#: sphinx/directives/other.py:249 msgid "See also" msgstr "Viz také" +#: sphinx/ext/autodoc.py:442 +#, python-format +msgid " Bases: %s" +msgstr "" + +#: sphinx/ext/autodoc.py:566 sphinx/ext/autodoc.py:583 +#, python-format +msgid "alias of :class:`%s`" +msgstr "" + +#: sphinx/ext/todo.py:31 +msgid "Todo" +msgstr "Todo" + +#: sphinx/ext/todo.py:75 +#, python-format +msgid "(The original entry is located in %s, line %d and can be found " +msgstr "(Původní záznam je v %s, řádka %d a lze jej nalézt" + +#: sphinx/ext/todo.py:81 +msgid "here" +msgstr "zde" + #: sphinx/locale/__init__.py:15 msgid "Attention" msgstr "Výstraha" @@ -318,33 +339,50 @@ msgstr "příkaz" msgid "built-in function" msgstr "vestavěná funkce" -#: sphinx/static/doctools.js:172 +#: sphinx/static/doctools.js:139 sphinx/writers/html.py:425 +msgid "Permalink to this headline" +msgstr "Trvalý odkaz na tento nadpis" + +#: sphinx/static/doctools.js:145 sphinx/writers/html.py:80 +msgid "Permalink to this definition" +msgstr "Trvalý odkaz na tuto definici" + +#: sphinx/static/doctools.js:174 msgid "Hide Search Matches" -msgstr "" +msgstr "Skrýt výsledky vyhledávání" -#: sphinx/static/searchtools.js:242 -#, fuzzy +#: sphinx/static/searchtools.js:274 msgid "Searching" -msgstr "hledej" +msgstr "Hledám" -#: sphinx/static/searchtools.js:246 -msgid "Getting search index..." -msgstr "" +#: sphinx/static/searchtools.js:279 +msgid "Preparing search..." +msgstr "Připravuji vyhledávání...." -#: sphinx/static/searchtools.js:384 sphinx/templates/search.html:18 +#: sphinx/static/searchtools.js:338 +msgid "module, in " +msgstr "modul, v" + +#: sphinx/static/searchtools.js:347 +msgid ", in " +msgstr ", v" + +#: sphinx/static/searchtools.js:453 sphinx/templates/search.html:25 msgid "Search Results" msgstr "Výsledky hledání" -#: sphinx/static/searchtools.js:386 +#: sphinx/static/searchtools.js:455 msgid "" "Your search did not match any documents. Please make sure that all words " "are spelled correctly and that you've selected enough categories." msgstr "" +"Nenalezli jsme žádný dokument. Ujistěte se prosím, že všechna slova jsou " +"správně a že jste vybral dostatek kategorií." -#: sphinx/static/searchtools.js:389 +#: sphinx/static/searchtools.js:457 #, python-format msgid "Search finished, found %s page(s) matching the search query." -msgstr "" +msgstr "Vyhledávání skončilo, nalezeno %s stran." #: sphinx/templates/defindex.html:2 msgid "Overview" @@ -362,10 +400,6 @@ msgstr "Celkový obsah" msgid "lists all sections and subsections" msgstr "seznam všech sekcí a podsekcí" -#: sphinx/templates/defindex.html:16 -msgid "Search page" -msgstr "Vyhledávací stránka" - #: sphinx/templates/defindex.html:17 msgid "search this documentation" msgstr "prohledej tuto dokumentaci" @@ -409,27 +443,23 @@ msgstr "Obsah" msgid "Previous topic" msgstr "Přechozí téma" -#: sphinx/templates/layout.html:47 +#: sphinx/templates/layout.html:48 msgid "previous chapter" msgstr "předchozí kapitola" -#: sphinx/templates/layout.html:50 +#: sphinx/templates/layout.html:51 msgid "Next topic" msgstr "Další téma" -#: sphinx/templates/layout.html:51 +#: sphinx/templates/layout.html:53 msgid "next chapter" msgstr "další kapitola" -#: sphinx/templates/layout.html:55 +#: sphinx/templates/layout.html:58 msgid "This Page" msgstr "Tato stránka" -#: sphinx/templates/layout.html:59 -msgid "Suggest Change" -msgstr "Návrh změnu" - -#: sphinx/templates/layout.html:60 sphinx/templates/layout.html:62 +#: sphinx/templates/layout.html:61 msgid "Show Source" msgstr "Ukázat zdroj" @@ -437,60 +467,49 @@ msgstr "Ukázat zdroj" msgid "Quick search" msgstr "Rychlé vyhledávání" -#: sphinx/templates/layout.html:71 -msgid "Keyword search" -msgstr "Hledání dle klíče" - -#: sphinx/templates/layout.html:73 +#: sphinx/templates/layout.html:74 msgid "Go" msgstr "hledej" #: sphinx/templates/layout.html:78 -msgid "Enter a module, class or function name." +#, fuzzy +msgid "Enter search terms or a module, class or function name." msgstr "Zadej jméno modulu, třídy nebo funkce." -#: sphinx/templates/layout.html:118 +#: sphinx/templates/layout.html:115 #, python-format msgid "Search within %(docstitle)s" msgstr "Hledání uvnitř %(docstitle)s" -#: sphinx/templates/layout.html:127 +#: sphinx/templates/layout.html:124 msgid "About these documents" msgstr "O těchto dokumentech" -#: sphinx/templates/layout.html:129 -msgid "Global table of contents" -msgstr "Celkový obsah" - -#: sphinx/templates/layout.html:130 -msgid "Global index" -msgstr "Celkový index" - -#: sphinx/templates/layout.html:131 sphinx/templates/search.html:2 +#: sphinx/templates/layout.html:127 sphinx/templates/search.html:2 #: sphinx/templates/search.html:5 msgid "Search" msgstr "Hledání" -#: sphinx/templates/layout.html:133 +#: sphinx/templates/layout.html:129 msgid "Copyright" msgstr "Veškerá práva vyhrazena" -#: sphinx/templates/layout.html:178 +#: sphinx/templates/layout.html:174 #, python-format msgid "© <a href=\"%(path)s\">Copyright</a> %(copyright)s." msgstr "© <a href=\"%(path)s\">Copyright</a> %(copyright)s." -#: sphinx/templates/layout.html:180 +#: sphinx/templates/layout.html:176 #, python-format msgid "© Copyright %(copyright)s." msgstr "© Copyright %(copyright)s." -#: sphinx/templates/layout.html:183 +#: sphinx/templates/layout.html:179 #, python-format msgid "Last updated on %(last_updated)s." -msgstr "Naposledy aktualizováno dne %(last_updated)s." +msgstr "Aktualizováno dne %(last_updated)s." -#: sphinx/templates/layout.html:186 +#: sphinx/templates/layout.html:182 #, python-format msgid "" "Created using <a href=\"http://sphinx.pocoo.org/\">Sphinx</a> " @@ -499,15 +518,7 @@ msgstr "" "Vytvořeno pomocí <a href=\"http://sphinx.pocoo.org/\">Sphinx</a> " "%(sphinx_version)s." -#: sphinx/templates/modindex.html:15 -msgid "Most popular modules:" -msgstr "Nejpopulárnější moduly:" - -#: sphinx/templates/modindex.html:24 -msgid "Show modules only available on these platforms" -msgstr "Zobrazit moduly dostupné na této platformě" - -#: sphinx/templates/modindex.html:56 +#: sphinx/templates/modindex.html:36 msgid "Deprecated" msgstr "Zastaralé" @@ -516,33 +527,29 @@ msgstr "Zastaralé" msgid "Search %(docstitle)s" msgstr "Prohledat %(docstitle)s" -#: sphinx/templates/page.html:8 +#: sphinx/templates/search.html:9 msgid "" -"<strong>Note:</strong> You requested an out-of-date URL from this server." -" We've tried to redirect you to the new location of this page, but it may" -" not be the right one." +"Please activate JavaScript to enable the search\n" +" functionality." msgstr "" -"<strong>Poznámka:</strong> Stránka, kterou hledáte, " -"neexistuje.<br>Snažili jsme se najít nové umístění této stránky, ale " -"nepovedlo se." -#: sphinx/templates/search.html:7 +#: sphinx/templates/search.html:14 msgid "" "From here you can search these documents. Enter your search\n" " words into the box below and click \"search\". Note that the search\n" " function will automatically search for all of the words. Pages\n" -" containing less words won't appear in the result list." +" containing fewer words won't appear in the result list." msgstr "" -"Toto je vyhledávací stránka. Zadejte klíčová slova do pole níže a " -"klikněte na \"hledej\". \n" -"Prohledávání funkcí hledá automaticky všechna slova. Stránky obsahující" -" slov méně, nebudou nalezeny." +"Toto je vyhledávací stránka. Zadejte klíčová slova a klikněte na " +"\"hledej\". \n" +"Vyhledávání hledá automaticky všechna slova. Nebudou tedy nalezeny " +"stránky, obsahující méně slov." -#: sphinx/templates/search.html:14 +#: sphinx/templates/search.html:21 msgid "search" msgstr "hledej" -#: sphinx/templates/search.html:20 +#: sphinx/templates/search.html:27 msgid "Your search did not match any results." msgstr "Nic jsme nenašli." @@ -574,3 +581,40 @@ msgstr "Změny API" msgid "Other changes" msgstr "Ostatní změny" +#: sphinx/writers/latex.py:173 +msgid "Release" +msgstr "Vydání" + +#: sphinx/writers/text.py:166 +#, python-format +msgid "Platform: %s" +msgstr "Platforma: %s" + +#: sphinx/writers/text.py:427 +msgid "[image]" +msgstr "[obrázek]" + +#~ msgid "Suggest Change" +#~ msgstr "Návrh změnu" + +#~ msgid "Keyword search" +#~ msgstr "Hledání dle klíče" + +#~ msgid "Most popular modules:" +#~ msgstr "Nejpopulárnější moduly:" + +#~ msgid "Show modules only available on these platforms" +#~ msgstr "Zobrazit moduly dostupné na této platformě" + +#~ msgid "" +#~ "<strong>Note:</strong> You requested an " +#~ "out-of-date URL from this server. " +#~ "We've tried to redirect you to the" +#~ " new location of this page, but " +#~ "it may not be the right one." +#~ msgstr "" +#~ "<strong>Poznámka:</strong> Stránka, kterou hledáte," +#~ " neexistuje.<br>Snažili jsme se najít nové" +#~ " umístění této stránky, ale nepovedlo " +#~ "se." + diff --git a/sphinx/locale/de/LC_MESSAGES/sphinx.js b/sphinx/locale/de/LC_MESSAGES/sphinx.js index 4079beace..542c094f9 100644 --- a/sphinx/locale/de/LC_MESSAGES/sphinx.js +++ b/sphinx/locale/de/LC_MESSAGES/sphinx.js @@ -1 +1 @@ -Documentation.addTranslations({"locale": "de", "plural_expr": "(n != 1)", "messages": {"Search Results": "Suchergebnisse", "Your search did not match any documents. Please make sure that all words are spelled correctly and that you've selected enough categories.": "Es wurden keine Dokumente gefunden. Haben Sie alle Suchworte richtig geschrieben und gen\u00fcgend Kategorien ausgew\u00e4hlt?", "Getting search index...": "Suchindex wird geladen...", "Permalink to this headline": "Permalink zu dieser \u00dcberschrift", "Searching": "Suchen...", "Permalink to this definition": "Permalink zu dieser Definition", "Hide Search Matches": "Suchergebnisse ausblenden", "Search finished, found %s page(s) matching the search query.": "Suche beendet, %s Seite(n) mit Ergebnissen wurden gefunden."}}); \ No newline at end of file +Documentation.addTranslations({"locale": "de", "plural_expr": "(n != 1)", "messages": {"module, in ": "Modul, in ", "Preparing search...": "Suche wird vorbereitet...", "Your search did not match any documents. Please make sure that all words are spelled correctly and that you've selected enough categories.": "Es wurden keine Dokumente gefunden. Haben Sie alle Suchworte richtig geschrieben und gen\u00fcgend Kategorien ausgew\u00e4hlt?", "Search finished, found %s page(s) matching the search query.": "Suche beendet, %s Seite(n) mit Ergebnissen wurden gefunden.", ", in ": ", in ", "Permalink to this headline": "Permalink zu dieser \u00dcberschrift", "Searching": "Suchen...", "Permalink to this definition": "Permalink zu dieser Definition", "Hide Search Matches": "Suchergebnisse ausblenden", "Search Results": "Suchergebnisse"}}); \ No newline at end of file diff --git a/sphinx/locale/de/LC_MESSAGES/sphinx.mo b/sphinx/locale/de/LC_MESSAGES/sphinx.mo index a4df22d76..1f8f8d2d7 100644 Binary files a/sphinx/locale/de/LC_MESSAGES/sphinx.mo and b/sphinx/locale/de/LC_MESSAGES/sphinx.mo differ diff --git a/sphinx/locale/de/LC_MESSAGES/sphinx.po b/sphinx/locale/de/LC_MESSAGES/sphinx.po index b12913ad3..a830aeefb 100644 --- a/sphinx/locale/de/LC_MESSAGES/sphinx.po +++ b/sphinx/locale/de/LC_MESSAGES/sphinx.po @@ -7,7 +7,7 @@ msgstr "" "Project-Id-Version: PROJECT VERSION\n" "Report-Msgid-Bugs-To: EMAIL@ADDRESS\n" "POT-Creation-Date: 2008-08-07 21:40+0200\n" -"PO-Revision-Date: 2008-09-06 19:13+0200\n" +"PO-Revision-Date: 2009-01-24 18:43+0000\n" "Last-Translator: Horst Gutmann <zerok@zerokspot.com>\n" "Language-Team: de <LL@li.org>\n" "Plural-Forms: nplurals=2; plural=(n != 1)\n" @@ -16,223 +16,243 @@ msgstr "" "Content-Transfer-Encoding: 8bit\n" "Generated-By: Babel 0.9.3\n" -#: sphinx/builder.py:391 -#, python-format -msgid "%b %d, %Y" -msgstr "%d. %m. %Y" - -#: sphinx/builder.py:410 sphinx/templates/defindex.html:21 -msgid "General Index" -msgstr "Allgemeiner Index" - -#: sphinx/builder.py:410 -msgid "index" -msgstr "Index" - -#: sphinx/builder.py:412 sphinx/htmlhelp.py:155 -#: sphinx/templates/defindex.html:19 sphinx/templates/modindex.html:2 -#: sphinx/templates/modindex.html:13 -msgid "Global Module Index" -msgstr "Globaler Modulindex" - -#: sphinx/builder.py:412 -msgid "modules" -msgstr "Module" - -#: sphinx/builder.py:448 -msgid "next" -msgstr "weiter" - -#: sphinx/builder.py:455 -msgid "previous" -msgstr "zurück" - -#: sphinx/builder.py:1092 -msgid "Builtins" -msgstr "Builtins" - -#: sphinx/builder.py:1094 -msgid "Module level" -msgstr "Modulebene" - -#: sphinx/environment.py:108 sphinx/latexwriter.py:129 +#: sphinx/environment.py:104 sphinx/writers/latex.py:170 #, python-format msgid "%B %d, %Y" msgstr "%d. %m. %Y" -#: sphinx/htmlwriter.py:73 sphinx/static/doctools.js:143 -msgid "Permalink to this definition" -msgstr "Permalink zu dieser Definition" - -#: sphinx/htmlwriter.py:379 sphinx/static/doctools.js:136 -msgid "Permalink to this headline" -msgstr "Permalink zu dieser Überschrift" - -#: sphinx/latexwriter.py:143 -msgid "Release" -msgstr "Release" - -#: sphinx/latexwriter.py:188 -msgid "Module index" -msgstr "Modulindex" - -#: sphinx/latexwriter.py:190 sphinx/templates/genindex-single.html:2 +#: sphinx/environment.py:300 sphinx/templates/genindex-single.html:2 #: sphinx/templates/genindex-split.html:2 #: sphinx/templates/genindex-split.html:5 sphinx/templates/genindex.html:2 #: sphinx/templates/genindex.html:5 sphinx/templates/genindex.html:48 +#: sphinx/templates/layout.html:126 sphinx/writers/latex.py:176 msgid "Index" msgstr "Stichwortverzeichnis" -#: sphinx/roles.py:52 sphinx/directives/desc.py:514 +#: sphinx/environment.py:301 sphinx/writers/latex.py:175 +msgid "Module Index" +msgstr "Modulindex" + +#: sphinx/environment.py:302 sphinx/templates/defindex.html:16 +msgid "Search Page" +msgstr "Suche" + +#: sphinx/roles.py:53 sphinx/directives/desc.py:580 #, python-format msgid "environment variable; %s" msgstr "Umgebungsvariable; %s" -#: sphinx/roles.py:59 +#: sphinx/roles.py:60 #, python-format msgid "Python Enhancement Proposals!PEP %s" msgstr "Python Enhancement Proposals!PEP %s" -#: sphinx/textwriter.py:151 +#: sphinx/builders/changes.py:64 +msgid "Builtins" +msgstr "Builtins" + +#: sphinx/builders/changes.py:66 +msgid "Module level" +msgstr "Modulebene" + +#: sphinx/builders/html.py:118 #, python-format -msgid "Platform: %s" -msgstr "Plattform: %s" +msgid "%b %d, %Y" +msgstr "%d. %m. %Y" -#: sphinx/textwriter.py:353 -msgid "[image]" -msgstr "[Bild]" +#: sphinx/builders/html.py:137 sphinx/templates/defindex.html:21 +msgid "General Index" +msgstr "Allgemeiner Index" -#: sphinx/directives/desc.py:26 +#: sphinx/builders/html.py:137 +msgid "index" +msgstr "Index" + +#: sphinx/builders/html.py:139 sphinx/builders/htmlhelp.py:182 +#: sphinx/builders/qthelp.py:131 sphinx/templates/defindex.html:19 +#: sphinx/templates/modindex.html:2 sphinx/templates/modindex.html:13 +msgid "Global Module Index" +msgstr "Globaler Modulindex" + +#: sphinx/builders/html.py:139 +msgid "modules" +msgstr "Module" + +#: sphinx/builders/html.py:179 +msgid "next" +msgstr "weiter" + +#: sphinx/builders/html.py:186 +msgid "previous" +msgstr "zurück" + +#: sphinx/builders/latex.py:155 sphinx/builders/pdf.py:162 +msgid " (in " +msgstr " (in " + +#: sphinx/directives/desc.py:25 #, python-format msgid "%s() (built-in function)" msgstr "%s() (eingebaute Funktion)" -#: sphinx/directives/desc.py:27 sphinx/directives/desc.py:41 -#: sphinx/directives/desc.py:53 +#: sphinx/directives/desc.py:26 sphinx/directives/desc.py:42 +#: sphinx/directives/desc.py:54 #, python-format msgid "%s() (in module %s)" msgstr "%s() (in Modul %s)" -#: sphinx/directives/desc.py:30 +#: sphinx/directives/desc.py:29 #, python-format msgid "%s (built-in variable)" msgstr "%s (eingebaute Variable)" -#: sphinx/directives/desc.py:31 sphinx/directives/desc.py:65 +#: sphinx/directives/desc.py:30 sphinx/directives/desc.py:78 #, python-format msgid "%s (in module %s)" msgstr "%s (in Modul %s)" #: sphinx/directives/desc.py:33 #, python-format +msgid "%s (built-in class)" +msgstr "%s (eingebaute Klasse)" + +#: sphinx/directives/desc.py:34 +#, python-format msgid "%s (class in %s)" msgstr "%s (Klasse in %s)" -#: sphinx/directives/desc.py:45 +#: sphinx/directives/desc.py:46 #, python-format msgid "%s() (%s.%s method)" msgstr "%s() (Methode von %s.%s)" -#: sphinx/directives/desc.py:47 +#: sphinx/directives/desc.py:48 #, python-format msgid "%s() (%s method)" msgstr "%s() (Methode von %s)" -#: sphinx/directives/desc.py:57 +#: sphinx/directives/desc.py:58 #, python-format msgid "%s() (%s.%s static method)" msgstr "%s() (statische Methode von %s.%s)" -#: sphinx/directives/desc.py:59 +#: sphinx/directives/desc.py:60 #, python-format msgid "%s() (%s static method)" msgstr "%s() (statische Methode von %s)" -#: sphinx/directives/desc.py:69 +#: sphinx/directives/desc.py:82 #, python-format msgid "%s (%s.%s attribute)" msgstr "%s (Attribut von %s.%s)" -#: sphinx/directives/desc.py:71 +#: sphinx/directives/desc.py:84 #, python-format msgid "%s (%s attribute)" msgstr "%s (Attribut von %s)" -#: sphinx/directives/desc.py:73 +#: sphinx/directives/desc.py:86 #, python-format msgid "%s (C function)" msgstr "%s (C-Funktion)" -#: sphinx/directives/desc.py:75 +#: sphinx/directives/desc.py:88 #, python-format msgid "%s (C member)" msgstr "%s (C-Member)" -#: sphinx/directives/desc.py:77 +#: sphinx/directives/desc.py:90 #, python-format msgid "%s (C macro)" msgstr "%s (C-Makro)" -#: sphinx/directives/desc.py:79 +#: sphinx/directives/desc.py:92 #, python-format msgid "%s (C type)" msgstr "%s (C-Typ)" -#: sphinx/directives/desc.py:81 +#: sphinx/directives/desc.py:94 #, python-format msgid "%s (C variable)" msgstr "%s (C-Variable)" -#: sphinx/directives/desc.py:99 +#: sphinx/directives/desc.py:112 msgid "Raises" msgstr "Verursacht:" -#: sphinx/directives/desc.py:103 +#: sphinx/directives/desc.py:116 msgid "Variable" msgstr "Variable" -#: sphinx/directives/desc.py:106 +#: sphinx/directives/desc.py:119 msgid "Returns" msgstr "Rückgabe" -#: sphinx/directives/desc.py:113 +#: sphinx/directives/desc.py:128 msgid "Return type" msgstr "Rückgabetyp" -#: sphinx/directives/desc.py:140 +#: sphinx/directives/desc.py:213 +msgid "Parameter" +msgstr "Parameter" + +#: sphinx/directives/desc.py:217 msgid "Parameters" msgstr "Parameter" -#: sphinx/directives/desc.py:402 +#: sphinx/directives/desc.py:465 #, python-format -msgid "command line option; %s" -msgstr "Kommandozeilenoption; %s" +msgid "%scommand line option; %s" +msgstr "%sKommandozeilenoption; %s" -#: sphinx/directives/other.py:102 +#: sphinx/directives/other.py:101 msgid "Platforms: " msgstr "Plattformen: " -#: sphinx/directives/other.py:107 +#: sphinx/directives/other.py:106 #, python-format msgid "%s (module)" msgstr "%s (Modul)" -#: sphinx/directives/other.py:147 +#: sphinx/directives/other.py:146 msgid "Section author: " msgstr "Autor des Abschnitts: " -#: sphinx/directives/other.py:149 +#: sphinx/directives/other.py:148 msgid "Module author: " msgstr "Autor des Moduls: " -#: sphinx/directives/other.py:151 +#: sphinx/directives/other.py:150 msgid "Author: " msgstr "Autor: " -#: sphinx/directives/other.py:233 +#: sphinx/directives/other.py:249 msgid "See also" msgstr "Siehe auch" +#: sphinx/ext/autodoc.py:442 +#, python-format +msgid " Bases: %s" +msgstr " Basisklassen: %s" + +#: sphinx/ext/autodoc.py:566 sphinx/ext/autodoc.py:583 +#, python-format +msgid "alias of :class:`%s`" +msgstr "Alias von :class:`%s`" + +#: sphinx/ext/todo.py:31 +msgid "Todo" +msgstr "Zu tun" + +#: sphinx/ext/todo.py:75 +#, python-format +msgid "(The original entry is located in %s, line %d and can be found " +msgstr "(Der Eintrag steht in %s, Zeile %s, siehe " + +#: sphinx/ext/todo.py:81 +msgid "here" +msgstr "hier" + #: sphinx/locale/__init__.py:15 msgid "Attention" msgstr "Achtung" @@ -316,30 +336,47 @@ msgstr "Statement" msgid "built-in function" msgstr "eingebaute Funktion" -#: sphinx/static/doctools.js:172 +#: sphinx/static/doctools.js:139 sphinx/writers/html.py:425 +msgid "Permalink to this headline" +msgstr "Permalink zu dieser Überschrift" + +#: sphinx/static/doctools.js:145 sphinx/writers/html.py:80 +msgid "Permalink to this definition" +msgstr "Permalink zu dieser Definition" + +#: sphinx/static/doctools.js:174 msgid "Hide Search Matches" msgstr "Suchergebnisse ausblenden" -#: sphinx/static/searchtools.js:242 -#, fuzzy +#: sphinx/static/searchtools.js:274 msgid "Searching" msgstr "Suchen..." -#: sphinx/static/searchtools.js:246 -msgid "Getting search index..." -msgstr "Suchindex wird geladen..." +#: sphinx/static/searchtools.js:279 +msgid "Preparing search..." +msgstr "Suche wird vorbereitet..." -#: sphinx/static/searchtools.js:384 sphinx/templates/search.html:18 +#: sphinx/static/searchtools.js:338 +msgid "module, in " +msgstr "Modul, in " + +#: sphinx/static/searchtools.js:347 +msgid ", in " +msgstr ", in " + +#: sphinx/static/searchtools.js:453 sphinx/templates/search.html:25 msgid "Search Results" msgstr "Suchergebnisse" -#: sphinx/static/searchtools.js:386 +#: sphinx/static/searchtools.js:455 msgid "" "Your search did not match any documents. Please make sure that all words " "are spelled correctly and that you've selected enough categories." -msgstr "Es wurden keine Dokumente gefunden. Haben Sie alle Suchworte richtig geschrieben und genügend Kategorien ausgewählt?" +msgstr "" +"Es wurden keine Dokumente gefunden. Haben Sie alle Suchworte richtig " +"geschrieben und genügend Kategorien ausgewählt?" -#: sphinx/static/searchtools.js:389 +#: sphinx/static/searchtools.js:457 #, python-format msgid "Search finished, found %s page(s) matching the search query." msgstr "Suche beendet, %s Seite(n) mit Ergebnissen wurden gefunden." @@ -360,10 +397,6 @@ msgstr "Vollständiges Inhaltsverzeichnis" msgid "lists all sections and subsections" msgstr "Liste aller Kapitel und Unterkapitel" -#: sphinx/templates/defindex.html:16 -msgid "Search page" -msgstr "Suche" - #: sphinx/templates/defindex.html:17 msgid "search this documentation" msgstr "Durchsuche diese Dokumentation" @@ -407,27 +440,23 @@ msgstr "Inhalt" msgid "Previous topic" msgstr "Vorheriges Thema" -#: sphinx/templates/layout.html:47 +#: sphinx/templates/layout.html:48 msgid "previous chapter" msgstr "vorheriges Kapitel" -#: sphinx/templates/layout.html:50 +#: sphinx/templates/layout.html:51 msgid "Next topic" msgstr "Nächstes Thema" -#: sphinx/templates/layout.html:51 +#: sphinx/templates/layout.html:53 msgid "next chapter" msgstr "nächstes Kapitel" -#: sphinx/templates/layout.html:55 +#: sphinx/templates/layout.html:58 msgid "This Page" msgstr "Diese Seite" -#: sphinx/templates/layout.html:59 -msgid "Suggest Change" -msgstr "Änderung vorschlagen" - -#: sphinx/templates/layout.html:60 sphinx/templates/layout.html:62 +#: sphinx/templates/layout.html:61 msgid "Show Source" msgstr "Quelltext anzeigen" @@ -435,60 +464,48 @@ msgstr "Quelltext anzeigen" msgid "Quick search" msgstr "Schnellsuche" -#: sphinx/templates/layout.html:71 -msgid "Keyword search" -msgstr "Stichwortsuche" - -#: sphinx/templates/layout.html:73 +#: sphinx/templates/layout.html:74 msgid "Go" msgstr "Los" #: sphinx/templates/layout.html:78 -msgid "Enter a module, class or function name." -msgstr "Gib einen Modul-, Klassen- oder Funktionsnamen an." +msgid "Enter search terms or a module, class or function name." +msgstr "Geben Sie einen Modul-, Klassen- oder Funktionsnamen einn." -#: sphinx/templates/layout.html:118 +#: sphinx/templates/layout.html:115 #, python-format msgid "Search within %(docstitle)s" msgstr "Suche in %(docstitle)s" -#: sphinx/templates/layout.html:127 +#: sphinx/templates/layout.html:124 msgid "About these documents" msgstr "Über diese Dokumentation" -#: sphinx/templates/layout.html:129 -msgid "Global table of contents" -msgstr "Globales Inhaltsverzeichnis" - -#: sphinx/templates/layout.html:130 -msgid "Global index" -msgstr "Globale Stichwortverzeichnis" - -#: sphinx/templates/layout.html:131 sphinx/templates/search.html:2 +#: sphinx/templates/layout.html:127 sphinx/templates/search.html:2 #: sphinx/templates/search.html:5 msgid "Search" msgstr "Suche" -#: sphinx/templates/layout.html:133 +#: sphinx/templates/layout.html:129 msgid "Copyright" msgstr "Copyright" -#: sphinx/templates/layout.html:178 +#: sphinx/templates/layout.html:174 #, python-format msgid "© <a href=\"%(path)s\">Copyright</a> %(copyright)s." msgstr "© <a href=\"%(path)s\">Copyright</a> %(copyright)s." -#: sphinx/templates/layout.html:180 +#: sphinx/templates/layout.html:176 #, python-format msgid "© Copyright %(copyright)s." msgstr "© Copyright %(copyright)s." -#: sphinx/templates/layout.html:183 +#: sphinx/templates/layout.html:179 #, python-format msgid "Last updated on %(last_updated)s." msgstr "Zuletzt aktualisiert am %(last_updated)s." -#: sphinx/templates/layout.html:186 +#: sphinx/templates/layout.html:182 #, python-format msgid "" "Created using <a href=\"http://sphinx.pocoo.org/\">Sphinx</a> " @@ -497,15 +514,7 @@ msgstr "" "Mit <a href=\"http://sphinx.pocoo.org/\">Sphinx</a> %(sphinx_version)s " "erstellt." -#: sphinx/templates/modindex.html:15 -msgid "Most popular modules:" -msgstr "Beliebteste Module:" - -#: sphinx/templates/modindex.html:24 -msgid "Show modules only available on these platforms" -msgstr "Zeige nur Module, die auf diesen Plattformen verfügbar sind" - -#: sphinx/templates/modindex.html:56 +#: sphinx/templates/modindex.html:36 msgid "Deprecated" msgstr "Veraltet" @@ -514,34 +523,25 @@ msgstr "Veraltet" msgid "Search %(docstitle)s" msgstr "Suche in %(docstitle)s" -#: sphinx/templates/page.html:8 +#: sphinx/templates/search.html:9 msgid "" -"<strong>Note:</strong> You requested an out-of-date URL from this server." -" We've tried to redirect you to the new location of this page, but it may" -" not be the right one." -msgstr "" -"<strong>Anmerkung:</strong> Du hast eine nicht länger gültige URL von " -"diesem Server angefragt. Wir haben versucht dich auf die neue Adresse " -"dieser Seite umzuleiten, aber dies muss nicht die richtige Seite sein." +"Please activate JavaScript to enable the search\n" +" functionality." +msgstr "Bitte aktivieren Sie JavaScript, wenn Sie die Suchfunktion nutzen wollen." -#: sphinx/templates/search.html:7 +#: sphinx/templates/search.html:14 msgid "" "From here you can search these documents. Enter your search\n" " words into the box below and click \"search\". Note that the search\n" " function will automatically search for all of the words. Pages\n" -" containing less words won't appear in the result list." -msgstr "" -"Von hier aus kannst du die Dokumentation durchsuchen. Gib deine " -"Suchbegriffe in das untenstehende Feld ein und klicke auf \"suchen\". " -"Bitte beachte, dass die Suchfunktion automatisch nach all diesen Worten " -"suchen wird. Seiten, die nicht alle Worte enthalten, werden nicht in der " -"Ergebnisliste erscheinen." +" containing fewer words won't appear in the result list." +msgstr "Von hier aus können Sie die Dokumentation durchsuchen. Geben Sie Ihre Suchbegriffe in das untenstehende Feld ein und klicken Sie auf \"Suchen\". Bitte beachten Sie, dass die Suchfunktion automatisch nach all diesen Worten suchen wird. Seiten, die nicht alle Worte enthalten, werden nicht in der Ergebnisliste erscheinen." -#: sphinx/templates/search.html:14 +#: sphinx/templates/search.html:21 msgid "search" msgstr "suchen" -#: sphinx/templates/search.html:20 +#: sphinx/templates/search.html:27 msgid "Your search did not match any results." msgstr "Deine Suche ergab leider keine Treffer." @@ -573,3 +573,16 @@ msgstr "C API-Änderungen" msgid "Other changes" msgstr "Andere Änderungen" +#: sphinx/writers/latex.py:173 +msgid "Release" +msgstr "Release" + +#: sphinx/writers/text.py:166 +#, python-format +msgid "Platform: %s" +msgstr "Plattform: %s" + +#: sphinx/writers/text.py:427 +msgid "[image]" +msgstr "[Bild]" + diff --git a/sphinx/locale/es/LC_MESSAGES/sphinx.js b/sphinx/locale/es/LC_MESSAGES/sphinx.js index 0864e7939..a8e2fd62e 100644 --- a/sphinx/locale/es/LC_MESSAGES/sphinx.js +++ b/sphinx/locale/es/LC_MESSAGES/sphinx.js @@ -1 +1 @@ -Documentation.addTranslations({"locale": "es", "plural_expr": "(n != 1)", "messages": {"Search Results": "Resultados de la b\u00fasqueda", "Preparing search...": "Preparando la b\u00fasqueda", "Your search did not match any documents. Please make sure that all words are spelled correctly and that you've selected enough categories.": "La b\u00fasqueda no dio ning\u00fan resultado. Por favor aseg\u00farese que escribi\u00f3 todas las palabras correctamente y que ha seleccionado suficientes categor\u00edas", "Search finished, found %s page(s) matching the search query.": "B\u00fasqueda finalizada, se han encontrado %s p\u00e1gina(s) que concuerdan con su consulta", "Permalink to this headline": "Enlazar permanentemente con este t\u00edtulo", "Searching": "Buscando", "Permalink to this definition": "Enlazar permanentemente con esta definici\u00f3n", "Hide Search Matches": "Coincidencias de la b\u00fasqueda"}}); \ No newline at end of file +Documentation.addTranslations({"locale": "es", "plural_expr": "(n != 1)", "messages": {"module, in ": "m\u00f3dulo", "Preparing search...": "Preparando la b\u00fasqueda", "Your search did not match any documents. Please make sure that all words are spelled correctly and that you've selected enough categories.": "La b\u00fasqueda no dio ning\u00fan resultado. Por favor aseg\u00farese que escribi\u00f3 todas las palabras correctamente y que ha seleccionado suficientes categor\u00edas", "Search finished, found %s page(s) matching the search query.": "B\u00fasqueda finalizada, se han encontrado %s p\u00e1gina(s) que concuerdan con su consulta", ", in ": "", "Permalink to this headline": "Enlazar permanentemente con este t\u00edtulo", "Searching": "Buscando", "Permalink to this definition": "Enlazar permanentemente con esta definici\u00f3n", "Hide Search Matches": "Coincidencias de la b\u00fasqueda", "Search Results": "Resultados de la b\u00fasqueda"}}); \ No newline at end of file diff --git a/sphinx/locale/es/LC_MESSAGES/sphinx.mo b/sphinx/locale/es/LC_MESSAGES/sphinx.mo index 1d5d4c7be..2989194c9 100644 Binary files a/sphinx/locale/es/LC_MESSAGES/sphinx.mo and b/sphinx/locale/es/LC_MESSAGES/sphinx.mo differ diff --git a/sphinx/locale/es/LC_MESSAGES/sphinx.po b/sphinx/locale/es/LC_MESSAGES/sphinx.po index 44b17a2c9..09ebda8b7 100644 --- a/sphinx/locale/es/LC_MESSAGES/sphinx.po +++ b/sphinx/locale/es/LC_MESSAGES/sphinx.po @@ -1,4 +1,4 @@ -# Translations template for Sphinx. +# Spanish translations for Sphinx. # Copyright (C) 2008 ORGANIZATION # This file is distributed under the same license as the Sphinx project. # FIRST AUTHOR <EMAIL@ADDRESS>, 2008. @@ -8,240 +8,256 @@ msgstr "" "Project-Id-Version: Sphinx 0.5\n" "Report-Msgid-Bugs-To: guillem@torroja.dmt.upm.es\n" "POT-Creation-Date: 2008-09-11 23:58+0200\n" -"PO-Revision-Date: 2008-10-23 22:11+0200\n" +"PO-Revision-Date: 2009-01-24 18:39+0000\n" "Last-Translator: Guillem Borrell <guillem@torroja.dmt.upm.es>\n" -"Language-Team: LANGUAGE <LL@li.org>\n" +"Language-Team: es <LL@li.org>\n" +"Plural-Forms: nplurals=2; plural=(n != 1)\n" "MIME-Version: 1.0\n" "Content-Type: text/plain; charset=utf-8\n" "Content-Transfer-Encoding: 8bit\n" "Generated-By: Babel 0.9.3\n" -#: sphinx/builder.py:400 -#, python-format -msgid "%b %d, %Y" -msgstr "%d %b, %Y" - -#: sphinx/builder.py:419 sphinx/templates/defindex.html:21 -msgid "General Index" -msgstr "Índice General" - -#: sphinx/builder.py:419 -msgid "index" -msgstr "índice" - -#: sphinx/builder.py:421 sphinx/htmlhelp.py:155 -#: sphinx/templates/defindex.html:19 sphinx/templates/modindex.html:2 -#: sphinx/templates/modindex.html:13 -msgid "Global Module Index" -msgstr "Índice Global de Módulos" - -#: sphinx/builder.py:421 -msgid "modules" -msgstr "módulos" - -#: sphinx/builder.py:457 -msgid "next" -msgstr "siguiente" - -#: sphinx/builder.py:464 -msgid "previous" -msgstr "anterior" - -#: sphinx/builder.py:1108 -#, fuzzy -msgid "Builtins" -msgstr "Funciones de base" - -#: sphinx/builder.py:1110 -#, fuzzy -msgid "Module level" -msgstr "Módulos" - -#: sphinx/environment.py:107 sphinx/latexwriter.py:129 -#, python-format, fuzzy +#: sphinx/environment.py:104 sphinx/writers/latex.py:170 +#, fuzzy, python-format msgid "%B %d, %Y" msgstr "%d de %B de %Y" -#: sphinx/environment.py:270 sphinx/latexwriter.py:190 -#: sphinx/templates/genindex-single.html:2 +#: sphinx/environment.py:300 sphinx/templates/genindex-single.html:2 #: sphinx/templates/genindex-split.html:2 #: sphinx/templates/genindex-split.html:5 sphinx/templates/genindex.html:2 #: sphinx/templates/genindex.html:5 sphinx/templates/genindex.html:48 +#: sphinx/templates/layout.html:126 sphinx/writers/latex.py:176 msgid "Index" msgstr "Índice" -#: sphinx/environment.py:271 sphinx/latexwriter.py:188 +#: sphinx/environment.py:301 sphinx/writers/latex.py:175 msgid "Module Index" msgstr "Índice de Módulos" -#: sphinx/environment.py:272 sphinx/templates/defindex.html:16 +#: sphinx/environment.py:302 sphinx/templates/defindex.html:16 msgid "Search Page" msgstr "Página de Búsqueda" -#: sphinx/htmlwriter.py:73 sphinx/static/doctools.js:145 -msgid "Permalink to this definition" -msgstr "Enlazar permanentemente con esta definición" - -#: sphinx/htmlwriter.py:375 sphinx/static/doctools.js:139 -msgid "Permalink to this headline" -msgstr "Enlazar permanentemente con este título" - -#: sphinx/latexwriter.py:143 -#, fuzzy -msgid "Release" -msgstr "Versión" - -#: sphinx/roles.py:52 sphinx/directives/desc.py:514 +#: sphinx/roles.py:53 sphinx/directives/desc.py:580 #, python-format msgid "environment variable; %s" msgstr "variables de entorno; %s" -#: sphinx/roles.py:59 +#: sphinx/roles.py:60 #, python-format msgid "Python Enhancement Proposals!PEP %s" msgstr "Python Enhancement Proposals!PEP %s" -#: sphinx/textwriter.py:151 +#: sphinx/builders/changes.py:64 +#, fuzzy +msgid "Builtins" +msgstr "Funciones de base" + +#: sphinx/builders/changes.py:66 +#, fuzzy +msgid "Module level" +msgstr "Módulos" + +#: sphinx/builders/html.py:118 #, python-format -msgid "Platform: %s" -msgstr "Plataforma: %s" +msgid "%b %d, %Y" +msgstr "%d %b, %Y" -#: sphinx/textwriter.py:353 -msgid "[image]" -msgstr "[imagen]" +#: sphinx/builders/html.py:137 sphinx/templates/defindex.html:21 +msgid "General Index" +msgstr "Índice General" -#: sphinx/directives/desc.py:26 -#, python-format, fuzzy +#: sphinx/builders/html.py:137 +msgid "index" +msgstr "índice" + +#: sphinx/builders/html.py:139 sphinx/builders/htmlhelp.py:182 +#: sphinx/builders/qthelp.py:131 sphinx/templates/defindex.html:19 +#: sphinx/templates/modindex.html:2 sphinx/templates/modindex.html:13 +msgid "Global Module Index" +msgstr "Índice Global de Módulos" + +#: sphinx/builders/html.py:139 +msgid "modules" +msgstr "módulos" + +#: sphinx/builders/html.py:179 +msgid "next" +msgstr "siguiente" + +#: sphinx/builders/html.py:186 +msgid "previous" +msgstr "anterior" + +#: sphinx/builders/latex.py:155 sphinx/builders/pdf.py:162 +msgid " (in " +msgstr "" + +#: sphinx/directives/desc.py:25 +#, fuzzy, python-format msgid "%s() (built-in function)" msgstr "%s() (función de base)" -#: sphinx/directives/desc.py:27 sphinx/directives/desc.py:41 -#: sphinx/directives/desc.py:53 +#: sphinx/directives/desc.py:26 sphinx/directives/desc.py:42 +#: sphinx/directives/desc.py:54 #, python-format msgid "%s() (in module %s)" msgstr "%s() (en el módulo %s)" -#: sphinx/directives/desc.py:30 -#, python-format, fuzzy +#: sphinx/directives/desc.py:29 +#, fuzzy, python-format msgid "%s (built-in variable)" msgstr "%s (variable de base)" -#: sphinx/directives/desc.py:31 sphinx/directives/desc.py:65 +#: sphinx/directives/desc.py:30 sphinx/directives/desc.py:78 #, python-format msgid "%s (in module %s)" msgstr "%s (en el módulo %s)" #: sphinx/directives/desc.py:33 +#, fuzzy, python-format +msgid "%s (built-in class)" +msgstr "%s (variable de base)" + +#: sphinx/directives/desc.py:34 #, python-format msgid "%s (class in %s)" msgstr "%s (clase en %s)" -#: sphinx/directives/desc.py:45 +#: sphinx/directives/desc.py:46 #, python-format msgid "%s() (%s.%s method)" msgstr "%s() (%s.%s método)" -#: sphinx/directives/desc.py:47 +#: sphinx/directives/desc.py:48 #, python-format msgid "%s() (%s method)" msgstr "%s() (%s método)" -#: sphinx/directives/desc.py:57 +#: sphinx/directives/desc.py:58 #, python-format msgid "%s() (%s.%s static method)" msgstr "%s() (%s.%s método estático)" -#: sphinx/directives/desc.py:59 +#: sphinx/directives/desc.py:60 #, python-format msgid "%s() (%s static method)" msgstr "%s() (%s método estático)" -#: sphinx/directives/desc.py:69 +#: sphinx/directives/desc.py:82 #, python-format msgid "%s (%s.%s attribute)" msgstr "%s (%s.%s atributo)" -#: sphinx/directives/desc.py:71 +#: sphinx/directives/desc.py:84 #, python-format msgid "%s (%s attribute)" msgstr "%s (%s atributo)" -#: sphinx/directives/desc.py:73 +#: sphinx/directives/desc.py:86 #, python-format msgid "%s (C function)" msgstr "%s (función C)" -#: sphinx/directives/desc.py:75 +#: sphinx/directives/desc.py:88 #, python-format msgid "%s (C member)" msgstr "%s (miembro C)" -#: sphinx/directives/desc.py:77 +#: sphinx/directives/desc.py:90 #, python-format msgid "%s (C macro)" msgstr "%s (macro C)" -#: sphinx/directives/desc.py:79 +#: sphinx/directives/desc.py:92 #, python-format msgid "%s (C type)" msgstr "%s (tipo C)" -#: sphinx/directives/desc.py:81 +#: sphinx/directives/desc.py:94 #, python-format msgid "%s (C variable)" msgstr "%s (variable C)" -#: sphinx/directives/desc.py:99 +#: sphinx/directives/desc.py:112 msgid "Raises" msgstr "Muestra" -#: sphinx/directives/desc.py:103 +#: sphinx/directives/desc.py:116 msgid "Variable" msgstr "Variable" -#: sphinx/directives/desc.py:106 +#: sphinx/directives/desc.py:119 msgid "Returns" msgstr "Devuelve" -#: sphinx/directives/desc.py:113 +#: sphinx/directives/desc.py:128 #, fuzzy msgid "Return type" msgstr "Tipo del argumento devuelto" -#: sphinx/directives/desc.py:140 +#: sphinx/directives/desc.py:213 +#, fuzzy +msgid "Parameter" +msgstr "Parámetros" + +#: sphinx/directives/desc.py:217 msgid "Parameters" msgstr "Parámetros" -#: sphinx/directives/desc.py:402 -#, python-format -msgid "command line option; %s" -msgstr "Opciones en línea de comandos; %s" +#: sphinx/directives/desc.py:465 +#, fuzzy, python-format +msgid "%scommand line option; %s" +msgstr "%sOpciones en línea de comandos; %s" -#: sphinx/directives/other.py:102 +#: sphinx/directives/other.py:101 msgid "Platforms: " msgstr "Plataformas:" -#: sphinx/directives/other.py:107 +#: sphinx/directives/other.py:106 #, python-format msgid "%s (module)" msgstr "%s (módulo)" -#: sphinx/directives/other.py:147 +#: sphinx/directives/other.py:146 msgid "Section author: " msgstr "Autor de la sección" -#: sphinx/directives/other.py:149 +#: sphinx/directives/other.py:148 msgid "Module author: " msgstr "Autor del módulo" -#: sphinx/directives/other.py:151 +#: sphinx/directives/other.py:150 msgid "Author: " msgstr "Autor:" -#: sphinx/directives/other.py:233 +#: sphinx/directives/other.py:249 msgid "See also" msgstr "Ver también" +#: sphinx/ext/autodoc.py:442 +#, python-format +msgid " Bases: %s" +msgstr "" + +#: sphinx/ext/autodoc.py:566 sphinx/ext/autodoc.py:583 +#, python-format +msgid "alias of :class:`%s`" +msgstr "" + +#: sphinx/ext/todo.py:31 +msgid "Todo" +msgstr "" + +#: sphinx/ext/todo.py:75 +#, python-format +msgid "(The original entry is located in %s, line %d and can be found " +msgstr "" + +#: sphinx/ext/todo.py:81 +msgid "here" +msgstr "" + #: sphinx/locale/__init__.py:15 msgid "Attention" msgstr "Atención" @@ -326,6 +342,14 @@ msgstr "sentencia" msgid "built-in function" msgstr "función de base" +#: sphinx/static/doctools.js:139 sphinx/writers/html.py:425 +msgid "Permalink to this headline" +msgstr "Enlazar permanentemente con este título" + +#: sphinx/static/doctools.js:145 sphinx/writers/html.py:80 +msgid "Permalink to this definition" +msgstr "Enlazar permanentemente con esta definición" + #: sphinx/static/doctools.js:174 #, fuzzy msgid "Hide Search Matches" @@ -339,20 +363,34 @@ msgstr "Buscando" msgid "Preparing search..." msgstr "Preparando la búsqueda" -#: sphinx/static/searchtools.js:401 sphinx/templates/search.html:18 +#: sphinx/static/searchtools.js:338 +#, fuzzy +msgid "module, in " +msgstr "módulo" + +#: sphinx/static/searchtools.js:347 +msgid ", in " +msgstr "" + +#: sphinx/static/searchtools.js:453 sphinx/templates/search.html:25 msgid "Search Results" msgstr "Resultados de la búsqueda" -#: sphinx/static/searchtools.js:403 +#: sphinx/static/searchtools.js:455 msgid "" "Your search did not match any documents. Please make sure that all words " "are spelled correctly and that you've selected enough categories." -msgstr "La búsqueda no dio ningún resultado. Por favor asegúrese que escribió todas las palabras correctamente y que ha seleccionado suficientes categorías" +msgstr "" +"La búsqueda no dio ningún resultado. Por favor asegúrese que escribió " +"todas las palabras correctamente y que ha seleccionado suficientes " +"categorías" -#: sphinx/static/searchtools.js:405 +#: sphinx/static/searchtools.js:457 #, python-format msgid "Search finished, found %s page(s) matching the search query." -msgstr "Búsqueda finalizada, se han encontrado %s página(s) que concuerdan con su consulta" +msgstr "" +"Búsqueda finalizada, se han encontrado %s página(s) que concuerdan con su" +" consulta" #: sphinx/templates/defindex.html:2 msgid "Overview" @@ -413,27 +451,23 @@ msgstr "Contenidos" msgid "Previous topic" msgstr "Tema anterior" -#: sphinx/templates/layout.html:47 +#: sphinx/templates/layout.html:48 msgid "previous chapter" msgstr "Capítulo anterior" -#: sphinx/templates/layout.html:50 +#: sphinx/templates/layout.html:51 msgid "Next topic" msgstr "Próximo tema" -#: sphinx/templates/layout.html:51 +#: sphinx/templates/layout.html:53 msgid "next chapter" msgstr "Próximo capítulo" -#: sphinx/templates/layout.html:55 +#: sphinx/templates/layout.html:58 msgid "This Page" msgstr "Esta página" -#: sphinx/templates/layout.html:59 -msgid "Suggest Change" -msgstr "Sugerir una modificación" - -#: sphinx/templates/layout.html:60 sphinx/templates/layout.html:62 +#: sphinx/templates/layout.html:61 msgid "Show Source" msgstr "Enseñar el código" @@ -441,75 +475,58 @@ msgstr "Enseñar el código" msgid "Quick search" msgstr "Búsqueda rápida" -#: sphinx/templates/layout.html:71 -msgid "Keyword search" -msgstr "Búsqueda por palabras clave" - -#: sphinx/templates/layout.html:73 +#: sphinx/templates/layout.html:74 msgid "Go" msgstr "Ir a" #: sphinx/templates/layout.html:78 -msgid "Enter a module, class or function name." +#, fuzzy +msgid "Enter search terms or a module, class or function name." msgstr "Introducir en nombre de un módulo, clase o función" -#: sphinx/templates/layout.html:118 +#: sphinx/templates/layout.html:115 #, python-format msgid "Search within %(docstitle)s" msgstr "Buscar en %(docstitle)s" -#: sphinx/templates/layout.html:127 +#: sphinx/templates/layout.html:124 msgid "About these documents" msgstr "Sobre este documento" -#: sphinx/templates/layout.html:129 -msgid "Global table of contents" -msgstr "Índice General" - -#: sphinx/templates/layout.html:130 -msgid "Global index" -msgstr "Índice Global" - -#: sphinx/templates/layout.html:131 sphinx/templates/search.html:2 +#: sphinx/templates/layout.html:127 sphinx/templates/search.html:2 #: sphinx/templates/search.html:5 msgid "Search" msgstr "Búsqueda" -#: sphinx/templates/layout.html:133 +#: sphinx/templates/layout.html:129 msgid "Copyright" msgstr "Copyright" -#: sphinx/templates/layout.html:178 +#: sphinx/templates/layout.html:174 #, python-format msgid "© <a href=\"%(path)s\">Copyright</a> %(copyright)s." msgstr "© <a href=\\\"%(path)s\\\">Copyright</a> %(copyright)s." -#: sphinx/templates/layout.html:180 +#: sphinx/templates/layout.html:176 #, python-format msgid "© Copyright %(copyright)s." msgstr "© Copyright %(copyright)s." -#: sphinx/templates/layout.html:183 +#: sphinx/templates/layout.html:179 #, python-format msgid "Last updated on %(last_updated)s." msgstr "Actualizado por última vez en %(last_updated)s." -#: sphinx/templates/layout.html:186 +#: sphinx/templates/layout.html:182 #, python-format msgid "" "Created using <a href=\"http://sphinx.pocoo.org/\">Sphinx</a> " "%(sphinx_version)s." -msgstr "Creado con <a href=\"http://sphinx.pocoo.org/\">Sphinx</a> %(sphinx_version)s." +msgstr "" +"Creado con <a href=\"http://sphinx.pocoo.org/\">Sphinx</a> " +"%(sphinx_version)s." -#: sphinx/templates/modindex.html:15 -msgid "Most popular modules:" -msgstr "Módulos más comunes:" - -#: sphinx/templates/modindex.html:24 -msgid "Show modules only available on these platforms" -msgstr "Mostrar sólo los módulos disponibles en estas plataformas" - -#: sphinx/templates/modindex.html:56 +#: sphinx/templates/modindex.html:36 msgid "Deprecated" msgstr "Obsoleto" @@ -518,26 +535,30 @@ msgstr "Obsoleto" msgid "Search %(docstitle)s" msgstr "Buscar en %(docstitle)s" -#: sphinx/templates/page.html:8 +#: sphinx/templates/search.html:9 msgid "" -"<strong>Note:</strong> You requested an out-of-date URL from this server." -" We've tried to redirect you to the new location of this page, but it may" -" not be the right one." -msgstr "<strong>Nota:</strong> Has solicitado una dirección desactualizada a este servidor. Hemos intentado redirigirte a la nueva dirección de la misma página pero puede no ser la correcta." +"Please activate JavaScript to enable the search\n" +" functionality." +msgstr "" -#: sphinx/templates/search.html:7 +#: sphinx/templates/search.html:14 +#, fuzzy msgid "" "From here you can search these documents. Enter your search\n" " words into the box below and click \"search\". Note that the search\n" " function will automatically search for all of the words. Pages\n" -" containing less words won't appear in the result list." -msgstr "Este es el diálogo de búsqueda. Introduce los términos en el diálogo siguiente y pulsa \"buscar\". El asistente buscará automáticamente todas las palabras. Las páginas que contengan menos palabras no aparecerán en la lista de resultados." +" containing fewer words won't appear in the result list." +msgstr "" +"Este es el diálogo de búsqueda. Introduce los términos en el diálogo " +"siguiente y pulsa \"buscar\". El asistente buscará automáticamente todas" +" las palabras. Las páginas que contengan menos palabras no aparecerán en" +" la lista de resultados." -#: sphinx/templates/search.html:14 +#: sphinx/templates/search.html:21 msgid "search" msgstr "buscar" -#: sphinx/templates/search.html:20 +#: sphinx/templates/search.html:27 msgid "Your search did not match any results." msgstr "Tu consulta no obtuvo ningún resultado" @@ -569,3 +590,17 @@ msgstr "Cambios en la API C" msgid "Other changes" msgstr "Otros cambios" +#: sphinx/writers/latex.py:173 +#, fuzzy +msgid "Release" +msgstr "Versión" + +#: sphinx/writers/text.py:166 +#, python-format +msgid "Platform: %s" +msgstr "Plataforma: %s" + +#: sphinx/writers/text.py:427 +msgid "[image]" +msgstr "[imagen]" + diff --git a/sphinx/locale/fi/LC_MESSAGES/sphinx.js b/sphinx/locale/fi/LC_MESSAGES/sphinx.js new file mode 100644 index 000000000..f654e7e11 --- /dev/null +++ b/sphinx/locale/fi/LC_MESSAGES/sphinx.js @@ -0,0 +1 @@ +Documentation.addTranslations({"locale": "fi", "plural_expr": "(n != 1)", "messages": {"module, in ": "", "Preparing search...": "Valmistellaan etsint\u00e4\u00e4...", "Your search did not match any documents. Please make sure that all words are spelled correctly and that you've selected enough categories.": "Ei l\u00f6ytynyt yht\u00e4\u00e4n. Tarkista hakuehdot, sanahaku, ei sen osia", "Search finished, found %s page(s) matching the search query.": "Etsint\u00e4 tehty, l\u00f6ydetty %s sivu(a).", ", in ": "", "Permalink to this headline": "", "Searching": "Etsit\u00e4\u00e4n", "Permalink to this definition": "", "Hide Search Matches": "Piilota l\u00f6ydetyt", "Search Results": "Etsinn\u00e4n tulos"}}); \ No newline at end of file diff --git a/sphinx/locale/fi/LC_MESSAGES/sphinx.mo b/sphinx/locale/fi/LC_MESSAGES/sphinx.mo new file mode 100644 index 000000000..3207b7389 Binary files /dev/null and b/sphinx/locale/fi/LC_MESSAGES/sphinx.mo differ diff --git a/sphinx/locale/fi/LC_MESSAGES/sphinx.po b/sphinx/locale/fi/LC_MESSAGES/sphinx.po new file mode 100644 index 000000000..7bbe636e9 --- /dev/null +++ b/sphinx/locale/fi/LC_MESSAGES/sphinx.po @@ -0,0 +1,600 @@ +# Finnish translations for Sphinx. +# Copyright (C) 2009 ORGANIZATION +# This file is distributed under the same license as the Sphinx project. +# FIRST AUTHOR <EMAIL@ADDRESS>, 2009. +# +msgid "" +msgstr "" +"Project-Id-Version: Sphinx 0.6\n" +"Report-Msgid-Bugs-To: sphinx@awot.fi\n" +"POT-Creation-Date: 2009-01-24 18:39+0000\n" +"PO-Revision-Date: 2009-02-11 11:21+0200\n" +"Last-Translator: Jukka Inkeri <sphinx@awot.fi>\n" +"Language-Team: fi <sphinx@awot.fi>\n" +"Plural-Forms: nplurals=2; plural=(n != 1)\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=utf-8\n" +"Content-Transfer-Encoding: 8bit\n" +"Generated-By: Babel 0.9.4\n" + +#: sphinx/environment.py:104 sphinx/writers/latex.py:170 +#, python-format +msgid "%B %d, %Y" +msgstr "%d.%m.%Y" + +#: sphinx/environment.py:300 sphinx/templates/genindex-single.html:2 +#: sphinx/templates/genindex-split.html:2 +#: sphinx/templates/genindex-split.html:5 sphinx/templates/genindex.html:2 +#: sphinx/templates/genindex.html:5 sphinx/templates/genindex.html:48 +#: sphinx/templates/layout.html:126 sphinx/writers/latex.py:176 +msgid "Index" +msgstr "Sisällysluettelo" + +#: sphinx/environment.py:301 sphinx/writers/latex.py:175 +msgid "Module Index" +msgstr "Moduuli sisällysluettelo" + +#: sphinx/environment.py:302 sphinx/templates/defindex.html:16 +msgid "Search Page" +msgstr "Etsi sivu" + +#: sphinx/roles.py:53 sphinx/directives/desc.py:580 +#, python-format +msgid "environment variable; %s" +msgstr "" + +#: sphinx/roles.py:60 +#, python-format +msgid "Python Enhancement Proposals!PEP %s" +msgstr "" + +#: sphinx/builders/changes.py:64 +msgid "Builtins" +msgstr "" + +#: sphinx/builders/changes.py:66 +msgid "Module level" +msgstr "Moduulitaso" + + +#: sphinx/builders/html.py:118 +#, python-format +msgid "%b %d, %Y" +msgstr "%d.%m.%Y" + +#: sphinx/builders/html.py:137 sphinx/templates/defindex.html:21 +msgid "General Index" +msgstr "Yleinen sisällysluettelo" + +#: sphinx/builders/html.py:137 +msgid "index" +msgstr "hakemisto" + +#: sphinx/builders/html.py:139 sphinx/builders/htmlhelp.py:182 +#: sphinx/builders/qthelp.py:131 sphinx/templates/defindex.html:19 +#: sphinx/templates/modindex.html:2 sphinx/templates/modindex.html:13 +msgid "Global Module Index" +msgstr "Yleinen moduulien sisällysluettelo" + +#: sphinx/builders/html.py:139 +msgid "modules" +msgstr "moduulit" +#msgstr "osat" + +#: sphinx/builders/html.py:179 +msgid "next" +msgstr ">" + +#: sphinx/builders/html.py:186 +msgid "previous" +msgstr "<" + +#: sphinx/builders/latex.py:155 sphinx/builders/pdf.py:162 +msgid " (in " +msgstr "" + +#: sphinx/directives/desc.py:25 +#, python-format +msgid "%s() (built-in function)" +msgstr "" + +#: sphinx/directives/desc.py:26 sphinx/directives/desc.py:42 +#: sphinx/directives/desc.py:54 +#, python-format +msgid "%s() (in module %s)" +msgstr "" + +#: sphinx/directives/desc.py:29 +#, python-format +msgid "%s (built-in variable)" +msgstr "" + +#: sphinx/directives/desc.py:30 sphinx/directives/desc.py:78 +#, python-format +msgid "%s (in module %s)" +msgstr "" + +#: sphinx/directives/desc.py:33 +#, python-format +msgid "%s (built-in class)" +msgstr "" + +#: sphinx/directives/desc.py:34 +#, python-format +msgid "%s (class in %s)" +msgstr "" + +#: sphinx/directives/desc.py:46 +#, python-format +msgid "%s() (%s.%s method)" +msgstr "" + +#: sphinx/directives/desc.py:48 +#, python-format +msgid "%s() (%s method)" +msgstr "" + +#: sphinx/directives/desc.py:58 +#, python-format +msgid "%s() (%s.%s static method)" +msgstr "" + +#: sphinx/directives/desc.py:60 +#, python-format +msgid "%s() (%s static method)" +msgstr "" + +#: sphinx/directives/desc.py:82 +#, python-format +msgid "%s (%s.%s attribute)" +msgstr "" + +#: sphinx/directives/desc.py:84 +#, python-format +msgid "%s (%s attribute)" +msgstr "" + +#: sphinx/directives/desc.py:86 +#, python-format +msgid "%s (C function)" +msgstr "" + +#: sphinx/directives/desc.py:88 +#, python-format +msgid "%s (C member)" +msgstr "" + +#: sphinx/directives/desc.py:90 +#, python-format +msgid "%s (C macro)" +msgstr "" + +#: sphinx/directives/desc.py:92 +#, python-format +msgid "%s (C type)" +msgstr "" + +#: sphinx/directives/desc.py:94 +#, python-format +msgid "%s (C variable)" +msgstr "" + +#: sphinx/directives/desc.py:112 +msgid "Raises" +msgstr "" + +#: sphinx/directives/desc.py:116 +msgid "Variable" +msgstr "" + +#: sphinx/directives/desc.py:119 +msgid "Returns" +msgstr "" + +#: sphinx/directives/desc.py:128 +msgid "Return type" +msgstr "" + +#: sphinx/directives/desc.py:213 +msgid "Parameter" +msgstr "" + +#: sphinx/directives/desc.py:217 +msgid "Parameters" +msgstr "" + +#: sphinx/directives/desc.py:465 +#, python-format +msgid "%scommand line option; %s" +msgstr "" + +#: sphinx/directives/other.py:101 +msgid "Platforms: " +msgstr "Ympäristö" + +#: sphinx/directives/other.py:106 +#, python-format +msgid "%s (module)" +msgstr "%s (moduuli)" + +#: sphinx/directives/other.py:146 +msgid "Section author: " +msgstr "Luvun kirjoittaja: " + +#: sphinx/directives/other.py:148 +msgid "Module author: " +msgstr "Moduulin kirjoittaja: " + +#: sphinx/directives/other.py:150 +msgid "Author: " +msgstr "Tekijä: " + +#: sphinx/directives/other.py:249 +msgid "See also" +msgstr "Katso myös" + +#: sphinx/ext/autodoc.py:442 +#, python-format +msgid " Bases: %s" +msgstr "" + +#: sphinx/ext/autodoc.py:566 sphinx/ext/autodoc.py:583 +#, python-format +msgid "alias of :class:`%s`" +msgstr "" + +#: sphinx/ext/todo.py:31 +msgid "Todo" +msgstr "Tehtävä vielä" + +#: sphinx/ext/todo.py:75 +#, python-format +msgid "(The original entry is located in %s, line %d and can be found " +msgstr "" + +#: sphinx/ext/todo.py:81 +msgid "here" +msgstr "tässä" + +#: sphinx/locale/__init__.py:15 +msgid "Attention" +msgstr "Huom" + +#: sphinx/locale/__init__.py:16 +msgid "Caution" +msgstr "Varoitus" + +#: sphinx/locale/__init__.py:17 +msgid "Danger" +msgstr "Vaara" + +#: sphinx/locale/__init__.py:18 +msgid "Error" +msgstr "Virhe" + +#: sphinx/locale/__init__.py:19 +msgid "Hint" +msgstr "Vihje" + +#: sphinx/locale/__init__.py:20 +msgid "Important" +msgstr "Tärkeä" + +#: sphinx/locale/__init__.py:21 +msgid "Note" +msgstr "Muista" + +#: sphinx/locale/__init__.py:22 +msgid "See Also" +msgstr "Katso myös" + +#: sphinx/locale/__init__.py:23 +msgid "Tip" +msgstr "Vihje" + +#: sphinx/locale/__init__.py:24 +msgid "Warning" +msgstr "Varoitus" + +#: sphinx/locale/__init__.py:28 +#, python-format +msgid "New in version %s" +msgstr "Uusi versiossa %s" + +#: sphinx/locale/__init__.py:29 +#, python-format +msgid "Changed in version %s" +msgstr "Muutettu versiossa %s" + +#: sphinx/locale/__init__.py:30 +#, python-format +msgid "Deprecated since version %s" +msgstr "Poistettu versiosta %s alkaen" + +#: sphinx/locale/__init__.py:34 +msgid "module" +msgstr "moduuli" +#msgstr "osa" + +#: sphinx/locale/__init__.py:35 +msgid "keyword" +msgstr "" +#msgstr "avainsana" + +#: sphinx/locale/__init__.py:36 +msgid "operator" +msgstr "" +#msgstr "operaattori" + + +#: sphinx/locale/__init__.py:37 +msgid "object" +msgstr "" +#msgstr "objekti" + +#: sphinx/locale/__init__.py:38 +msgid "exception" +msgstr "" +#msgstr "poikkeus" + +#: sphinx/locale/__init__.py:39 +msgid "statement" +msgstr "" + +#: sphinx/locale/__init__.py:40 +msgid "built-in function" +msgstr "" + +#: sphinx/static/doctools.js:139 sphinx/writers/html.py:425 +msgid "Permalink to this headline" +msgstr "" + +#: sphinx/static/doctools.js:145 sphinx/writers/html.py:80 +msgid "Permalink to this definition" +msgstr "" + +#: sphinx/static/doctools.js:174 +msgid "Hide Search Matches" +msgstr "Piilota löydetyt" + +#: sphinx/static/searchtools.js:274 +msgid "Searching" +msgstr "Etsitään" + +#: sphinx/static/searchtools.js:279 +msgid "Preparing search..." +msgstr "Valmistellaan etsintää..." + +#: sphinx/static/searchtools.js:338 +msgid "module, in " +msgstr "" + +#: sphinx/static/searchtools.js:347 +msgid ", in " +msgstr "" + +#: sphinx/static/searchtools.js:453 sphinx/templates/search.html:25 +msgid "Search Results" +msgstr "Etsinnän tulos" + +#: sphinx/static/searchtools.js:455 +msgid "" +"Your search did not match any documents. Please make sure that all words " +"are spelled correctly and that you've selected enough categories." +msgstr "Ei löytynyt yhtään. Tarkista hakuehdot, sanahaku, ei sen osia" + +#: sphinx/static/searchtools.js:457 +#, python-format +msgid "Search finished, found %s page(s) matching the search query." +msgstr "Etsintä tehty, löydetty %s sivu(a)." + +#: sphinx/templates/defindex.html:2 +msgid "Overview" +msgstr "Yhteenveto" + +#: sphinx/templates/defindex.html:11 +msgid "Indices and tables:" +msgstr "" + +#: sphinx/templates/defindex.html:14 +msgid "Complete Table of Contents" +msgstr "" + +#: sphinx/templates/defindex.html:15 +msgid "lists all sections and subsections" +msgstr "" + +#: sphinx/templates/defindex.html:17 +msgid "search this documentation" +msgstr "" + +#: sphinx/templates/defindex.html:20 +msgid "quick access to all modules" +msgstr "" + +#: sphinx/templates/defindex.html:22 +msgid "all functions, classes, terms" +msgstr "" + +#: sphinx/templates/genindex-single.html:5 +#, python-format +msgid "Index – %(key)s" +msgstr "" + +#: sphinx/templates/genindex-single.html:44 +#: sphinx/templates/genindex-split.html:14 +#: sphinx/templates/genindex-split.html:27 sphinx/templates/genindex.html:54 +msgid "Full index on one page" +msgstr "Hakemisto yhtenä luettelona" + +#: sphinx/templates/genindex-split.html:7 +msgid "Index pages by letter" +msgstr "Hakemisto aakkostus sivuttain" + +#: sphinx/templates/genindex-split.html:15 +msgid "can be huge" +msgstr "voi olla iso" + +#: sphinx/templates/layout.html:9 +msgid "Navigation" +msgstr "Navikointi" + +#: sphinx/templates/layout.html:40 +msgid "Table Of Contents" +msgstr "Sisällysluettelo" + +#: sphinx/templates/layout.html:46 +msgid "Previous topic" +msgstr "<<" + +#: sphinx/templates/layout.html:48 +msgid "previous chapter" +msgstr "<<" + +#: sphinx/templates/layout.html:51 +msgid "Next topic" +msgstr ">>" + +#: sphinx/templates/layout.html:53 +msgid "next chapter" +msgstr ">>" + +#: sphinx/templates/layout.html:58 +msgid "This Page" +msgstr "Tämä sivu" + +#: sphinx/templates/layout.html:61 +msgid "Show Source" +msgstr "Näytä lähdekoodina" + +#: sphinx/templates/layout.html:71 +msgid "Quick search" +msgstr "Pikahaku" + +#: sphinx/templates/layout.html:74 +msgid "Go" +msgstr "Siirry" + +#: sphinx/templates/layout.html:78 +msgid "Enter search terms or a module, class or function name." +msgstr "Anna etsittävä termi tai moduuli, luokka tai funktio" + +#: sphinx/templates/layout.html:115 +#, python-format +msgid "Search within %(docstitle)s" +msgstr "" + +#: sphinx/templates/layout.html:124 +msgid "About these documents" +msgstr "Tietoja tästä documentistä" + +#: sphinx/templates/layout.html:127 sphinx/templates/search.html:2 +#: sphinx/templates/search.html:5 +msgid "Search" +msgstr "Etsi" + +#: sphinx/templates/layout.html:129 +msgid "Copyright" +msgstr "" +#msgstr "(c)" + +#: sphinx/templates/layout.html:174 +#, python-format +msgid "© <a href=\"%(path)s\">Copyright</a> %(copyright)s." +msgstr "" +#msgstr "© <a href=\"%(path)s\">Copyright</a> %(copyright)s." +#msgstr "© <a href=\"%(path)s\">kaikki pidätetään</A> %(copyright)." + +#: sphinx/templates/layout.html:176 +#, python-format +msgid "© Copyright %(copyright)s." +msgstr "" +##msgstr "© Copyright %(copyright)s." +#msgstr "© %(copyright)." + +#: sphinx/templates/layout.html:179 +#, python-format +msgid "Last updated on %(last_updated)s." +msgstr "" +#msgstr "Viimeksi muutettu %(last_updated)." + +#: sphinx/templates/layout.html:182 +#, python-format +msgid "" +"Created using <a href=\"http://sphinx.pocoo.org/\">Sphinx</a> " +"%(sphinx_version)s." +msgstr """ +#msgstr "Tehty <a href=\"http://sphinx.pocoo.org/\">Sphinx</a> %(sphinx_version)" + +#: sphinx/templates/modindex.html:36 +msgid "Deprecated" +msgstr "Poistettu" + +#: sphinx/templates/opensearch.xml:4 +#, python-format +msgid "Search %(docstitle)s" +msgstr "" + +#: sphinx/templates/search.html:9 +msgid "" +"Please activate JavaScript to enable the search\n" +" functionality." +msgstr "Javascript pitää olla sallittu, jotta etsintä toimii." + +#: sphinx/templates/search.html:14 +msgid "" +"From here you can search these documents. Enter your search\n" +" words into the box below and click \"search\". Note that the search\n" +" function will automatically search for all of the words. Pages\n" +" containing fewer words won't appear in the result list." +msgstr "Anna hakusanat kokonaan, osasanoilla ei haeta." + +#: sphinx/templates/search.html:21 +msgid "search" +msgstr "etsi" + +#: sphinx/templates/search.html:27 +msgid "Your search did not match any results." +msgstr "Ei löytynyt ko. ehdoilla yhtään." + +#: sphinx/templates/changes/frameset.html:5 +#: sphinx/templates/changes/versionchanges.html:12 +#, python-format +msgid "Changes in Version %(version)s — %(docstitle)s" +msgstr "Muutos versiosta %(version) — %(docstitle)" + +#: sphinx/templates/changes/rstsource.html:5 +#, python-format +msgid "%(filename)s — %(docstitle)s" +msgstr "" + +#: sphinx/templates/changes/versionchanges.html:17 +#, python-format +msgid "Automatically generated list of changes in version %(version)s" +msgstr "Automaattisesti luotu muutoshistoria alkaen versiosta %(version)" + +#: sphinx/templates/changes/versionchanges.html:18 +msgid "Library changes" +msgstr "" + +#: sphinx/templates/changes/versionchanges.html:23 +msgid "C API changes" +msgstr "" + +#: sphinx/templates/changes/versionchanges.html:25 +msgid "Other changes" +msgstr "" + +#: sphinx/writers/latex.py:173 +msgid "Release" +msgstr "" + +#: sphinx/writers/text.py:166 +#, python-format +msgid "Ympäristö: %s" +msgstr "" + +#: sphinx/writers/text.py:427 +msgid "[image]" +msgstr "" + diff --git a/sphinx/locale/fr/LC_MESSAGES/sphinx.js b/sphinx/locale/fr/LC_MESSAGES/sphinx.js index 56debc4cd..ebe9e3514 100644 --- a/sphinx/locale/fr/LC_MESSAGES/sphinx.js +++ b/sphinx/locale/fr/LC_MESSAGES/sphinx.js @@ -1 +1 @@ -Documentation.addTranslations({"locale": "fr", "plural_expr": "(n > 1)", "messages": {"Search Results": "R\u00e9sultats de la recherche", "Your search did not match any documents. Please make sure that all words are spelled correctly and that you've selected enough categories.": "", "Getting search index...": "", "Permalink to this headline": "Lien permanent vers ce titre", "Searching": "rechercher", "Permalink to this definition": "Lien permanent vers cette d\u00e9finition", "Hide Search Matches": "", "Search finished, found %s page(s) matching the search query.": ""}}); \ No newline at end of file +Documentation.addTranslations({"locale": "fr", "plural_expr": "(n > 1)", "messages": {"module, in ": "module, dans", "Preparing search...": "Pr\u00e9paration de la recherche...", "Your search did not match any documents. Please make sure that all words are spelled correctly and that you've selected enough categories.": "Votre recherche ne correspond \u00e0 aucun document. V\u00e9rifiez l'orthographe des termes de recherche et que vous avez s\u00e9lectionn\u00e9 suffisamment de cat\u00e9gories.", "Search finished, found %s page(s) matching the search query.": "La recherche est termin\u00e9e, %s page(s) correspond(ent) \u00e0 la requ\u00eate.", ", in ": ", dans", "Permalink to this headline": "Lien permanent vers ce titre", "Searching": "En cours de recherche", "Permalink to this definition": "Lien permanent vers cette d\u00e9finition", "Hide Search Matches": "Cacher les r\u00e9sultats de la recherche", "Search Results": "R\u00e9sultats de la recherche"}}); \ No newline at end of file diff --git a/sphinx/locale/fr/LC_MESSAGES/sphinx.mo b/sphinx/locale/fr/LC_MESSAGES/sphinx.mo index 94de5c620..c7b2474d8 100644 Binary files a/sphinx/locale/fr/LC_MESSAGES/sphinx.mo and b/sphinx/locale/fr/LC_MESSAGES/sphinx.mo differ diff --git a/sphinx/locale/fr/LC_MESSAGES/sphinx.po b/sphinx/locale/fr/LC_MESSAGES/sphinx.po index 72b5608d2..bd6ea6ec2 100644 --- a/sphinx/locale/fr/LC_MESSAGES/sphinx.po +++ b/sphinx/locale/fr/LC_MESSAGES/sphinx.po @@ -2,240 +2,260 @@ # Copyright (C) 2008 ORGANIZATION # This file is distributed under the same license as the Sphinx project. # David Larlet <larlet@gmail.com>, 2008. +# Sebastien Douche <sdouche@gmail.com>, 2008. # msgid "" msgstr "" "Project-Id-Version: Sphinx 0.5\n" "Report-Msgid-Bugs-To: larlet@gmail.com\n" "POT-Creation-Date: 2008-08-08 12:39+0000\n" -"PO-Revision-Date: 2008-09-06 19:10+0200\n" -"Last-Translator: David Larlet <larlet@gmail.com>\n" -"Language-Team: fr <LL@li.org>\n" +"PO-Revision-Date: 2009-01-24 18:39+0000\n" +"Last-Translator: Sébastien Douche <sdouche@gmail.com>\n" +"Language-Team: French Translation Team <sphinx-dev@googlegroups.com>\n" "Plural-Forms: nplurals=2; plural=(n > 1)\n" "MIME-Version: 1.0\n" "Content-Type: text/plain; charset=utf-8\n" "Content-Transfer-Encoding: 8bit\n" "Generated-By: Babel 0.9.3\n" -#: sphinx/builder.py:391 -#, python-format -msgid "%b %d, %Y" -msgstr "%d %b %Y" - -#: sphinx/builder.py:410 sphinx/templates/defindex.html:21 -msgid "General Index" -msgstr "Index général" - -#: sphinx/builder.py:410 -msgid "index" -msgstr "index" - -#: sphinx/builder.py:412 sphinx/htmlhelp.py:155 -#: sphinx/templates/defindex.html:19 sphinx/templates/modindex.html:2 -#: sphinx/templates/modindex.html:13 -msgid "Global Module Index" -msgstr "Index général des modules" - -#: sphinx/builder.py:412 -msgid "modules" -msgstr "modules" - -#: sphinx/builder.py:448 -msgid "next" -msgstr "suivant" - -#: sphinx/builder.py:455 -msgid "previous" -msgstr "précédent" - -#: sphinx/builder.py:1092 -msgid "Builtins" -msgstr "Fonctions de base" - -#: sphinx/builder.py:1094 -#, fuzzy -msgid "Module level" -msgstr "Modules" - -#: sphinx/environment.py:108 sphinx/latexwriter.py:129 +#: sphinx/environment.py:104 sphinx/writers/latex.py:170 #, python-format msgid "%B %d, %Y" msgstr "%d %B %Y" -#: sphinx/htmlwriter.py:73 sphinx/static/doctools.js:143 -msgid "Permalink to this definition" -msgstr "Lien permanent vers cette définition" - -#: sphinx/htmlwriter.py:379 sphinx/static/doctools.js:136 -msgid "Permalink to this headline" -msgstr "Lien permanent vers ce titre" - -#: sphinx/latexwriter.py:143 -msgid "Release" -msgstr "Release" - -#: sphinx/latexwriter.py:188 -#, fuzzy -msgid "Module index" -msgstr "Index général des modules" - -#: sphinx/latexwriter.py:190 sphinx/templates/genindex-single.html:2 +#: sphinx/environment.py:300 sphinx/templates/genindex-single.html:2 #: sphinx/templates/genindex-split.html:2 #: sphinx/templates/genindex-split.html:5 sphinx/templates/genindex.html:2 #: sphinx/templates/genindex.html:5 sphinx/templates/genindex.html:48 +#: sphinx/templates/layout.html:126 sphinx/writers/latex.py:176 msgid "Index" msgstr "Index" -#: sphinx/roles.py:52 sphinx/directives/desc.py:514 +#: sphinx/environment.py:301 sphinx/writers/latex.py:175 +msgid "Module Index" +msgstr "Index du module" + +#: sphinx/environment.py:302 sphinx/templates/defindex.html:16 +msgid "Search Page" +msgstr "Page de recherche" + +#: sphinx/roles.py:53 sphinx/directives/desc.py:580 #, python-format msgid "environment variable; %s" msgstr "variable d'environnement; %s" -#: sphinx/roles.py:59 +#: sphinx/roles.py:60 #, python-format msgid "Python Enhancement Proposals!PEP %s" msgstr "Python Enhancement Proposals!PEP %s" -#: sphinx/textwriter.py:151 +#: sphinx/builders/changes.py:64 +msgid "Builtins" +msgstr "Fonctions de base" + +#: sphinx/builders/changes.py:66 +msgid "Module level" +msgstr "Module" + +#: sphinx/builders/html.py:118 #, python-format -msgid "Platform: %s" -msgstr "Plateforme: %s" +msgid "%b %d, %Y" +msgstr "%d %b %Y" -#: sphinx/textwriter.py:353 -msgid "[image]" -msgstr "[image]" +#: sphinx/builders/html.py:137 sphinx/templates/defindex.html:21 +msgid "General Index" +msgstr "Index général" -#: sphinx/directives/desc.py:26 +#: sphinx/builders/html.py:137 +msgid "index" +msgstr "index" + +#: sphinx/builders/html.py:139 sphinx/builders/htmlhelp.py:182 +#: sphinx/builders/qthelp.py:131 sphinx/templates/defindex.html:19 +#: sphinx/templates/modindex.html:2 sphinx/templates/modindex.html:13 +msgid "Global Module Index" +msgstr "Index général des modules" + +#: sphinx/builders/html.py:139 +msgid "modules" +msgstr "modules" + +#: sphinx/builders/html.py:179 +msgid "next" +msgstr "suivant" + +#: sphinx/builders/html.py:186 +msgid "previous" +msgstr "précédent" + +#: sphinx/builders/latex.py:155 sphinx/builders/pdf.py:162 +msgid " (in " +msgstr "(dans" + +#: sphinx/directives/desc.py:25 #, python-format msgid "%s() (built-in function)" msgstr "%s() (fonction de base)" -#: sphinx/directives/desc.py:27 sphinx/directives/desc.py:41 -#: sphinx/directives/desc.py:53 +#: sphinx/directives/desc.py:26 sphinx/directives/desc.py:42 +#: sphinx/directives/desc.py:54 #, python-format msgid "%s() (in module %s)" msgstr "%s() (dans le module %s)" -#: sphinx/directives/desc.py:30 +#: sphinx/directives/desc.py:29 #, python-format msgid "%s (built-in variable)" msgstr "%s (variable de base)" -#: sphinx/directives/desc.py:31 sphinx/directives/desc.py:65 +#: sphinx/directives/desc.py:30 sphinx/directives/desc.py:78 #, python-format msgid "%s (in module %s)" msgstr "%s (dans le module %s)" #: sphinx/directives/desc.py:33 #, python-format +msgid "%s (built-in class)" +msgstr "%s (classe de base)" + +#: sphinx/directives/desc.py:34 +#, python-format msgid "%s (class in %s)" msgstr "%s (classe dans %s)" -#: sphinx/directives/desc.py:45 +#: sphinx/directives/desc.py:46 #, python-format msgid "%s() (%s.%s method)" msgstr "%s() (méthode %s.%s)" -#: sphinx/directives/desc.py:47 +#: sphinx/directives/desc.py:48 #, python-format msgid "%s() (%s method)" msgstr "%s() (méthode %s)" -#: sphinx/directives/desc.py:57 +#: sphinx/directives/desc.py:58 #, python-format msgid "%s() (%s.%s static method)" msgstr "%s() (méthode statique %s.%s)" -#: sphinx/directives/desc.py:59 +#: sphinx/directives/desc.py:60 #, python-format msgid "%s() (%s static method)" msgstr "%s() (méthode statique %s)" -#: sphinx/directives/desc.py:69 +#: sphinx/directives/desc.py:82 #, python-format msgid "%s (%s.%s attribute)" msgstr "%s (attribut %s.%s)" -#: sphinx/directives/desc.py:71 +#: sphinx/directives/desc.py:84 #, python-format msgid "%s (%s attribute)" msgstr "%s (attribut %s)" -#: sphinx/directives/desc.py:73 +#: sphinx/directives/desc.py:86 #, python-format msgid "%s (C function)" msgstr "%s (fonction C)" -#: sphinx/directives/desc.py:75 +#: sphinx/directives/desc.py:88 #, python-format msgid "%s (C member)" msgstr "%s (membre C)" -#: sphinx/directives/desc.py:77 +#: sphinx/directives/desc.py:90 #, python-format msgid "%s (C macro)" msgstr "%s (macro C)" -#: sphinx/directives/desc.py:79 +#: sphinx/directives/desc.py:92 #, python-format msgid "%s (C type)" msgstr "%s (type C)" -#: sphinx/directives/desc.py:81 +#: sphinx/directives/desc.py:94 #, python-format msgid "%s (C variable)" msgstr "%s (variable C)" -#: sphinx/directives/desc.py:99 +#: sphinx/directives/desc.py:112 msgid "Raises" msgstr "Lève" -#: sphinx/directives/desc.py:103 +#: sphinx/directives/desc.py:116 msgid "Variable" msgstr "Variable" -#: sphinx/directives/desc.py:106 +#: sphinx/directives/desc.py:119 msgid "Returns" msgstr "Retourne" -#: sphinx/directives/desc.py:113 +#: sphinx/directives/desc.py:128 msgid "Return type" msgstr "Type retourné" -#: sphinx/directives/desc.py:140 +#: sphinx/directives/desc.py:213 +#, fuzzy +msgid "Parameter" +msgstr "Paramètres" + +#: sphinx/directives/desc.py:217 msgid "Parameters" msgstr "Paramètres" -#: sphinx/directives/desc.py:402 +#: sphinx/directives/desc.py:465 #, python-format -msgid "command line option; %s" -msgstr "option de ligne de commande; %s" +msgid "%scommand line option; %s" +msgstr "%soption de ligne de commande; %s" -#: sphinx/directives/other.py:102 +#: sphinx/directives/other.py:101 msgid "Platforms: " msgstr "Plateformes : " -#: sphinx/directives/other.py:107 -#, fuzzy, python-format +#: sphinx/directives/other.py:106 +#, python-format msgid "%s (module)" msgstr "%s (module)" -#: sphinx/directives/other.py:147 +#: sphinx/directives/other.py:146 msgid "Section author: " msgstr "Auteur de la section : " -#: sphinx/directives/other.py:149 +#: sphinx/directives/other.py:148 msgid "Module author: " msgstr "Auteur du module : " -#: sphinx/directives/other.py:151 +#: sphinx/directives/other.py:150 msgid "Author: " msgstr "Auteur : " -#: sphinx/directives/other.py:233 +#: sphinx/directives/other.py:249 msgid "See also" msgstr "Voir aussi" +#: sphinx/ext/autodoc.py:442 +#, python-format +msgid " Bases: %s" +msgstr "" + +#: sphinx/ext/autodoc.py:566 sphinx/ext/autodoc.py:583 +#, python-format +msgid "alias of :class:`%s`" +msgstr "" + +#: sphinx/ext/todo.py:31 +msgid "Todo" +msgstr "A faire" + +#: sphinx/ext/todo.py:75 +#, python-format +msgid "(The original entry is located in %s, line %d and can be found " +msgstr "(L'entrée orginale se trouve dans %s, à la ligne %d et peut être trouvé" + +#: sphinx/ext/todo.py:81 +msgid "here" +msgstr "ici" + #: sphinx/locale/__init__.py:15 msgid "Attention" msgstr "Attention" @@ -319,33 +339,51 @@ msgstr "état" msgid "built-in function" msgstr "fonction de base" -#: sphinx/static/doctools.js:172 +#: sphinx/static/doctools.js:139 sphinx/writers/html.py:425 +msgid "Permalink to this headline" +msgstr "Lien permanent vers ce titre" + +#: sphinx/static/doctools.js:145 sphinx/writers/html.py:80 +msgid "Permalink to this definition" +msgstr "Lien permanent vers cette définition" + +#: sphinx/static/doctools.js:174 msgid "Hide Search Matches" -msgstr "" +msgstr "Cacher les résultats de la recherche" -#: sphinx/static/searchtools.js:242 -#, fuzzy +#: sphinx/static/searchtools.js:274 msgid "Searching" -msgstr "rechercher" +msgstr "En cours de recherche" -#: sphinx/static/searchtools.js:246 -msgid "Getting search index..." -msgstr "" +#: sphinx/static/searchtools.js:279 +msgid "Preparing search..." +msgstr "Préparation de la recherche..." -#: sphinx/static/searchtools.js:384 sphinx/templates/search.html:18 +#: sphinx/static/searchtools.js:338 +msgid "module, in " +msgstr "module, dans" + +#: sphinx/static/searchtools.js:347 +msgid ", in " +msgstr ", dans" + +#: sphinx/static/searchtools.js:453 sphinx/templates/search.html:25 msgid "Search Results" msgstr "Résultats de la recherche" -#: sphinx/static/searchtools.js:386 +#: sphinx/static/searchtools.js:455 msgid "" "Your search did not match any documents. Please make sure that all words " "are spelled correctly and that you've selected enough categories." msgstr "" +"Votre recherche ne correspond à aucun document. Vérifiez l'orthographe " +"des termes de recherche et que vous avez sélectionné suffisamment de " +"catégories." -#: sphinx/static/searchtools.js:389 +#: sphinx/static/searchtools.js:457 #, python-format msgid "Search finished, found %s page(s) matching the search query." -msgstr "" +msgstr "La recherche est terminée, %s page(s) correspond(ent) à la requête." #: sphinx/templates/defindex.html:2 msgid "Overview" @@ -363,10 +401,6 @@ msgstr "Table des matières complète" msgid "lists all sections and subsections" msgstr "lister l'ensemble des sections et sous-sections" -#: sphinx/templates/defindex.html:16 -msgid "Search page" -msgstr "Page de recherche" - #: sphinx/templates/defindex.html:17 msgid "search this documentation" msgstr "rechercher dans cette documentation" @@ -410,27 +444,23 @@ msgstr "Table des matières" msgid "Previous topic" msgstr "Sujet précédent" -#: sphinx/templates/layout.html:47 +#: sphinx/templates/layout.html:48 msgid "previous chapter" msgstr "Chapitre précédent" -#: sphinx/templates/layout.html:50 +#: sphinx/templates/layout.html:51 msgid "Next topic" msgstr "Sujet suivant" -#: sphinx/templates/layout.html:51 +#: sphinx/templates/layout.html:53 msgid "next chapter" msgstr "Chapitre suivant" -#: sphinx/templates/layout.html:55 +#: sphinx/templates/layout.html:58 msgid "This Page" msgstr "Cette page" -#: sphinx/templates/layout.html:59 -msgid "Suggest Change" -msgstr "Suggérer une modification" - -#: sphinx/templates/layout.html:60 sphinx/templates/layout.html:62 +#: sphinx/templates/layout.html:61 msgid "Show Source" msgstr "Montrer la source" @@ -438,60 +468,49 @@ msgstr "Montrer la source" msgid "Quick search" msgstr "Recherche rapide" -#: sphinx/templates/layout.html:71 -msgid "Keyword search" -msgstr "Recherche par mot-clé" - -#: sphinx/templates/layout.html:73 +#: sphinx/templates/layout.html:74 msgid "Go" msgstr "Go" #: sphinx/templates/layout.html:78 -msgid "Enter a module, class or function name." +#, fuzzy +msgid "Enter search terms or a module, class or function name." msgstr "Saisissez un nom de module, classe ou fonction." -#: sphinx/templates/layout.html:118 +#: sphinx/templates/layout.html:115 #, python-format msgid "Search within %(docstitle)s" msgstr "Recherchez dans %(docstitle)s" -#: sphinx/templates/layout.html:127 +#: sphinx/templates/layout.html:124 msgid "About these documents" msgstr "À propos de ces documents" -#: sphinx/templates/layout.html:129 -msgid "Global table of contents" -msgstr "Table des matières générale" - -#: sphinx/templates/layout.html:130 -msgid "Global index" -msgstr "Index général" - -#: sphinx/templates/layout.html:131 sphinx/templates/search.html:2 +#: sphinx/templates/layout.html:127 sphinx/templates/search.html:2 #: sphinx/templates/search.html:5 msgid "Search" msgstr "Recherche" -#: sphinx/templates/layout.html:133 +#: sphinx/templates/layout.html:129 msgid "Copyright" msgstr "Copyright" -#: sphinx/templates/layout.html:178 +#: sphinx/templates/layout.html:174 #, python-format msgid "© <a href=\"%(path)s\">Copyright</a> %(copyright)s." msgstr "© <a href=\"%(path)s\">Copyright</a> %(copyright)s." -#: sphinx/templates/layout.html:180 +#: sphinx/templates/layout.html:176 #, python-format msgid "© Copyright %(copyright)s." msgstr "© Copyright %(copyright)s." -#: sphinx/templates/layout.html:183 +#: sphinx/templates/layout.html:179 #, python-format msgid "Last updated on %(last_updated)s." msgstr "Mis à jour le %(last_updated)s." -#: sphinx/templates/layout.html:186 +#: sphinx/templates/layout.html:182 #, python-format msgid "" "Created using <a href=\"http://sphinx.pocoo.org/\">Sphinx</a> " @@ -500,15 +519,7 @@ msgstr "" "Créé avec <a href=\"http://sphinx.pocoo.org/\">Sphinx</a> " "%(sphinx_version)s." -#: sphinx/templates/modindex.html:15 -msgid "Most popular modules:" -msgstr "Modules les plus utilisés :" - -#: sphinx/templates/modindex.html:24 -msgid "Show modules only available on these platforms" -msgstr "N'afficher que les modules disponibles sur ces plateformes" - -#: sphinx/templates/modindex.html:56 +#: sphinx/templates/modindex.html:36 msgid "Deprecated" msgstr "Obsolète" @@ -517,22 +528,19 @@ msgstr "Obsolète" msgid "Search %(docstitle)s" msgstr "Rechercher %(docstitle)s" -#: sphinx/templates/page.html:8 +#: sphinx/templates/search.html:9 msgid "" -"<strong>Note:</strong> You requested an out-of-date URL from this server." -" We've tried to redirect you to the new location of this page, but it may" -" not be the right one." +"Please activate JavaScript to enable the search\n" +" functionality." msgstr "" -"<strong>Note :</strong> Vous tentez d'accéder à une ancienne URL de ce " -"serveur. Nous avons essayé de vous rediriger vers la nouvelle adresse de " -"cette page, mais ce n'est peut-être pas la bonne." -#: sphinx/templates/search.html:7 +#: sphinx/templates/search.html:14 +#, fuzzy msgid "" "From here you can search these documents. Enter your search\n" " words into the box below and click \"search\". Note that the search\n" " function will automatically search for all of the words. Pages\n" -" containing less words won't appear in the result list." +" containing fewer words won't appear in the result list." msgstr "" "Vous pouvez effectuer une recherche au sein des documents. Saisissez les " "termes\n" @@ -542,11 +550,11 @@ msgstr "" " contenant moins de mots n'apparaîtront pas dans la liste des " "résultats." -#: sphinx/templates/search.html:14 +#: sphinx/templates/search.html:21 msgid "search" msgstr "rechercher" -#: sphinx/templates/search.html:20 +#: sphinx/templates/search.html:27 msgid "Your search did not match any results." msgstr "Votre recherche n'a retourné aucun résultat" @@ -578,3 +586,16 @@ msgstr "Modifications de l'API C" msgid "Other changes" msgstr "Autres modifications" +#: sphinx/writers/latex.py:173 +msgid "Release" +msgstr "Version" + +#: sphinx/writers/text.py:166 +#, python-format +msgid "Platform: %s" +msgstr "Plateforme : %s" + +#: sphinx/writers/text.py:427 +msgid "[image]" +msgstr "[image]" + diff --git a/sphinx/locale/it/LC_MESSAGES/sphinx.js b/sphinx/locale/it/LC_MESSAGES/sphinx.js new file mode 100644 index 000000000..91a939a6d --- /dev/null +++ b/sphinx/locale/it/LC_MESSAGES/sphinx.js @@ -0,0 +1 @@ +Documentation.addTranslations({"locale": "it", "plural_expr": "(n != 1)", "messages": {"module, in ": "modulo, in", "Preparing search...": "Preparazione della ricerca", "Your search did not match any documents. Please make sure that all words are spelled correctly and that you've selected enough categories.": "La tua ricerca non ha trovato alcun risultato. Controlla la correttezza dei termini di ricerca e di avere selezionato un numero sufficiente di categorie", "Search finished, found %s page(s) matching the search query.": "Ricerca terminata, trovate %s pagine corrispondenti alla ricerca.", ", in ": ", in ", "Permalink to this headline": "link permanente per questa intestazione", "Searching": "Ricerca in corso", "Permalink to this definition": "link permanente per questa definizione", "Hide Search Matches": "Nascondi i risultati della ricerca", "Search Results": "Risultati della ricerca"}}); \ No newline at end of file diff --git a/sphinx/locale/it/LC_MESSAGES/sphinx.mo b/sphinx/locale/it/LC_MESSAGES/sphinx.mo new file mode 100644 index 000000000..4f95d152b Binary files /dev/null and b/sphinx/locale/it/LC_MESSAGES/sphinx.mo differ diff --git a/sphinx/locale/it/LC_MESSAGES/sphinx.po b/sphinx/locale/it/LC_MESSAGES/sphinx.po new file mode 100644 index 000000000..c6db18306 --- /dev/null +++ b/sphinx/locale/it/LC_MESSAGES/sphinx.po @@ -0,0 +1,595 @@ +# Italian translations for Sphinx. +# Copyright (C) 2008 ORGANIZATION +# This file is distributed under the same license as the Sphinx project. +# Sandro Dentella <sandro@e-den.it>, 2008. +msgid "" +msgstr "" +"Project-Id-Version: Sphinx 0.5\n" +"Report-Msgid-Bugs-To: EMAIL@ADDRESS\n" +"POT-Creation-Date: 2008-11-27 18:39+0100\n" +"PO-Revision-Date: 2009-01-24 18:39+0000\n" +"Last-Translator: Sandro Dentella <sandro@e-den.it>\n" +"Language-Team: <sphinx-dev@googlegroups.com>\n" +"Plural-Forms: nplurals=2; plural=(n != 1)\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=utf-8\n" +"Content-Transfer-Encoding: 8bit\n" +"Generated-By: Babel 0.9.3\n" + +#: sphinx/environment.py:104 sphinx/writers/latex.py:170 +#, python-format +msgid "%B %d, %Y" +msgstr "%d %B %Y" + +#: sphinx/environment.py:300 sphinx/templates/genindex-single.html:2 +#: sphinx/templates/genindex-split.html:2 +#: sphinx/templates/genindex-split.html:5 sphinx/templates/genindex.html:2 +#: sphinx/templates/genindex.html:5 sphinx/templates/genindex.html:48 +#: sphinx/templates/layout.html:126 sphinx/writers/latex.py:176 +msgid "Index" +msgstr "Indice" + +#: sphinx/environment.py:301 sphinx/writers/latex.py:175 +msgid "Module Index" +msgstr "Indice dei Moduli" + +#: sphinx/environment.py:302 sphinx/templates/defindex.html:16 +msgid "Search Page" +msgstr "Cerca" + +#: sphinx/roles.py:53 sphinx/directives/desc.py:580 +#, python-format +msgid "environment variable; %s" +msgstr "variabile d'ambiente, %s" + +#: sphinx/roles.py:60 +#, python-format +msgid "Python Enhancement Proposals!PEP %s" +msgstr "Python Enhancement Proposals!PEP %s" + +#: sphinx/builders/changes.py:64 +msgid "Builtins" +msgstr "Builtin" + +#: sphinx/builders/changes.py:66 +msgid "Module level" +msgstr "Modulo" + +#: sphinx/builders/html.py:118 +#, python-format +msgid "%b %d, %Y" +msgstr "%d/%b/%Y" + +#: sphinx/builders/html.py:137 sphinx/templates/defindex.html:21 +msgid "General Index" +msgstr "Indice generale" + +#: sphinx/builders/html.py:137 +msgid "index" +msgstr "indice" + +#: sphinx/builders/html.py:139 sphinx/builders/htmlhelp.py:182 +#: sphinx/builders/qthelp.py:131 sphinx/templates/defindex.html:19 +#: sphinx/templates/modindex.html:2 sphinx/templates/modindex.html:13 +msgid "Global Module Index" +msgstr "Indice dei moduli" + +#: sphinx/builders/html.py:139 +msgid "modules" +msgstr "moduli" + +#: sphinx/builders/html.py:179 +msgid "next" +msgstr "successivo" + +#: sphinx/builders/html.py:186 +msgid "previous" +msgstr "precedente" + +#: sphinx/builders/latex.py:155 sphinx/builders/pdf.py:162 +msgid " (in " +msgstr " (in " + +#: sphinx/directives/desc.py:25 +#, python-format +msgid "%s() (built-in function)" +msgstr "%s() (funzione built-in)" + +#: sphinx/directives/desc.py:26 sphinx/directives/desc.py:42 +#: sphinx/directives/desc.py:54 +#, python-format +msgid "%s() (in module %s)" +msgstr "%s() (nel modulo %s)" + +#: sphinx/directives/desc.py:29 +#, python-format +msgid "%s (built-in variable)" +msgstr "%s (variabile built-in)" + +#: sphinx/directives/desc.py:30 sphinx/directives/desc.py:78 +#, python-format +msgid "%s (in module %s)" +msgstr "%s (nel modulo %s)" + +#: sphinx/directives/desc.py:33 +#, python-format +msgid "%s (built-in class)" +msgstr "%s (classe built-in)" + +#: sphinx/directives/desc.py:34 +#, python-format +msgid "%s (class in %s)" +msgstr "%s (classe in %s)" + +#: sphinx/directives/desc.py:46 +#, python-format +msgid "%s() (%s.%s method)" +msgstr "%s() (%s.%s metodo)" + +#: sphinx/directives/desc.py:48 +#, python-format +msgid "%s() (%s method)" +msgstr "%s() (%s metodo)" + +#: sphinx/directives/desc.py:58 +#, python-format +msgid "%s() (%s.%s static method)" +msgstr "%s() (%s.%s metodo statico)" + +#: sphinx/directives/desc.py:60 +#, python-format +msgid "%s() (%s static method)" +msgstr "%s() (%s metodo statico)" + +#: sphinx/directives/desc.py:82 +#, python-format +msgid "%s (%s.%s attribute)" +msgstr "%s (%s.%s attributo)" + +#: sphinx/directives/desc.py:84 +#, python-format +msgid "%s (%s attribute)" +msgstr "%s (%s attributo)" + +#: sphinx/directives/desc.py:86 +#, python-format +msgid "%s (C function)" +msgstr "%s (funzione C)" + +#: sphinx/directives/desc.py:88 +#, python-format +msgid "%s (C member)" +msgstr "%s (membro C )" + +#: sphinx/directives/desc.py:90 +#, python-format +msgid "%s (C macro)" +msgstr "%s (macro C)" + +#: sphinx/directives/desc.py:92 +#, python-format +msgid "%s (C type)" +msgstr "%s (tipo C)" + +#: sphinx/directives/desc.py:94 +#, python-format +msgid "%s (C variable)" +msgstr "%s (variabile C)" + +#: sphinx/directives/desc.py:112 +msgid "Raises" +msgstr "Solleva" + +#: sphinx/directives/desc.py:116 +msgid "Variable" +msgstr "Variabile" + +#: sphinx/directives/desc.py:119 +msgid "Returns" +msgstr "Ritorna" + +#: sphinx/directives/desc.py:128 +msgid "Return type" +msgstr "Tipo di ritorno" + +#: sphinx/directives/desc.py:213 +msgid "Parameter" +msgstr "Parametri" + +#: sphinx/directives/desc.py:217 +msgid "Parameters" +msgstr "Parametri" + +#: sphinx/directives/desc.py:465 +#, python-format +msgid "%scommand line option; %s" +msgstr "%sopzione di linea di comando; %s" + +#: sphinx/directives/other.py:101 +msgid "Platforms: " +msgstr "Piattaforme:" + +#: sphinx/directives/other.py:106 +#, python-format +msgid "%s (module)" +msgstr "%s (modulo)" + +#: sphinx/directives/other.py:146 +msgid "Section author: " +msgstr "Autore della sezione" + +#: sphinx/directives/other.py:148 +msgid "Module author: " +msgstr "Autore del modulo" + +#: sphinx/directives/other.py:150 +msgid "Author: " +msgstr "Autore: " + +#: sphinx/directives/other.py:249 +msgid "See also" +msgstr "Vedi anche" + +#: sphinx/ext/autodoc.py:442 +#, python-format +msgid " Bases: %s" +msgstr "" + +#: sphinx/ext/autodoc.py:566 sphinx/ext/autodoc.py:583 +#, python-format +msgid "alias of :class:`%s`" +msgstr "alias per :class:`%s`" + +#: sphinx/ext/todo.py:31 +msgid "Todo" +msgstr "Da fare" + +#: sphinx/ext/todo.py:75 +#, python-format +msgid "(The original entry is located in %s, line %d and can be found " +msgstr "(La riga originale si trova in %s, linea %d e può essere trovata " + +#: sphinx/ext/todo.py:81 +msgid "here" +msgstr "qui" + +#: sphinx/locale/__init__.py:15 +msgid "Attention" +msgstr "Attenzione" + +#: sphinx/locale/__init__.py:16 +msgid "Caution" +msgstr "Attenzione" + +#: sphinx/locale/__init__.py:17 +msgid "Danger" +msgstr "Pericolo" + +#: sphinx/locale/__init__.py:18 +msgid "Error" +msgstr "Errore" + +#: sphinx/locale/__init__.py:19 +msgid "Hint" +msgstr "Consiglio" + +#: sphinx/locale/__init__.py:20 +msgid "Important" +msgstr "Importante" + +#: sphinx/locale/__init__.py:21 +msgid "Note" +msgstr "Nota" + +#: sphinx/locale/__init__.py:22 +msgid "See Also" +msgstr "Vedi anche" + +#: sphinx/locale/__init__.py:23 +msgid "Tip" +msgstr "Suggerimento" + +#: sphinx/locale/__init__.py:24 +msgid "Warning" +msgstr "Avvertimento" + +#: sphinx/locale/__init__.py:28 +#, python-format +msgid "New in version %s" +msgstr "Nuovo nella versione %s" + +#: sphinx/locale/__init__.py:29 +#, python-format +msgid "Changed in version %s" +msgstr "Cambiato nella versione %s" + +#: sphinx/locale/__init__.py:30 +#, python-format +msgid "Deprecated since version %s" +msgstr "Deprecato dalla versione %s" + +#: sphinx/locale/__init__.py:34 +msgid "module" +msgstr "modulo" + +#: sphinx/locale/__init__.py:35 +msgid "keyword" +msgstr "keyword" + +#: sphinx/locale/__init__.py:36 +msgid "operator" +msgstr "operatore" + +#: sphinx/locale/__init__.py:37 +msgid "object" +msgstr "oggetto" + +#: sphinx/locale/__init__.py:38 +msgid "exception" +msgstr "eccezione" + +#: sphinx/locale/__init__.py:39 +msgid "statement" +msgstr "statement" + +#: sphinx/locale/__init__.py:40 +msgid "built-in function" +msgstr "funzione built-in" + +#: sphinx/static/doctools.js:139 sphinx/writers/html.py:425 +msgid "Permalink to this headline" +msgstr "link permanente per questa intestazione" + +#: sphinx/static/doctools.js:145 sphinx/writers/html.py:80 +msgid "Permalink to this definition" +msgstr "link permanente per questa definizione" + +#: sphinx/static/doctools.js:174 +msgid "Hide Search Matches" +msgstr "Nascondi i risultati della ricerca" + +#: sphinx/static/searchtools.js:274 +msgid "Searching" +msgstr "Ricerca in corso" + +#: sphinx/static/searchtools.js:279 +msgid "Preparing search..." +msgstr "Preparazione della ricerca" + +#: sphinx/static/searchtools.js:338 +msgid "module, in " +msgstr "modulo, in" + +#: sphinx/static/searchtools.js:347 +msgid ", in " +msgstr ", in " + +#: sphinx/static/searchtools.js:453 sphinx/templates/search.html:25 +msgid "Search Results" +msgstr "Risultati della ricerca" + +#: sphinx/static/searchtools.js:455 +msgid "" +"Your search did not match any documents. Please make sure that all words " +"are spelled correctly and that you've selected enough categories." +msgstr "" +"La tua ricerca non ha trovato alcun risultato. Controlla la correttezza " +"dei termini di ricerca e di avere selezionato un numero sufficiente di " +"categorie" + +#: sphinx/static/searchtools.js:457 +#, python-format +msgid "Search finished, found %s page(s) matching the search query." +msgstr "Ricerca terminata, trovate %s pagine corrispondenti alla ricerca." + +#: sphinx/templates/defindex.html:2 +msgid "Overview" +msgstr "Sintesi" + +#: sphinx/templates/defindex.html:11 +msgid "Indices and tables:" +msgstr "Indici e tabelle:" + +#: sphinx/templates/defindex.html:14 +msgid "Complete Table of Contents" +msgstr "Tabella dei contenuti completa" + +#: sphinx/templates/defindex.html:15 +msgid "lists all sections and subsections" +msgstr "elenca l'insieme delle sezioni e sottosezioni" + +#: sphinx/templates/defindex.html:17 +msgid "search this documentation" +msgstr "cerca in questa documentazione" + +#: sphinx/templates/defindex.html:20 +msgid "quick access to all modules" +msgstr "accesso veloce ai moduli" + +#: sphinx/templates/defindex.html:22 +msgid "all functions, classes, terms" +msgstr "tutte le funzioni, classi e moduli" + +#: sphinx/templates/genindex-single.html:5 +#, python-format +msgid "Index – %(key)s" +msgstr "Indice – %(key)s" + +#: sphinx/templates/genindex-single.html:44 +#: sphinx/templates/genindex-split.html:14 +#: sphinx/templates/genindex-split.html:27 sphinx/templates/genindex.html:54 +msgid "Full index on one page" +msgstr "Indice completo in una pagina" + +#: sphinx/templates/genindex-split.html:7 +msgid "Index pages by letter" +msgstr "Indice delle pagine per lettera" + +#: sphinx/templates/genindex-split.html:15 +msgid "can be huge" +msgstr "può essere enorme" + +#: sphinx/templates/layout.html:9 +msgid "Navigation" +msgstr "Navigazione" + +#: sphinx/templates/layout.html:40 +msgid "Table Of Contents" +msgstr "Tabella dei contenuti" + +#: sphinx/templates/layout.html:46 +msgid "Previous topic" +msgstr "Argomento precedente" + +#: sphinx/templates/layout.html:48 +msgid "previous chapter" +msgstr "capitolo precedente" + +#: sphinx/templates/layout.html:51 +msgid "Next topic" +msgstr "Argomento successivo" + +#: sphinx/templates/layout.html:53 +msgid "next chapter" +msgstr "capitolo successivo" + +#: sphinx/templates/layout.html:58 +msgid "This Page" +msgstr "Questa pagina" + +#: sphinx/templates/layout.html:61 +msgid "Show Source" +msgstr "Mostra sorgente" + +#: sphinx/templates/layout.html:71 +msgid "Quick search" +msgstr "Ricerca veloce" + +#: sphinx/templates/layout.html:74 +msgid "Go" +msgstr "Vai" + +#: sphinx/templates/layout.html:78 +msgid "Enter search terms or a module, class or function name." +msgstr "Inserisci un termine di ricerca un modulo, classe o nome di funzione" + +#: sphinx/templates/layout.html:115 +#, python-format +msgid "Search within %(docstitle)s" +msgstr "Cerca in %(docstitle)s" + +#: sphinx/templates/layout.html:124 +msgid "About these documents" +msgstr "A proposito di questi documenti" + +#: sphinx/templates/layout.html:127 sphinx/templates/search.html:2 +#: sphinx/templates/search.html:5 +msgid "Search" +msgstr "Cerca" + +#: sphinx/templates/layout.html:129 +msgid "Copyright" +msgstr "Copyright" + +#: sphinx/templates/layout.html:174 +#, python-format +msgid "© <a href=\"%(path)s\">Copyright</a> %(copyright)s." +msgstr "© <a href=\"%(path)s\">Copyright</a> %(copyright)s." + +#: sphinx/templates/layout.html:176 +#, python-format +msgid "© Copyright %(copyright)s." +msgstr "© Copyright %(copyright)s." + +#: sphinx/templates/layout.html:179 +#, python-format +msgid "Last updated on %(last_updated)s." +msgstr "Ultimo Aggiornamento on %(last_updated)s." + +#: sphinx/templates/layout.html:182 +#, python-format +msgid "" +"Created using <a href=\"http://sphinx.pocoo.org/\">Sphinx</a> " +"%(sphinx_version)s." +msgstr "" +"Creato con <a href=\"http://sphinx.pocoo.org/\">Sphinx</a> " +"%(sphinx_version)s." + +#: sphinx/templates/modindex.html:36 +msgid "Deprecated" +msgstr "Deprecato" + +#: sphinx/templates/opensearch.xml:4 +#, python-format +msgid "Search %(docstitle)s" +msgstr "Cerca %(docstitle)s" + +#: sphinx/templates/search.html:9 +msgid "" +"Please activate JavaScript to enable the search\n" +" functionality." +msgstr "" + +#: sphinx/templates/search.html:14 +msgid "" +"From here you can search these documents. Enter your search\n" +" words into the box below and click \"search\". Note that the search\n" +" function will automatically search for all of the words. Pages\n" +" containing fewer words won't appear in the result list." +msgstr "" +"Puoi effettuare una ricerca in questi documenti. Immetti le parole chiave" +" \n" +" della tua ricerca nel riquadro sottostante \"cerca\". Nota che la " +"funzione\n" +" di ricerca cerca automaticamente per tutte le parole. Le pagine\n" +" che contendono meno parole non compariranno nei risultati di ricerca." + +#: sphinx/templates/search.html:21 +msgid "search" +msgstr "cerca" + +#: sphinx/templates/search.html:27 +msgid "Your search did not match any results." +msgstr "La tua ricerca non ha ottenuto risultati" + +#: sphinx/templates/changes/frameset.html:5 +#: sphinx/templates/changes/versionchanges.html:12 +#, python-format +msgid "Changes in Version %(version)s — %(docstitle)s" +msgstr "Modifiche nella Versione %(version)s — %(docstitle)s" + +#: sphinx/templates/changes/rstsource.html:5 +#, python-format +msgid "%(filename)s — %(docstitle)s" +msgstr "%(filename)s — %(docstitle)s" + +#: sphinx/templates/changes/versionchanges.html:17 +#, python-format +msgid "Automatically generated list of changes in version %(version)s" +msgstr "Lista delle modifiche generata automaticamente nella versione %(version)s" + +#: sphinx/templates/changes/versionchanges.html:18 +msgid "Library changes" +msgstr "Modifiche nella libreria" + +#: sphinx/templates/changes/versionchanges.html:23 +msgid "C API changes" +msgstr "Modifiche nelle API C" + +#: sphinx/templates/changes/versionchanges.html:25 +msgid "Other changes" +msgstr "Altre modifiche" + +#: sphinx/writers/latex.py:173 +msgid "Release" +msgstr "Release" + +#: sphinx/writers/text.py:166 +#, python-format +msgid "Platform: %s" +msgstr "Piattaforma: %s" + +#: sphinx/writers/text.py:427 +msgid "[image]" +msgstr "[immagine]" + diff --git a/sphinx/locale/ja/LC_MESSAGES/sphinx.js b/sphinx/locale/ja/LC_MESSAGES/sphinx.js index e807d3027..c87bbc2bc 100644 --- a/sphinx/locale/ja/LC_MESSAGES/sphinx.js +++ b/sphinx/locale/ja/LC_MESSAGES/sphinx.js @@ -1 +1 @@ -Documentation.addTranslations({"locale": "ja", "plural_expr": "0", "messages": {"Search Results": "\u691c\u7d22\u7d50\u679c", "Preparing search...": "\u691c\u7d22\u306e\u6e96\u5099\u4e2d...", "Your search did not match any documents. Please make sure that all words are spelled correctly and that you've selected enough categories.": "\u691c\u7d22\u6761\u4ef6\u306b\u4e00\u81f4\u3059\u308b\u30c9\u30ad\u30e5\u30e1\u30f3\u30c8\u306f\u3042\u308a\u307e\u305b\u3093\u3067\u3057\u305f\u3002\u691c\u7d22\u3057\u305f\u3044\u8a00\u8449\u3092\u6b63\u3057\u3044\u3064\u3065\u308a\u3067\u5165\u529b\u3057\u3066\u3044\u308b\u304b\u78ba\u8a8d\u3057\u3066\u304f\u3060\u3055\u3044\u3002\u307e\u305f\u3001\u6b63\u3057\u3044\u30ab\u30c6\u30b4\u30ea\u306e\u691c\u7d22\u3092\u884c\u3063\u3066\u3044\u308b\u304b\u78ba\u8a8d\u3057\u3066\u304f\u3060\u3055\u3044\u3002", "Search finished, found %s page(s) matching the search query.": "\u691c\u7d22\u304c\u7d42\u4e86\u3057\u3001\u6761\u4ef6\u306b\u4e00\u81f4\u3059\u308b\u30da\u30fc\u30b8\u304c %s \u500b\u307f\u3064\u304b\u308a\u307e\u3057\u305f\u3002", "Permalink to this headline": "\u3053\u306e\u30d8\u30c3\u30c9\u30e9\u30a4\u30f3\u3078\u306e\u30d1\u30fc\u30de\u30ea\u30f3\u30af", "Searching": "\u691c\u7d22\u4e2d", "Permalink to this definition": "\u3053\u306e\u5b9a\u7fa9\u3078\u306e\u30d1\u30fc\u30de\u30ea\u30f3\u30af", "Hide Search Matches": "\u691c\u7d22\u7d50\u679c\u3092\u96a0\u3059"}}); \ No newline at end of file +Documentation.addTranslations({"locale": "ja", "plural_expr": "0", "messages": {"module, in ": "\u30e2\u30b8\u30e5\u30fc\u30eb", "Preparing search...": "\u691c\u7d22\u306e\u6e96\u5099\u4e2d...", "Your search did not match any documents. Please make sure that all words are spelled correctly and that you've selected enough categories.": "\u691c\u7d22\u6761\u4ef6\u306b\u4e00\u81f4\u3059\u308b\u30c9\u30ad\u30e5\u30e1\u30f3\u30c8\u306f\u3042\u308a\u307e\u305b\u3093\u3067\u3057\u305f\u3002\u691c\u7d22\u3057\u305f\u3044\u8a00\u8449\u3092\u6b63\u3057\u3044\u3064\u3065\u308a\u3067\u5165\u529b\u3057\u3066\u3044\u308b\u304b\u78ba\u8a8d\u3057\u3066\u304f\u3060\u3055\u3044\u3002\u307e\u305f\u3001\u6b63\u3057\u3044\u30ab\u30c6\u30b4\u30ea\u306e\u691c\u7d22\u3092\u884c\u3063\u3066\u3044\u308b\u304b\u78ba\u8a8d\u3057\u3066\u304f\u3060\u3055\u3044\u3002", "Search finished, found %s page(s) matching the search query.": "\u691c\u7d22\u304c\u7d42\u4e86\u3057\u3001\u6761\u4ef6\u306b\u4e00\u81f4\u3059\u308b\u30da\u30fc\u30b8\u304c %s \u500b\u307f\u3064\u304b\u308a\u307e\u3057\u305f\u3002", ", in ": "", "Permalink to this headline": "\u3053\u306e\u30d8\u30c3\u30c9\u30e9\u30a4\u30f3\u3078\u306e\u30d1\u30fc\u30de\u30ea\u30f3\u30af", "Searching": "\u691c\u7d22\u4e2d", "Permalink to this definition": "\u3053\u306e\u5b9a\u7fa9\u3078\u306e\u30d1\u30fc\u30de\u30ea\u30f3\u30af", "Hide Search Matches": "\u691c\u7d22\u7d50\u679c\u3092\u96a0\u3059", "Search Results": "\u691c\u7d22\u7d50\u679c"}}); \ No newline at end of file diff --git a/sphinx/locale/ja/LC_MESSAGES/sphinx.mo b/sphinx/locale/ja/LC_MESSAGES/sphinx.mo index 3d07bbe75..36735ab52 100644 Binary files a/sphinx/locale/ja/LC_MESSAGES/sphinx.mo and b/sphinx/locale/ja/LC_MESSAGES/sphinx.mo differ diff --git a/sphinx/locale/ja/LC_MESSAGES/sphinx.po b/sphinx/locale/ja/LC_MESSAGES/sphinx.po index 738adc6c3..307a8700c 100644 --- a/sphinx/locale/ja/LC_MESSAGES/sphinx.po +++ b/sphinx/locale/ja/LC_MESSAGES/sphinx.po @@ -3,244 +3,258 @@ # This file is distributed under the same license as the Sphinx project. # Yasushi Masuda <whosaysni@gmail.com>, 2008. # -# msgid "" msgstr "" "Project-Id-Version: Sphinx 0.5\n" "Report-Msgid-Bugs-To: EMAIL@ADDRESS\n" "POT-Creation-Date: 2008-09-11 23:58+0200\n" -"PO-Revision-Date: 2008-09-17 12:00:00+0900\n" +"PO-Revision-Date: 2009-01-24 18:39+0000\n" "Last-Translator: Yasushi MASUDA <whosaysni@gmail.com>\n" "Language-Team: ja <LL@li.org>\n" +"Plural-Forms: nplurals=1; plural=0\n" "MIME-Version: 1.0\n" "Content-Type: text/plain; charset=utf-8\n" "Content-Transfer-Encoding: 8bit\n" "Generated-By: Babel 0.9.3\n" -#: sphinx/builder.py:400 -#, python-format -msgid "%b %d, %Y" -msgstr "%Y 年 %m 月 %d 日" - -#: sphinx/builder.py:419 sphinx/templates/defindex.html:21 -msgid "General Index" -msgstr "総合索引" - -#: sphinx/builder.py:419 -msgid "index" -msgstr "索引" - - -#: sphinx/builder.py:421 sphinx/htmlhelp.py:155 -#: sphinx/templates/defindex.html:19 sphinx/templates/modindex.html:2 -#: sphinx/templates/modindex.html:13 -msgid "Global Module Index" -msgstr "モジュール総索引" - -#: sphinx/builder.py:421 -msgid "modules" -msgstr "モジュール" - -#: sphinx/builder.py:457 -msgid "next" -msgstr "次へ" - -#: sphinx/builder.py:464 -msgid "previous" -msgstr "前へ" - -#: sphinx/builder.py:1108 -msgid "Builtins" -msgstr "組み込み" - -#: sphinx/builder.py:1110 -msgid "Module level" -msgstr "モジュールレベル" - - -#: sphinx/environment.py:107 sphinx/latexwriter.py:129 +#: sphinx/environment.py:104 sphinx/writers/latex.py:170 #, python-format msgid "%B %d, %Y" msgstr "%Y 年 %m 月 %d 日" -#: sphinx/environment.py:270 sphinx/latexwriter.py:190 -#: sphinx/templates/genindex-single.html:2 +#: sphinx/environment.py:300 sphinx/templates/genindex-single.html:2 #: sphinx/templates/genindex-split.html:2 #: sphinx/templates/genindex-split.html:5 sphinx/templates/genindex.html:2 #: sphinx/templates/genindex.html:5 sphinx/templates/genindex.html:48 +#: sphinx/templates/layout.html:126 sphinx/writers/latex.py:176 msgid "Index" msgstr "索引" -#: sphinx/environment.py:271 sphinx/latexwriter.py:188 +#: sphinx/environment.py:301 sphinx/writers/latex.py:175 msgid "Module Index" msgstr "モジュール索引" -#: sphinx/environment.py:272 sphinx/templates/defindex.html:16 +#: sphinx/environment.py:302 sphinx/templates/defindex.html:16 msgid "Search Page" msgstr "検索ページ" -#: sphinx/htmlwriter.py:73 sphinx/static/doctools.js:145 -msgid "Permalink to this definition" -msgstr "この定義へのパーマリンク" - -#: sphinx/htmlwriter.py:375 sphinx/static/doctools.js:139 -msgid "Permalink to this headline" -msgstr "このヘッドラインへのパーマリンク" - -#: sphinx/latexwriter.py:143 -msgid "Release" -msgstr "リリース" - -#: sphinx/roles.py:52 sphinx/directives/desc.py:514 +#: sphinx/roles.py:53 sphinx/directives/desc.py:580 #, python-format msgid "environment variable; %s" msgstr "環境変数; %s" -#: sphinx/roles.py:59 +#: sphinx/roles.py:60 #, python-format msgid "Python Enhancement Proposals!PEP %s" msgstr "Python Enhancement Proposals!PEP %s" -#: sphinx/textwriter.py:151 +#: sphinx/builders/changes.py:64 +msgid "Builtins" +msgstr "組み込み" + +#: sphinx/builders/changes.py:66 +msgid "Module level" +msgstr "モジュールレベル" + +#: sphinx/builders/html.py:118 #, python-format -msgid "Platform: %s" -msgstr "プラットフォーム: %s" +msgid "%b %d, %Y" +msgstr "%Y 年 %m 月 %d 日" -#: sphinx/textwriter.py:353 -msgid "[image]" -msgstr "[画像]" +#: sphinx/builders/html.py:137 sphinx/templates/defindex.html:21 +msgid "General Index" +msgstr "総合索引" -#: sphinx/directives/desc.py:26 +#: sphinx/builders/html.py:137 +msgid "index" +msgstr "索引" + +#: sphinx/builders/html.py:139 sphinx/builders/htmlhelp.py:182 +#: sphinx/builders/qthelp.py:131 sphinx/templates/defindex.html:19 +#: sphinx/templates/modindex.html:2 sphinx/templates/modindex.html:13 +msgid "Global Module Index" +msgstr "モジュール総索引" + +#: sphinx/builders/html.py:139 +msgid "modules" +msgstr "モジュール" + +#: sphinx/builders/html.py:179 +msgid "next" +msgstr "次へ" + +#: sphinx/builders/html.py:186 +msgid "previous" +msgstr "前へ" + +#: sphinx/builders/latex.py:155 sphinx/builders/pdf.py:162 +msgid " (in " +msgstr "" + +#: sphinx/directives/desc.py:25 #, python-format msgid "%s() (built-in function)" msgstr "%s() (組み込み関数)" -#: sphinx/directives/desc.py:27 sphinx/directives/desc.py:41 -#: sphinx/directives/desc.py:53 +#: sphinx/directives/desc.py:26 sphinx/directives/desc.py:42 +#: sphinx/directives/desc.py:54 #, python-format msgid "%s() (in module %s)" msgstr "%s() (%s モジュール)" -#: sphinx/directives/desc.py:30 +#: sphinx/directives/desc.py:29 #, python-format msgid "%s (built-in variable)" msgstr "%s (組み込み変数)" -#: sphinx/directives/desc.py:31 sphinx/directives/desc.py:65 +#: sphinx/directives/desc.py:30 sphinx/directives/desc.py:78 #, python-format msgid "%s (in module %s)" msgstr "%s (%s モジュール)" #: sphinx/directives/desc.py:33 +#, fuzzy, python-format +msgid "%s (built-in class)" +msgstr "%s (組み込み変数)" + +#: sphinx/directives/desc.py:34 #, python-format msgid "%s (class in %s)" msgstr "%s (%s のクラス)" -#: sphinx/directives/desc.py:45 +#: sphinx/directives/desc.py:46 #, python-format msgid "%s() (%s.%s method)" msgstr "%s() (%s.%s のメソッド)" -#: sphinx/directives/desc.py:47 +#: sphinx/directives/desc.py:48 #, python-format msgid "%s() (%s method)" msgstr "%s() (%s のメソッド)" -#: sphinx/directives/desc.py:57 +#: sphinx/directives/desc.py:58 #, python-format msgid "%s() (%s.%s static method)" msgstr "%s() (%s.%s の静的メソッド)" -#: sphinx/directives/desc.py:59 +#: sphinx/directives/desc.py:60 #, python-format msgid "%s() (%s static method)" msgstr "%s() (%s の静的メソッド)" -#: sphinx/directives/desc.py:69 +#: sphinx/directives/desc.py:82 #, python-format msgid "%s (%s.%s attribute)" msgstr "%s (%s.%s の属性)" -#: sphinx/directives/desc.py:71 +#: sphinx/directives/desc.py:84 #, python-format msgid "%s (%s attribute)" msgstr "%s (%s の属性)" -#: sphinx/directives/desc.py:73 +#: sphinx/directives/desc.py:86 #, python-format msgid "%s (C function)" msgstr "%s (C の関数)" -#: sphinx/directives/desc.py:75 +#: sphinx/directives/desc.py:88 #, python-format msgid "%s (C member)" msgstr "%s (C のメンバ変数)" -#: sphinx/directives/desc.py:77 +#: sphinx/directives/desc.py:90 #, python-format msgid "%s (C macro)" msgstr "%s (C のマクロ)" -#: sphinx/directives/desc.py:79 +#: sphinx/directives/desc.py:92 #, python-format msgid "%s (C type)" msgstr "%s (C のデータ型)" -#: sphinx/directives/desc.py:81 +#: sphinx/directives/desc.py:94 #, python-format msgid "%s (C variable)" msgstr "%s (C の変数)" -#: sphinx/directives/desc.py:99 +#: sphinx/directives/desc.py:112 msgid "Raises" msgstr "例外" -#: sphinx/directives/desc.py:103 +#: sphinx/directives/desc.py:116 msgid "Variable" msgstr "変数" -#: sphinx/directives/desc.py:106 +#: sphinx/directives/desc.py:119 msgid "Returns" msgstr "戻り値" -#: sphinx/directives/desc.py:113 +#: sphinx/directives/desc.py:128 msgid "Return type" msgstr "戻り値の型" -#: sphinx/directives/desc.py:140 +#: sphinx/directives/desc.py:213 +#, fuzzy +msgid "Parameter" +msgstr "パラメタ" + +#: sphinx/directives/desc.py:217 msgid "Parameters" msgstr "パラメタ" -#: sphinx/directives/desc.py:402 -#, python-format -msgid "command line option; %s" -msgstr "コマンドラインオプション; %s" +#: sphinx/directives/desc.py:465 +#, fuzzy, python-format +msgid "%scommand line option; %s" +msgstr "%sコマンドラインオプション; %s" -#: sphinx/directives/other.py:102 +#: sphinx/directives/other.py:101 msgid "Platforms: " msgstr "プラットフォーム: " -#: sphinx/directives/other.py:107 +#: sphinx/directives/other.py:106 #, python-format msgid "%s (module)" msgstr "%s (モジュール)" -#: sphinx/directives/other.py:147 +#: sphinx/directives/other.py:146 msgid "Section author: " msgstr "この節の作者: " -#: sphinx/directives/other.py:149 +#: sphinx/directives/other.py:148 msgid "Module author: " msgstr "モジュールの作者: " -#: sphinx/directives/other.py:151 +#: sphinx/directives/other.py:150 msgid "Author: " msgstr "作者: " -#: sphinx/directives/other.py:233 +#: sphinx/directives/other.py:249 msgid "See also" msgstr "参考" +#: sphinx/ext/autodoc.py:442 +#, python-format +msgid " Bases: %s" +msgstr "" + +#: sphinx/ext/autodoc.py:566 sphinx/ext/autodoc.py:583 +#, python-format +msgid "alias of :class:`%s`" +msgstr "" + +#: sphinx/ext/todo.py:31 +msgid "Todo" +msgstr "" + +#: sphinx/ext/todo.py:75 +#, python-format +msgid "(The original entry is located in %s, line %d and can be found " +msgstr "" + +#: sphinx/ext/todo.py:81 +msgid "here" +msgstr "" + #: sphinx/locale/__init__.py:15 msgid "Attention" msgstr "注意" @@ -324,6 +338,14 @@ msgstr "文" msgid "built-in function" msgstr "組み込み関数" +#: sphinx/static/doctools.js:139 sphinx/writers/html.py:425 +msgid "Permalink to this headline" +msgstr "このヘッドラインへのパーマリンク" + +#: sphinx/static/doctools.js:145 sphinx/writers/html.py:80 +msgid "Permalink to this definition" +msgstr "この定義へのパーマリンク" + #: sphinx/static/doctools.js:174 msgid "Hide Search Matches" msgstr "検索結果を隠す" @@ -336,20 +358,26 @@ msgstr "検索中" msgid "Preparing search..." msgstr "検索の準備中..." -#: sphinx/static/searchtools.js:401 sphinx/templates/search.html:18 +#: sphinx/static/searchtools.js:338 +#, fuzzy +msgid "module, in " +msgstr "モジュール" + +#: sphinx/static/searchtools.js:347 +msgid ", in " +msgstr "" + +#: sphinx/static/searchtools.js:453 sphinx/templates/search.html:25 msgid "Search Results" msgstr "検索結果" -#: sphinx/static/searchtools.js:403 +#: sphinx/static/searchtools.js:455 msgid "" "Your search did not match any documents. Please make sure that all words " "are spelled correctly and that you've selected enough categories." -msgstr "" -"検索条件に一致するドキュメントはありませんでした。検索したい言葉を" -"正しいつづりで入力しているか確認してください。また、正しいカテゴリ" -"の検索を行っているか確認してください。" +msgstr "検索条件に一致するドキュメントはありませんでした。検索したい言葉を正しいつづりで入力しているか確認してください。また、正しいカテゴリの検索を行っているか確認してください。" -#: sphinx/static/searchtools.js:405 +#: sphinx/static/searchtools.js:457 #, python-format msgid "Search finished, found %s page(s) matching the search query." msgstr "検索が終了し、条件に一致するページが %s 個みつかりました。" @@ -413,27 +441,23 @@ msgstr "目次" msgid "Previous topic" msgstr "前のトピックへ" -#: sphinx/templates/layout.html:47 +#: sphinx/templates/layout.html:48 msgid "previous chapter" msgstr "前の章へ" -#: sphinx/templates/layout.html:50 +#: sphinx/templates/layout.html:51 msgid "Next topic" msgstr "次のトピックへ" -#: sphinx/templates/layout.html:51 +#: sphinx/templates/layout.html:53 msgid "next chapter" msgstr "次の章へ" -#: sphinx/templates/layout.html:55 +#: sphinx/templates/layout.html:58 msgid "This Page" msgstr "このページ" -#: sphinx/templates/layout.html:59 -msgid "Suggest Change" -msgstr "変更のサジェスト" - -#: sphinx/templates/layout.html:60 sphinx/templates/layout.html:62 +#: sphinx/templates/layout.html:61 msgid "Show Source" msgstr "ソースコードを表示" @@ -441,60 +465,49 @@ msgstr "ソースコードを表示" msgid "Quick search" msgstr "クイック検索" -#: sphinx/templates/layout.html:71 -msgid "Keyword search" -msgstr "キーワード検索" - -#: sphinx/templates/layout.html:73 +#: sphinx/templates/layout.html:74 msgid "Go" msgstr "検索" #: sphinx/templates/layout.html:78 -msgid "Enter a module, class or function name." +#, fuzzy +msgid "Enter search terms or a module, class or function name." msgstr "モジュール、クラス、または関数名を入力してください" -#: sphinx/templates/layout.html:118 +#: sphinx/templates/layout.html:115 #, python-format msgid "Search within %(docstitle)s" msgstr "%(docstitle)s 内を検索" -#: sphinx/templates/layout.html:127 +#: sphinx/templates/layout.html:124 msgid "About these documents" msgstr "このドキュメントについて" -#: sphinx/templates/layout.html:129 -msgid "Global table of contents" -msgstr "総目次" - -#: sphinx/templates/layout.html:130 -msgid "Global index" -msgstr "総合索引" - -#: sphinx/templates/layout.html:131 sphinx/templates/search.html:2 +#: sphinx/templates/layout.html:127 sphinx/templates/search.html:2 #: sphinx/templates/search.html:5 msgid "Search" msgstr "検索" -#: sphinx/templates/layout.html:133 +#: sphinx/templates/layout.html:129 msgid "Copyright" msgstr "著作権" -#: sphinx/templates/layout.html:178 +#: sphinx/templates/layout.html:174 #, python-format msgid "© <a href=\"%(path)s\">Copyright</a> %(copyright)s." msgstr "© <a href=\"%(path)s\">Copyright</a> %(copyright)s." -#: sphinx/templates/layout.html:180 +#: sphinx/templates/layout.html:176 #, python-format msgid "© Copyright %(copyright)s." msgstr "© Copyright %(copyright)s." -#: sphinx/templates/layout.html:183 +#: sphinx/templates/layout.html:179 #, python-format msgid "Last updated on %(last_updated)s." msgstr "最終更新: %(last_updated)s" -#: sphinx/templates/layout.html:186 +#: sphinx/templates/layout.html:182 #, python-format msgid "" "Created using <a href=\"http://sphinx.pocoo.org/\">Sphinx</a> " @@ -503,15 +516,7 @@ msgstr "" "このドキュメントは <a href=\"http://sphinx.pocoo.org/\">Sphinx</a> " "%(sphinx_version)s で生成しました。" -#: sphinx/templates/modindex.html:15 -msgid "Most popular modules:" -msgstr "よく参照されているモジュール:" - -#: sphinx/templates/modindex.html:24 -msgid "Show modules only available on these platforms" -msgstr "このプラットフォームで利用可能なモジュールだけを表示する" - -#: sphinx/templates/modindex.html:56 +#: sphinx/templates/modindex.html:36 msgid "Deprecated" msgstr "撤廃" @@ -520,33 +525,26 @@ msgstr "撤廃" msgid "Search %(docstitle)s" msgstr "%(docstitle)s 内を検索" -#: sphinx/templates/page.html:8 +#: sphinx/templates/search.html:9 msgid "" -"<strong>Note:</strong> You requested an out-of-date URL from this server." -" We've tried to redirect you to the new location of this page, but it may" -" not be the right one." +"Please activate JavaScript to enable the search\n" +" functionality." msgstr "" -"<strong>注意:</strong> あなたが表示しようとしているのは古い URL です。" -"このページに対応する新しい URL へのリダイレクトを試みますが、" -"適切なリダイレクト先でないかもしれないので注意してください。" -#: sphinx/templates/search.html:7 +#: sphinx/templates/search.html:14 +#, fuzzy msgid "" "From here you can search these documents. Enter your search\n" " words into the box below and click \"search\". Note that the search\n" " function will automatically search for all of the words. Pages\n" -" containing less words won't appear in the result list." -msgstr "" -"このページからドキュメントを検索できます。キーワードを下のボックスに入力" -"して、「検索」をクリックしてください。入力された全てのキーワードを含む" -"ページが検索されます。一部のキーワードしか含まないページは検索結果に" -"表示されないので注意してください。" +" containing fewer words won't appear in the result list." +msgstr "このページからドキュメントを検索できます。キーワードを下のボックスに入力して、「検索」をクリックしてください。入力された全てのキーワードを含むページが検索されます。一部のキーワードしか含まないページは検索結果に表示されないので注意してください。" -#: sphinx/templates/search.html:14 +#: sphinx/templates/search.html:21 msgid "search" msgstr "検索" -#: sphinx/templates/search.html:20 +#: sphinx/templates/search.html:27 msgid "Your search did not match any results." msgstr "検索条件に一致する項目がありませんでした。" @@ -578,3 +576,16 @@ msgstr "C API に関する変更" msgid "Other changes" msgstr "その多の変更" +#: sphinx/writers/latex.py:173 +msgid "Release" +msgstr "リリース" + +#: sphinx/writers/text.py:166 +#, python-format +msgid "Platform: %s" +msgstr "プラットフォーム: %s" + +#: sphinx/writers/text.py:427 +msgid "[image]" +msgstr "[画像]" + diff --git a/sphinx/locale/nl/LC_MESSAGES/sphinx.js b/sphinx/locale/nl/LC_MESSAGES/sphinx.js new file mode 100644 index 000000000..2dafd39f1 --- /dev/null +++ b/sphinx/locale/nl/LC_MESSAGES/sphinx.js @@ -0,0 +1 @@ +Documentation.addTranslations({"locale": "nl", "plural_expr": "(n != 1)", "messages": {"module, in ": "module", "Preparing search...": "Het zoeken wordt voorbereid", "Your search did not match any documents. Please make sure that all words are spelled correctly and that you've selected enough categories.": "Uw zoekopdracht leverde geen resultaten op. Controleer of alle woordencorrect gespeld zijn en dat u genoeg categori\u00ebn hebt geselecteerd.", "Search finished, found %s page(s) matching the search query.": "Zoeken voltooid, %s pagina(s) gevonden.", ", in ": "", "Permalink to this headline": "Permanente link naar deze titel", "Searching": "Zoeken", "Permalink to this definition": "Permanente link naar deze definitie", "Hide Search Matches": "Zoekresultaten verbergen", "Search Results": "Zoekresultaten"}}); \ No newline at end of file diff --git a/sphinx/locale/nl/LC_MESSAGES/sphinx.mo b/sphinx/locale/nl/LC_MESSAGES/sphinx.mo new file mode 100644 index 000000000..035fd0e32 Binary files /dev/null and b/sphinx/locale/nl/LC_MESSAGES/sphinx.mo differ diff --git a/sphinx/locale/nl/LC_MESSAGES/sphinx.po b/sphinx/locale/nl/LC_MESSAGES/sphinx.po new file mode 100644 index 000000000..1dbc43992 --- /dev/null +++ b/sphinx/locale/nl/LC_MESSAGES/sphinx.po @@ -0,0 +1,598 @@ +# Copyright (C) 2008 ORGANIZATION +# This file is distributed under the same license as the Sphinx project. +# FIRST AUTHOR <EMAIL@ADDRESS>, 2008. +# +msgid "" +msgstr "" +"Project-Id-Version: Sphinx 0.5\n" +"Report-Msgid-Bugs-To: EMAIL@ADDRESS\n" +"POT-Creation-Date: 2008-09-11 23:58+0200\n" +"PO-Revision-Date: 2009-01-24 18:39+0000\n" +"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n" +"Language-Team: nl <LL@li.org>\n" +"Plural-Forms: nplurals=2; plural=(n != 1)\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=utf-8\n" +"Content-Transfer-Encoding: 8bit\n" +"Generated-By: Babel 0.9.3\n" + +#: sphinx/environment.py:104 sphinx/writers/latex.py:170 +#, python-format +msgid "%B %d, %Y" +msgstr "%d. %B %Y" + +#: sphinx/environment.py:300 sphinx/templates/genindex-single.html:2 +#: sphinx/templates/genindex-split.html:2 +#: sphinx/templates/genindex-split.html:5 sphinx/templates/genindex.html:2 +#: sphinx/templates/genindex.html:5 sphinx/templates/genindex.html:48 +#: sphinx/templates/layout.html:126 sphinx/writers/latex.py:176 +msgid "Index" +msgstr "Index" + +#: sphinx/environment.py:301 sphinx/writers/latex.py:175 +msgid "Module Index" +msgstr "Module-index" + +#: sphinx/environment.py:302 sphinx/templates/defindex.html:16 +msgid "Search Page" +msgstr "Zoekpagina" + +#: sphinx/roles.py:53 sphinx/directives/desc.py:580 +#, python-format +msgid "environment variable; %s" +msgstr "Omgevingsvariabele; %s" + +#: sphinx/roles.py:60 +#, python-format +msgid "Python Enhancement Proposals!PEP %s" +msgstr "Python Enhancement Proposals!PEP %s" + +#: sphinx/builders/changes.py:64 +msgid "Builtins" +msgstr "Builtins" + +#: sphinx/builders/changes.py:66 +msgid "Module level" +msgstr "Moduleniveau" + +#: sphinx/builders/html.py:118 +#, python-format +msgid "%b %d, %Y" +msgstr "%d.%b.%Y" + +#: sphinx/builders/html.py:137 sphinx/templates/defindex.html:21 +msgid "General Index" +msgstr "Algemene index" + +#: sphinx/builders/html.py:137 +msgid "index" +msgstr "Index" + +#: sphinx/builders/html.py:139 sphinx/builders/htmlhelp.py:182 +#: sphinx/builders/qthelp.py:131 sphinx/templates/defindex.html:19 +#: sphinx/templates/modindex.html:2 sphinx/templates/modindex.html:13 +msgid "Global Module Index" +msgstr "Globale Module-index" + +#: sphinx/builders/html.py:139 +msgid "modules" +msgstr "modules" + +#: sphinx/builders/html.py:179 +msgid "next" +msgstr "volgende" + +#: sphinx/builders/html.py:186 +msgid "previous" +msgstr "vorige" + +#: sphinx/builders/latex.py:155 sphinx/builders/pdf.py:162 +msgid " (in " +msgstr "" + +#: sphinx/directives/desc.py:25 +#, python-format +msgid "%s() (built-in function)" +msgstr "%s() (geïntegreerde functie)" + +#: sphinx/directives/desc.py:26 sphinx/directives/desc.py:42 +#: sphinx/directives/desc.py:54 +#, python-format +msgid "%s() (in module %s)" +msgstr "%s() (in module %s)" + +#: sphinx/directives/desc.py:29 +#, python-format +msgid "%s (built-in variable)" +msgstr "%s (geïntegreerde variabele)" + +#: sphinx/directives/desc.py:30 sphinx/directives/desc.py:78 +#, python-format +msgid "%s (in module %s)" +msgstr "%s (in module %s)" + +#: sphinx/directives/desc.py:33 +#, fuzzy, python-format +msgid "%s (built-in class)" +msgstr "%s (geïntegreerde variabele)" + +#: sphinx/directives/desc.py:34 +#, python-format +msgid "%s (class in %s)" +msgstr "%s (klasse in %s)" + +#: sphinx/directives/desc.py:46 +#, python-format +msgid "%s() (%s.%s method)" +msgstr "%s() (%s.%s methode)" + +#: sphinx/directives/desc.py:48 +#, python-format +msgid "%s() (%s method)" +msgstr "%s() (%s methode)" + +#: sphinx/directives/desc.py:58 +#, python-format +msgid "%s() (%s.%s static method)" +msgstr "%s() (%s.%s statische methode)" + +#: sphinx/directives/desc.py:60 +#, python-format +msgid "%s() (%s static method)" +msgstr "%s() (%s statische methode)" + +#: sphinx/directives/desc.py:82 +#, python-format +msgid "%s (%s.%s attribute)" +msgstr "%s (%s.%s attribuut)" + +#: sphinx/directives/desc.py:84 +#, python-format +msgid "%s (%s attribute)" +msgstr "%s (%s attribuut)" + +#: sphinx/directives/desc.py:86 +#, python-format +msgid "%s (C function)" +msgstr "%s (C-functie)" + +#: sphinx/directives/desc.py:88 +#, python-format +msgid "%s (C member)" +msgstr "%s (C member)" + +#: sphinx/directives/desc.py:90 +#, python-format +msgid "%s (C macro)" +msgstr "%s (C-macro)" + +#: sphinx/directives/desc.py:92 +#, python-format +msgid "%s (C type)" +msgstr "%s (C type)" + +#: sphinx/directives/desc.py:94 +#, python-format +msgid "%s (C variable)" +msgstr "%s (C-variabele)" + +#: sphinx/directives/desc.py:112 +msgid "Raises" +msgstr "Veroorzaakt" + +#: sphinx/directives/desc.py:116 +msgid "Variable" +msgstr "Variabele" + +#: sphinx/directives/desc.py:119 +msgid "Returns" +msgstr "Returns" + +#: sphinx/directives/desc.py:128 +msgid "Return type" +msgstr "Return type" + +#: sphinx/directives/desc.py:213 +#, fuzzy +msgid "Parameter" +msgstr "Parameters" + +#: sphinx/directives/desc.py:217 +msgid "Parameters" +msgstr "Parameters" + +#: sphinx/directives/desc.py:465 +#, fuzzy, python-format +msgid "%scommand line option; %s" +msgstr "%scommandolijn optie; %s" + +#: sphinx/directives/other.py:101 +msgid "Platforms: " +msgstr "Platformen: " + +#: sphinx/directives/other.py:106 +#, python-format +msgid "%s (module)" +msgstr "%s (module)" + +#: sphinx/directives/other.py:146 +msgid "Section author: " +msgstr "Auteur van deze sectie: " + +#: sphinx/directives/other.py:148 +msgid "Module author: " +msgstr "Auteur van deze module: " + +#: sphinx/directives/other.py:150 +msgid "Author: " +msgstr "Auteur: " + +#: sphinx/directives/other.py:249 +msgid "See also" +msgstr "Zie ook" + +#: sphinx/ext/autodoc.py:442 +#, python-format +msgid " Bases: %s" +msgstr "" + +#: sphinx/ext/autodoc.py:566 sphinx/ext/autodoc.py:583 +#, python-format +msgid "alias of :class:`%s`" +msgstr "" + +#: sphinx/ext/todo.py:31 +msgid "Todo" +msgstr "" + +#: sphinx/ext/todo.py:75 +#, python-format +msgid "(The original entry is located in %s, line %d and can be found " +msgstr "" + +#: sphinx/ext/todo.py:81 +msgid "here" +msgstr "" + +#: sphinx/locale/__init__.py:15 +msgid "Attention" +msgstr "Let op!" + +#: sphinx/locale/__init__.py:16 +msgid "Caution" +msgstr "Pas op!" + +#: sphinx/locale/__init__.py:17 +msgid "Danger" +msgstr "Gevaar" + +#: sphinx/locale/__init__.py:18 +msgid "Error" +msgstr "Fout" + +#: sphinx/locale/__init__.py:19 +msgid "Hint" +msgstr "Hint" + +#: sphinx/locale/__init__.py:20 +msgid "Important" +msgstr "Belangrijk" + +#: sphinx/locale/__init__.py:21 +msgid "Note" +msgstr "Notitie" + +#: sphinx/locale/__init__.py:22 +msgid "See Also" +msgstr "Zie Ook" + +#: sphinx/locale/__init__.py:23 +msgid "Tip" +msgstr "Tip" + +#: sphinx/locale/__init__.py:24 +msgid "Warning" +msgstr "Waarschuwing" + +#: sphinx/locale/__init__.py:28 +#, python-format +msgid "New in version %s" +msgstr "Nieuw in versie %s" + +#: sphinx/locale/__init__.py:29 +#, python-format +msgid "Changed in version %s" +msgstr "Veranderd in versie %s" + +#: sphinx/locale/__init__.py:30 +#, python-format +msgid "Deprecated since version %s" +msgstr "Verouderd sinds versie %s" + +#: sphinx/locale/__init__.py:34 +msgid "module" +msgstr "module" + +#: sphinx/locale/__init__.py:35 +msgid "keyword" +msgstr "trefwoord" + +#: sphinx/locale/__init__.py:36 +msgid "operator" +msgstr "operator" + +#: sphinx/locale/__init__.py:37 +msgid "object" +msgstr "object" + +#: sphinx/locale/__init__.py:38 +msgid "exception" +msgstr "foutmelding" + +#: sphinx/locale/__init__.py:39 +msgid "statement" +msgstr "statement" + +#: sphinx/locale/__init__.py:40 +msgid "built-in function" +msgstr "geïntegreerde functie" + +#: sphinx/static/doctools.js:139 sphinx/writers/html.py:425 +msgid "Permalink to this headline" +msgstr "Permanente link naar deze titel" + +#: sphinx/static/doctools.js:145 sphinx/writers/html.py:80 +msgid "Permalink to this definition" +msgstr "Permanente link naar deze definitie" + +#: sphinx/static/doctools.js:174 +msgid "Hide Search Matches" +msgstr "Zoekresultaten verbergen" + +#: sphinx/static/searchtools.js:274 +msgid "Searching" +msgstr "Zoeken" + +#: sphinx/static/searchtools.js:279 +msgid "Preparing search..." +msgstr "Het zoeken wordt voorbereid" + +#: sphinx/static/searchtools.js:338 +#, fuzzy +msgid "module, in " +msgstr "module" + +#: sphinx/static/searchtools.js:347 +msgid ", in " +msgstr "" + +#: sphinx/static/searchtools.js:453 sphinx/templates/search.html:25 +msgid "Search Results" +msgstr "Zoekresultaten" + +#: sphinx/static/searchtools.js:455 +msgid "" +"Your search did not match any documents. Please make sure that all words " +"are spelled correctly and that you've selected enough categories." +msgstr "" +"Uw zoekopdracht leverde geen resultaten op. Controleer of alle " +"woordencorrect gespeld zijn en dat u genoeg categoriën hebt geselecteerd." + +#: sphinx/static/searchtools.js:457 +#, python-format +msgid "Search finished, found %s page(s) matching the search query." +msgstr "Zoeken voltooid, %s pagina(s) gevonden." + +#: sphinx/templates/defindex.html:2 +msgid "Overview" +msgstr "Overzicht" + +#: sphinx/templates/defindex.html:11 +msgid "Indices and tables:" +msgstr "Indices en tabellen:" + +#: sphinx/templates/defindex.html:14 +msgid "Complete Table of Contents" +msgstr "Volledige inhoudstafel" + +#: sphinx/templates/defindex.html:15 +msgid "lists all sections and subsections" +msgstr "geeft alle secties en subsecties weer" + +#: sphinx/templates/defindex.html:17 +msgid "search this documentation" +msgstr "zoeken in deze documentatie" + +#: sphinx/templates/defindex.html:20 +msgid "quick access to all modules" +msgstr "sneltoegang naar alle modules" + +#: sphinx/templates/defindex.html:22 +msgid "all functions, classes, terms" +msgstr "alle functies, klasses en begrippen" + +#: sphinx/templates/genindex-single.html:5 +#, python-format +msgid "Index – %(key)s" +msgstr "Index – %(key)s" + +#: sphinx/templates/genindex-single.html:44 +#: sphinx/templates/genindex-split.html:14 +#: sphinx/templates/genindex-split.html:27 sphinx/templates/genindex.html:54 +msgid "Full index on one page" +msgstr "Volledige index op een pagina" + +#: sphinx/templates/genindex-split.html:7 +msgid "Index pages by letter" +msgstr "Index pagineerd per letter" + +#: sphinx/templates/genindex-split.html:15 +msgid "can be huge" +msgstr "kan heel groot zijn" + +#: sphinx/templates/layout.html:9 +msgid "Navigation" +msgstr "Navigatie" + +#: sphinx/templates/layout.html:40 +msgid "Table Of Contents" +msgstr "Inhoudstafel" + +#: sphinx/templates/layout.html:46 +msgid "Previous topic" +msgstr "Vorig onderwerp" + +#: sphinx/templates/layout.html:48 +msgid "previous chapter" +msgstr "Vorig hoofdstuk" + +#: sphinx/templates/layout.html:51 +msgid "Next topic" +msgstr "Volgend onderwerp" + +#: sphinx/templates/layout.html:53 +msgid "next chapter" +msgstr "volgend hoofdstuk" + +#: sphinx/templates/layout.html:58 +msgid "This Page" +msgstr "Deze Pagina" + +#: sphinx/templates/layout.html:61 +msgid "Show Source" +msgstr "Broncode weergeven" + +#: sphinx/templates/layout.html:71 +msgid "Quick search" +msgstr "Snel zoeken" + +#: sphinx/templates/layout.html:74 +msgid "Go" +msgstr "Go" + +#: sphinx/templates/layout.html:78 +#, fuzzy +msgid "Enter search terms or a module, class or function name." +msgstr "Geef de naam van een module, klasse of functie." + +#: sphinx/templates/layout.html:115 +#, python-format +msgid "Search within %(docstitle)s" +msgstr "Zoeken in %(docstitle)s" + +#: sphinx/templates/layout.html:124 +msgid "About these documents" +msgstr "Over deze documenten" + +#: sphinx/templates/layout.html:127 sphinx/templates/search.html:2 +#: sphinx/templates/search.html:5 +msgid "Search" +msgstr "Zoeken" + +#: sphinx/templates/layout.html:129 +msgid "Copyright" +msgstr "Copyright" + +#: sphinx/templates/layout.html:174 +#, python-format +msgid "© <a href=\"%(path)s\">Copyright</a> %(copyright)s." +msgstr "© <a href=\"%(path)s\">Copyright</a> %(copyright)s." + +#: sphinx/templates/layout.html:176 +#, python-format +msgid "© Copyright %(copyright)s." +msgstr "© Copyright %(copyright)s." + +#: sphinx/templates/layout.html:179 +#, python-format +msgid "Last updated on %(last_updated)s." +msgstr "Laatste aanpassing op %(last_updated)s." + +#: sphinx/templates/layout.html:182 +#, python-format +msgid "" +"Created using <a href=\"http://sphinx.pocoo.org/\">Sphinx</a> " +"%(sphinx_version)s." +msgstr "" +"Aangemaakt met <a href=\"http://sphinx.pocoo.org/\">Sphinx</a> " +"%(sphinx_version)s." + +#: sphinx/templates/modindex.html:36 +msgid "Deprecated" +msgstr "Verouderd" + +#: sphinx/templates/opensearch.xml:4 +#, python-format +msgid "Search %(docstitle)s" +msgstr "Zoeken %(docstitle)s" + +#: sphinx/templates/search.html:9 +msgid "" +"Please activate JavaScript to enable the search\n" +" functionality." +msgstr "" + +#: sphinx/templates/search.html:14 +#, fuzzy +msgid "" +"From here you can search these documents. Enter your search\n" +" words into the box below and click \"search\". Note that the search\n" +" function will automatically search for all of the words. Pages\n" +" containing fewer words won't appear in the result list." +msgstr "" +"Hier kan u de documenten doorzoeken. Geef enkele trefwoorden\n" +" in het veld hieronder en klik \"zoeken\". Merk op dat de zoekfunctie" +"\n" +" steeds naar alle woorden zoekt. Pagina's die minder woorden bevatten" +"\n" +" zullen niet tussen de resultaten verschijnen." + +#: sphinx/templates/search.html:21 +msgid "search" +msgstr "zoeken" + +#: sphinx/templates/search.html:27 +msgid "Your search did not match any results." +msgstr "Uw zoekopdracht leverde geen resultaten op." + +#: sphinx/templates/changes/frameset.html:5 +#: sphinx/templates/changes/versionchanges.html:12 +#, python-format +msgid "Changes in Version %(version)s — %(docstitle)s" +msgstr "Veranderingen in versie %(version)s — %(docstitle)s" + +#: sphinx/templates/changes/rstsource.html:5 +#, python-format +msgid "%(filename)s — %(docstitle)s" +msgstr "%(filename)s — %(docstitle)s" + +#: sphinx/templates/changes/versionchanges.html:17 +#, python-format +msgid "Automatically generated list of changes in version %(version)s" +msgstr "Automatisch genereerde lijst van veranderingen in versie %(version)s" + +#: sphinx/templates/changes/versionchanges.html:18 +msgid "Library changes" +msgstr "Veranderingen in de bibliotheek" + +#: sphinx/templates/changes/versionchanges.html:23 +msgid "C API changes" +msgstr "Veranderingen in de C-API" + +#: sphinx/templates/changes/versionchanges.html:25 +msgid "Other changes" +msgstr "Andere veranderingen" + +#: sphinx/writers/latex.py:173 +msgid "Release" +msgstr "Release" + +#: sphinx/writers/text.py:166 +#, python-format +msgid "Platform: %s" +msgstr "Platform: %s" + +#: sphinx/writers/text.py:427 +msgid "[image]" +msgstr "[afbeelding]" + diff --git a/sphinx/locale/pl/LC_MESSAGES/sphinx.js b/sphinx/locale/pl/LC_MESSAGES/sphinx.js index 2a769c986..ce79a1798 100644 --- a/sphinx/locale/pl/LC_MESSAGES/sphinx.js +++ b/sphinx/locale/pl/LC_MESSAGES/sphinx.js @@ -1 +1 @@ -Documentation.addTranslations({"locale": "pl", "plural_expr": "(n==1 ? 0 : n%10>=2 && n%10<=4 && (n%100<10 || n%100>=20) ? 1 : 2)", "messages": {"Search Results": "Wyniki wyszukiwania", "Preparing search...": "Przygotowanie wyszukiwania...", "Your search did not match any documents. Please make sure that all words are spelled correctly and that you've selected enough categories.": "Nie znaleziono \u017cadnych pasuj\u0105cych dokument\u00f3w. Upewnij si\u0119, \u017ce wszystkie s\u0142owa s\u0105 poprawnie wpisane i \u017ce wybra\u0142e\u015b wystarczaj\u0105c\u0105liczb\u0119 kategorii.", "Search finished, found %s page(s) matching the search query.": "Przeszukiwanie zako\u0144czone, znaleziono %s pasuj\u0105cych stron.", "Permalink to this headline": "Sta\u0142y odno\u015bnik do tego nag\u0142\u00f3wka", "Searching": "Wyszukiwanie", "Permalink to this definition": "Sta\u0142y odno\u015bnik do tej definicji", "Hide Search Matches": "Ukryj wyniki wyszukiwania"}}); \ No newline at end of file +Documentation.addTranslations({"locale": "pl", "plural_expr": "(n==1 ? 0 : n%10>=2 && n%10<=4 && (n%100<10 || n%100>=20) ? 1 : 2)", "messages": {"module, in ": "modu\u0142", "Preparing search...": "Przygotowanie wyszukiwania...", "Your search did not match any documents. Please make sure that all words are spelled correctly and that you've selected enough categories.": "Nie znaleziono \u017cadnych pasuj\u0105cych dokument\u00f3w. Upewnij si\u0119, \u017ce wszystkie s\u0142owa s\u0105 poprawnie wpisane i \u017ce wybra\u0142e\u015b wystarczaj\u0105c\u0105liczb\u0119 kategorii.", "Search finished, found %s page(s) matching the search query.": "Przeszukiwanie zako\u0144czone, znaleziono %s pasuj\u0105cych stron.", ", in ": "", "Permalink to this headline": "Sta\u0142y odno\u015bnik do tego nag\u0142\u00f3wka", "Searching": "Wyszukiwanie", "Permalink to this definition": "Sta\u0142y odno\u015bnik do tej definicji", "Hide Search Matches": "Ukryj wyniki wyszukiwania", "Search Results": "Wyniki wyszukiwania"}}); \ No newline at end of file diff --git a/sphinx/locale/pl/LC_MESSAGES/sphinx.mo b/sphinx/locale/pl/LC_MESSAGES/sphinx.mo index 88fbe3f83..93fd9f945 100644 Binary files a/sphinx/locale/pl/LC_MESSAGES/sphinx.mo and b/sphinx/locale/pl/LC_MESSAGES/sphinx.mo differ diff --git a/sphinx/locale/pl/LC_MESSAGES/sphinx.po b/sphinx/locale/pl/LC_MESSAGES/sphinx.po index 9ab396636..990c8e383 100644 --- a/sphinx/locale/pl/LC_MESSAGES/sphinx.po +++ b/sphinx/locale/pl/LC_MESSAGES/sphinx.po @@ -1,9 +1,10 @@ + msgid "" msgstr "" "Project-Id-Version: Sphinx 0.5\n" "Report-Msgid-Bugs-To: EMAIL@ADDRESS\n" "POT-Creation-Date: 2008-08-10 11:43+0000\n" -"PO-Revision-Date: 2008-09-16 15:47+0100\n" +"PO-Revision-Date: 2009-01-24 18:39+0000\n" "Last-Translator: Michał Kandulski <Michal.Kandulski@poczta.onet.pl>\n" "Language-Team: \n" "Plural-Forms: nplurals=3; plural=(n==1 ? 0 : n%10>=2 && n%10<=4 && " @@ -13,242 +14,244 @@ msgstr "" "Content-Transfer-Encoding: 8bit\n" "Generated-By: Babel 0.9.3\n" -#: sphinx/builder.py:400 -#, python-format -msgid "%b %d, %Y" -msgstr "%b %d %Y" - -#: sphinx/builder.py:419 -#: sphinx/templates/defindex.html:21 -msgid "General Index" -msgstr "Indeks ogólny" - -#: sphinx/builder.py:419 -msgid "index" -msgstr "indeks" - -#: sphinx/builder.py:421 -#: sphinx/htmlhelp.py:155 -#: sphinx/templates/defindex.html:19 -#: sphinx/templates/modindex.html:2 -#: sphinx/templates/modindex.html:13 -msgid "Global Module Index" -msgstr "Indeks modułów" - -#: sphinx/builder.py:421 -msgid "modules" -msgstr "moduły" - -#: sphinx/builder.py:457 -msgid "next" -msgstr "dalej" - -#: sphinx/builder.py:464 -msgid "previous" -msgstr "wstecz" - -#: sphinx/builder.py:1108 -msgid "Builtins" -msgstr "Wbudowane" - -#: sphinx/builder.py:1110 -msgid "Module level" -msgstr "Poziom modułu" - -#: sphinx/environment.py:107 -#: sphinx/latexwriter.py:129 +#: sphinx/environment.py:104 sphinx/writers/latex.py:170 #, python-format msgid "%B %d, %Y" msgstr "%B %d %Y" -#: sphinx/environment.py:270 -#: sphinx/latexwriter.py:190 -#: sphinx/templates/genindex-single.html:2 +#: sphinx/environment.py:300 sphinx/templates/genindex-single.html:2 #: sphinx/templates/genindex-split.html:2 -#: sphinx/templates/genindex-split.html:5 -#: sphinx/templates/genindex.html:2 -#: sphinx/templates/genindex.html:5 -#: sphinx/templates/genindex.html:48 +#: sphinx/templates/genindex-split.html:5 sphinx/templates/genindex.html:2 +#: sphinx/templates/genindex.html:5 sphinx/templates/genindex.html:48 +#: sphinx/templates/layout.html:126 sphinx/writers/latex.py:176 msgid "Index" msgstr "Indeks" -#: sphinx/environment.py:271 -#: sphinx/latexwriter.py:188 +#: sphinx/environment.py:301 sphinx/writers/latex.py:175 msgid "Module Index" msgstr "Indeks modułów" -#: sphinx/environment.py:272 -#: sphinx/templates/defindex.html:16 +#: sphinx/environment.py:302 sphinx/templates/defindex.html:16 msgid "Search Page" msgstr "Wyszukiwanie" -#: sphinx/htmlwriter.py:73 -#: sphinx/static/doctools.js:145 -msgid "Permalink to this definition" -msgstr "Stały odnośnik do tej definicji" - -#: sphinx/htmlwriter.py:375 -#: sphinx/static/doctools.js:139 -msgid "Permalink to this headline" -msgstr "Stały odnośnik do tego nagłówka" - -#: sphinx/latexwriter.py:143 -msgid "Release" -msgstr "Wydanie" - -#: sphinx/roles.py:52 -#: sphinx/directives/desc.py:514 +#: sphinx/roles.py:53 sphinx/directives/desc.py:580 #, python-format msgid "environment variable; %s" msgstr "zmienna środowiskowa; %s" -#: sphinx/roles.py:59 +#: sphinx/roles.py:60 #, python-format msgid "Python Enhancement Proposals!PEP %s" msgstr "Python Enhancement Proposals!PEP %s" -#: sphinx/textwriter.py:151 +#: sphinx/builders/changes.py:64 +msgid "Builtins" +msgstr "Wbudowane" + +#: sphinx/builders/changes.py:66 +msgid "Module level" +msgstr "Poziom modułu" + +#: sphinx/builders/html.py:118 #, python-format -msgid "Platform: %s" -msgstr "Platforma: %s" +msgid "%b %d, %Y" +msgstr "%b %d %Y" -#: sphinx/textwriter.py:353 -msgid "[image]" -msgstr "[obrazek]" +#: sphinx/builders/html.py:137 sphinx/templates/defindex.html:21 +msgid "General Index" +msgstr "Indeks ogólny" -#: sphinx/directives/desc.py:26 +#: sphinx/builders/html.py:137 +msgid "index" +msgstr "indeks" + +#: sphinx/builders/html.py:139 sphinx/builders/htmlhelp.py:182 +#: sphinx/builders/qthelp.py:131 sphinx/templates/defindex.html:19 +#: sphinx/templates/modindex.html:2 sphinx/templates/modindex.html:13 +msgid "Global Module Index" +msgstr "Indeks modułów" + +#: sphinx/builders/html.py:139 +msgid "modules" +msgstr "moduły" + +#: sphinx/builders/html.py:179 +msgid "next" +msgstr "dalej" + +#: sphinx/builders/html.py:186 +msgid "previous" +msgstr "wstecz" + +#: sphinx/builders/latex.py:155 sphinx/builders/pdf.py:162 +msgid " (in " +msgstr "" + +#: sphinx/directives/desc.py:25 #, python-format msgid "%s() (built-in function)" msgstr "%s() (funkcja wbudowana)" -#: sphinx/directives/desc.py:27 -#: sphinx/directives/desc.py:41 -#: sphinx/directives/desc.py:53 +#: sphinx/directives/desc.py:26 sphinx/directives/desc.py:42 +#: sphinx/directives/desc.py:54 #, python-format msgid "%s() (in module %s)" msgstr "%s() (w module %s)" -#: sphinx/directives/desc.py:30 +#: sphinx/directives/desc.py:29 #, python-format msgid "%s (built-in variable)" msgstr "%s (zmienna wbudowana)" -#: sphinx/directives/desc.py:31 -#: sphinx/directives/desc.py:65 +#: sphinx/directives/desc.py:30 sphinx/directives/desc.py:78 #, python-format msgid "%s (in module %s)" msgstr "%s (w module %s)" #: sphinx/directives/desc.py:33 +#, fuzzy, python-format +msgid "%s (built-in class)" +msgstr "%s (zmienna wbudowana)" + +#: sphinx/directives/desc.py:34 #, python-format msgid "%s (class in %s)" msgstr "%s (w klasie %s)" -#: sphinx/directives/desc.py:45 +#: sphinx/directives/desc.py:46 #, python-format msgid "%s() (%s.%s method)" msgstr "%s() (%s.%s metoda)" -#: sphinx/directives/desc.py:47 +#: sphinx/directives/desc.py:48 #, python-format msgid "%s() (%s method)" msgstr "%s() (%s metoda)" -#: sphinx/directives/desc.py:57 +#: sphinx/directives/desc.py:58 #, python-format msgid "%s() (%s.%s static method)" msgstr "%s() (%s.%s statyczna metoda)" -#: sphinx/directives/desc.py:59 +#: sphinx/directives/desc.py:60 #, python-format msgid "%s() (%s static method)" msgstr "%s() (%s statyczna metoda)" -#: sphinx/directives/desc.py:69 +#: sphinx/directives/desc.py:82 #, python-format msgid "%s (%s.%s attribute)" msgstr "%s (%s.%s atrybut)" -#: sphinx/directives/desc.py:71 +#: sphinx/directives/desc.py:84 #, python-format msgid "%s (%s attribute)" msgstr "%s (%s atrybut)" -#: sphinx/directives/desc.py:73 +#: sphinx/directives/desc.py:86 #, python-format msgid "%s (C function)" msgstr "%s (funkcja C)" -#: sphinx/directives/desc.py:75 +#: sphinx/directives/desc.py:88 #, python-format msgid "%s (C member)" msgstr "%s (pole C)" -#: sphinx/directives/desc.py:77 +#: sphinx/directives/desc.py:90 #, python-format msgid "%s (C macro)" msgstr "%s (makro C)" -#: sphinx/directives/desc.py:79 +#: sphinx/directives/desc.py:92 #, python-format msgid "%s (C type)" msgstr "%s (typ C)" -#: sphinx/directives/desc.py:81 +#: sphinx/directives/desc.py:94 #, python-format msgid "%s (C variable)" msgstr "%s (zmienna C)" -#: sphinx/directives/desc.py:99 +#: sphinx/directives/desc.py:112 msgid "Raises" msgstr "Wyrzuca" -#: sphinx/directives/desc.py:103 +#: sphinx/directives/desc.py:116 msgid "Variable" msgstr "Zmienna" -#: sphinx/directives/desc.py:106 +#: sphinx/directives/desc.py:119 msgid "Returns" msgstr "Zwraca" -#: sphinx/directives/desc.py:113 +#: sphinx/directives/desc.py:128 msgid "Return type" msgstr "Typ zwracany" -#: sphinx/directives/desc.py:140 +#: sphinx/directives/desc.py:213 +#, fuzzy +msgid "Parameter" +msgstr "Parametry" + +#: sphinx/directives/desc.py:217 msgid "Parameters" msgstr "Parametry" -#: sphinx/directives/desc.py:402 -#, python-format -msgid "command line option; %s" -msgstr "opcja linii komend; %s" +#: sphinx/directives/desc.py:465 +#, fuzzy, python-format +msgid "%scommand line option; %s" +msgstr "%sopcja linii komend; %s" -#: sphinx/directives/other.py:102 +#: sphinx/directives/other.py:101 msgid "Platforms: " msgstr "Platformy: " -#: sphinx/directives/other.py:107 +#: sphinx/directives/other.py:106 #, python-format msgid "%s (module)" msgstr "%s (moduł)" -#: sphinx/directives/other.py:147 +#: sphinx/directives/other.py:146 msgid "Section author: " msgstr "Autor rozdziału: " -#: sphinx/directives/other.py:149 +#: sphinx/directives/other.py:148 msgid "Module author: " msgstr "Autor modułu: " -#: sphinx/directives/other.py:151 +#: sphinx/directives/other.py:150 msgid "Author: " msgstr "Autor: " -#: sphinx/directives/other.py:233 +#: sphinx/directives/other.py:249 msgid "See also" msgstr "Zobacz także" +#: sphinx/ext/autodoc.py:442 +#, python-format +msgid " Bases: %s" +msgstr "" + +#: sphinx/ext/autodoc.py:566 sphinx/ext/autodoc.py:583 +#, python-format +msgid "alias of :class:`%s`" +msgstr "" + +#: sphinx/ext/todo.py:31 +msgid "Todo" +msgstr "" + +#: sphinx/ext/todo.py:75 +#, python-format +msgid "(The original entry is located in %s, line %d and can be found " +msgstr "" + +#: sphinx/ext/todo.py:81 +msgid "here" +msgstr "" + #: sphinx/locale/__init__.py:15 msgid "Attention" msgstr "Uwaga" @@ -332,6 +335,14 @@ msgstr "instrukcja" msgid "built-in function" msgstr "funkcja wbudowana" +#: sphinx/static/doctools.js:139 sphinx/writers/html.py:425 +msgid "Permalink to this headline" +msgstr "Stały odnośnik do tego nagłówka" + +#: sphinx/static/doctools.js:145 sphinx/writers/html.py:80 +msgid "Permalink to this definition" +msgstr "Stały odnośnik do tej definicji" + #: sphinx/static/doctools.js:174 msgid "Hide Search Matches" msgstr "Ukryj wyniki wyszukiwania" @@ -344,21 +355,28 @@ msgstr "Wyszukiwanie" msgid "Preparing search..." msgstr "Przygotowanie wyszukiwania..." -#: sphinx/static/searchtools.js:401 -#: sphinx/templates/search.html:18 +#: sphinx/static/searchtools.js:338 +#, fuzzy +msgid "module, in " +msgstr "moduł" + +#: sphinx/static/searchtools.js:347 +msgid ", in " +msgstr "" + +#: sphinx/static/searchtools.js:453 sphinx/templates/search.html:25 msgid "Search Results" msgstr "Wyniki wyszukiwania" -#: sphinx/static/searchtools.js:403 +#: sphinx/static/searchtools.js:455 msgid "" "Your search did not match any documents. Please make sure that all words " "are spelled correctly and that you've selected enough categories." msgstr "" -"Nie znaleziono żadnych pasujących dokumentów. Upewnij się, że " -"wszystkie słowa są poprawnie wpisane i że wybrałeś wystarczającą" -"liczbę kategorii." +"Nie znaleziono żadnych pasujących dokumentów. Upewnij się, że wszystkie " +"słowa są poprawnie wpisane i że wybrałeś wystarczającąliczbę kategorii." -#: sphinx/static/searchtools.js:405 +#: sphinx/static/searchtools.js:457 #, python-format msgid "Search finished, found %s page(s) matching the search query." msgstr "Przeszukiwanie zakończone, znaleziono %s pasujących stron." @@ -398,8 +416,7 @@ msgstr "Indeks – %(key)s" #: sphinx/templates/genindex-single.html:44 #: sphinx/templates/genindex-split.html:14 -#: sphinx/templates/genindex-split.html:27 -#: sphinx/templates/genindex.html:54 +#: sphinx/templates/genindex-split.html:27 sphinx/templates/genindex.html:54 msgid "Full index on one page" msgstr "Cały indeks na jednej stronie" @@ -423,28 +440,23 @@ msgstr "Spis treści" msgid "Previous topic" msgstr "Poprzedni temat" -#: sphinx/templates/layout.html:47 +#: sphinx/templates/layout.html:48 msgid "previous chapter" msgstr "poprzedni rozdział" -#: sphinx/templates/layout.html:50 +#: sphinx/templates/layout.html:51 msgid "Next topic" msgstr "Następny temat" -#: sphinx/templates/layout.html:51 +#: sphinx/templates/layout.html:53 msgid "next chapter" msgstr "następny rozdział" -#: sphinx/templates/layout.html:55 +#: sphinx/templates/layout.html:58 msgid "This Page" msgstr "Ta strona" -#: sphinx/templates/layout.html:59 -msgid "Suggest Change" -msgstr "Zasugeruj zmianę" - -#: sphinx/templates/layout.html:60 -#: sphinx/templates/layout.html:62 +#: sphinx/templates/layout.html:61 msgid "Show Source" msgstr "Pokaż źródło" @@ -452,61 +464,49 @@ msgstr "Pokaż źródło" msgid "Quick search" msgstr "Szybkie wyszukiwanie" -#: sphinx/templates/layout.html:71 -msgid "Keyword search" -msgstr "Szukanie wg słowa kluczowego" - -#: sphinx/templates/layout.html:73 +#: sphinx/templates/layout.html:74 msgid "Go" msgstr "Szukaj" #: sphinx/templates/layout.html:78 -msgid "Enter a module, class or function name." +#, fuzzy +msgid "Enter search terms or a module, class or function name." msgstr "Wprowadź nazwę modułu, klasy lub funkcji." -#: sphinx/templates/layout.html:118 +#: sphinx/templates/layout.html:115 #, python-format msgid "Search within %(docstitle)s" msgstr "Szukaj pośród %(docstitle)s" -#: sphinx/templates/layout.html:127 +#: sphinx/templates/layout.html:124 msgid "About these documents" msgstr "O tych dokumentach" -#: sphinx/templates/layout.html:129 -msgid "Global table of contents" -msgstr "Globalny spis treści" - -#: sphinx/templates/layout.html:130 -msgid "Global index" -msgstr "Globalny indeks" - -#: sphinx/templates/layout.html:131 -#: sphinx/templates/search.html:2 +#: sphinx/templates/layout.html:127 sphinx/templates/search.html:2 #: sphinx/templates/search.html:5 msgid "Search" msgstr "Szukaj" -#: sphinx/templates/layout.html:133 +#: sphinx/templates/layout.html:129 msgid "Copyright" msgstr "Copyright" -#: sphinx/templates/layout.html:178 +#: sphinx/templates/layout.html:174 #, python-format msgid "© <a href=\"%(path)s\">Copyright</a> %(copyright)s." msgstr "© <a href=\"%(path)s\">Copyright</a> %(copyright)s." -#: sphinx/templates/layout.html:180 +#: sphinx/templates/layout.html:176 #, python-format msgid "© Copyright %(copyright)s." msgstr "© Copyright %(copyright)s." -#: sphinx/templates/layout.html:183 +#: sphinx/templates/layout.html:179 #, python-format msgid "Last updated on %(last_updated)s." msgstr "Ostatnia modyfikacja %(last_updated)s." -#: sphinx/templates/layout.html:186 +#: sphinx/templates/layout.html:182 #, python-format msgid "" "Created using <a href=\"http://sphinx.pocoo.org/\">Sphinx</a> " @@ -515,15 +515,7 @@ msgstr "" "Utworzone przy pomocy <a href=\"http://sphinx.pocoo.org/\">Sphinx</a>'a " "%(sphinx_version)s." -#: sphinx/templates/modindex.html:15 -msgid "Most popular modules:" -msgstr "Najbardziej popularne moduły:" - -#: sphinx/templates/modindex.html:24 -msgid "Show modules only available on these platforms" -msgstr "Pokaż moduły dostępne tylko na tych platformach" - -#: sphinx/templates/modindex.html:56 +#: sphinx/templates/modindex.html:36 msgid "Deprecated" msgstr "Niezalecane" @@ -532,34 +524,31 @@ msgstr "Niezalecane" msgid "Search %(docstitle)s" msgstr "Przeszukaj %(docstitle)s" -#: sphinx/templates/page.html:8 +#: sphinx/templates/search.html:9 msgid "" -"<strong>Note:</strong> You requested an out-of-date URL from this server." -" We've tried to redirect you to the new location of this page, but it may" -" not be the right one." +"Please activate JavaScript to enable the search\n" +" functionality." msgstr "" -"<strong>Uwaga:</strong> Zażądano przedawnionego URL'a z tego serwera." -" Nastąpiła próba przekierowania do nowej lokalizacji, ale może ona " -"być niewłaściwa." -#: sphinx/templates/search.html:7 +#: sphinx/templates/search.html:14 +#, fuzzy msgid "" "From here you can search these documents. Enter your search\n" " words into the box below and click \"search\". Note that the search\n" " function will automatically search for all of the words. Pages\n" -" containing less words won't appear in the result list." +" containing fewer words won't appear in the result list." msgstr "" "Stąd możesz przeszukać dokumentację. Wprowadź szukane\n" " słowa w poniższym okienku i kliknij \"Szukaj\". Zwróć uwagę, że\n" -" funkcja szukająca będzie automatycznie szukała wszystkich słów. " -" Strony nie zawierające wszystkich słów nie znajdą się na wynikowej " -" liście." +" funkcja szukająca będzie automatycznie szukała wszystkich słów. " +"Strony nie zawierające wszystkich słów nie znajdą się na wynikowej " +"liście." -#: sphinx/templates/search.html:14 +#: sphinx/templates/search.html:21 msgid "search" msgstr "Szukaj" -#: sphinx/templates/search.html:20 +#: sphinx/templates/search.html:27 msgid "Your search did not match any results." msgstr "Nie znaleziono żadnych pasujących stron." @@ -591,3 +580,16 @@ msgstr "Zmiany w C API" msgid "Other changes" msgstr "Inne zmiany" +#: sphinx/writers/latex.py:173 +msgid "Release" +msgstr "Wydanie" + +#: sphinx/writers/text.py:166 +#, python-format +msgid "Platform: %s" +msgstr "Platforma: %s" + +#: sphinx/writers/text.py:427 +msgid "[image]" +msgstr "[obrazek]" + diff --git a/sphinx/locale/pt_BR/LC_MESSAGES/sphinx.js b/sphinx/locale/pt_BR/LC_MESSAGES/sphinx.js new file mode 100644 index 000000000..fb0fc93b3 --- /dev/null +++ b/sphinx/locale/pt_BR/LC_MESSAGES/sphinx.js @@ -0,0 +1 @@ +Documentation.addTranslations({"locale": "pt_BR", "plural_expr": "(n > 1)", "messages": {"module, in ": "m\u00f3dulo, em ", "Preparing search...": "Preparando pesquisa...", "Your search did not match any documents. Please make sure that all words are spelled correctly and that you've selected enough categories.": "Sua pesquisa n\u00e3o encontrou nenhum documento. Por favor assegure-se de que todas as palavras foram digitadas corretamente e de que voc\u00ea tenha selecionado o m\u00ednimo de categorias.", "Search finished, found %s page(s) matching the search query.": "Pesquisa finalizada, foram encontrada(s) %s p\u00e1gina(s) que conferem com o crit\u00e9rio de pesquisa.", ", in ": ", em ", "Permalink to this headline": "Link permanente para este t\u00edtulo", "Searching": "Pesquisando", "Permalink to this definition": "Link permanente para esta defini\u00e7\u00e3o", "Hide Search Matches": "Esconder Resultados da Pesquisa", "Search Results": "Resultados da Pesquisa"}}); \ No newline at end of file diff --git a/sphinx/locale/pt_BR/LC_MESSAGES/sphinx.mo b/sphinx/locale/pt_BR/LC_MESSAGES/sphinx.mo new file mode 100644 index 000000000..7c470e4f7 Binary files /dev/null and b/sphinx/locale/pt_BR/LC_MESSAGES/sphinx.mo differ diff --git a/sphinx/locale/pt_BR/LC_MESSAGES/sphinx.po b/sphinx/locale/pt_BR/LC_MESSAGES/sphinx.po new file mode 100644 index 000000000..48ee96dba --- /dev/null +++ b/sphinx/locale/pt_BR/LC_MESSAGES/sphinx.po @@ -0,0 +1,601 @@ +# Portuguese (Brazil) translations for Sphinx. +# Copyright (C) 2008 ORGANIZATION +# This file is distributed under the same license as the Sphinx project. +# FIRST AUTHOR <roger.demetrescu@gmail.com>, 2008. +# +msgid "" +msgstr "" +"Project-Id-Version: Sphinx 0.5\n" +"Report-Msgid-Bugs-To: roger.demetrescu@gmail.com\n" +"POT-Creation-Date: 2008-11-09 19:46+0100\n" +"PO-Revision-Date: 2009-01-24 18:39+0000\n" +"Last-Translator: Roger Demetrescu <roger.demetrescu@gmail.com>\n" +"Language-Team: pt_BR <roger.demetrescu@gmail.com>\n" +"Plural-Forms: nplurals=2; plural=(n > 1)\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=utf-8\n" +"Content-Transfer-Encoding: 8bit\n" +"Generated-By: Babel 0.9.3\n" + +#: sphinx/environment.py:104 sphinx/writers/latex.py:170 +#, python-format +msgid "%B %d, %Y" +msgstr "%d/%m/%Y" + +#: sphinx/environment.py:300 sphinx/templates/genindex-single.html:2 +#: sphinx/templates/genindex-split.html:2 +#: sphinx/templates/genindex-split.html:5 sphinx/templates/genindex.html:2 +#: sphinx/templates/genindex.html:5 sphinx/templates/genindex.html:48 +#: sphinx/templates/layout.html:126 sphinx/writers/latex.py:176 +msgid "Index" +msgstr "Índice" + +#: sphinx/environment.py:301 sphinx/writers/latex.py:175 +msgid "Module Index" +msgstr "Índice do Módulo" + +#: sphinx/environment.py:302 sphinx/templates/defindex.html:16 +msgid "Search Page" +msgstr "Página de Pesquisa" + +#: sphinx/roles.py:53 sphinx/directives/desc.py:580 +#, python-format +msgid "environment variable; %s" +msgstr "váriavel de ambiente; %s" + +#: sphinx/roles.py:60 +#, python-format +msgid "Python Enhancement Proposals!PEP %s" +msgstr "Python Enhancement Proposals!PEP %s" + +#: sphinx/builders/changes.py:64 +msgid "Builtins" +msgstr "Internos" + +#: sphinx/builders/changes.py:66 +msgid "Module level" +msgstr "Módulo" + +#: sphinx/builders/html.py:118 +#, python-format +msgid "%b %d, %Y" +msgstr "%d/%m/%Y" + +#: sphinx/builders/html.py:137 sphinx/templates/defindex.html:21 +msgid "General Index" +msgstr "Índice Geral" + +#: sphinx/builders/html.py:137 +msgid "index" +msgstr "índice" + +#: sphinx/builders/html.py:139 sphinx/builders/htmlhelp.py:182 +#: sphinx/builders/qthelp.py:131 sphinx/templates/defindex.html:19 +#: sphinx/templates/modindex.html:2 sphinx/templates/modindex.html:13 +msgid "Global Module Index" +msgstr "Índice Global de Módulos" + +#: sphinx/builders/html.py:139 +msgid "modules" +msgstr "módulos" + +#: sphinx/builders/html.py:179 +msgid "next" +msgstr "próximo" + +#: sphinx/builders/html.py:186 +msgid "previous" +msgstr "anterior" + +#: sphinx/builders/latex.py:155 sphinx/builders/pdf.py:162 +msgid " (in " +msgstr " (em " + +#: sphinx/directives/desc.py:25 +#, python-format +msgid "%s() (built-in function)" +msgstr "%s() (função interna)" + +#: sphinx/directives/desc.py:26 sphinx/directives/desc.py:42 +#: sphinx/directives/desc.py:54 +#, python-format +msgid "%s() (in module %s)" +msgstr "%s() (no módulo %s)" + +#: sphinx/directives/desc.py:29 +#, python-format +msgid "%s (built-in variable)" +msgstr "%s (variável interna)" + +#: sphinx/directives/desc.py:30 sphinx/directives/desc.py:78 +#, python-format +msgid "%s (in module %s)" +msgstr "%s (no módulo %s)" + +#: sphinx/directives/desc.py:33 +#, python-format +msgid "%s (built-in class)" +msgstr "%s (classe interna)" + +#: sphinx/directives/desc.py:34 +#, python-format +msgid "%s (class in %s)" +msgstr "%s (classe em %s)" + +#: sphinx/directives/desc.py:46 +#, python-format +msgid "%s() (%s.%s method)" +msgstr "%s() (método %s.%s)" + +#: sphinx/directives/desc.py:48 +#, python-format +msgid "%s() (%s method)" +msgstr "%s() (método %s)" + +#: sphinx/directives/desc.py:58 +#, python-format +msgid "%s() (%s.%s static method)" +msgstr "%s() (método estático %s.%s)" + +#: sphinx/directives/desc.py:60 +#, python-format +msgid "%s() (%s static method)" +msgstr "%s() (método estático %s)" + +#: sphinx/directives/desc.py:82 +#, python-format +msgid "%s (%s.%s attribute)" +msgstr "%s (atributo %s.%s)" + +#: sphinx/directives/desc.py:84 +#, python-format +msgid "%s (%s attribute)" +msgstr "%s (atributo %s)" + +#: sphinx/directives/desc.py:86 +#, python-format +msgid "%s (C function)" +msgstr "%s (função C)" + +#: sphinx/directives/desc.py:88 +#, python-format +msgid "%s (C member)" +msgstr "%s (membro C)" + +#: sphinx/directives/desc.py:90 +#, python-format +msgid "%s (C macro)" +msgstr "%s (macro C)" + +#: sphinx/directives/desc.py:92 +#, python-format +msgid "%s (C type)" +msgstr "%s (tipo C)" + +#: sphinx/directives/desc.py:94 +#, python-format +msgid "%s (C variable)" +msgstr "%s (variável C)" + +#: sphinx/directives/desc.py:112 +msgid "Raises" +msgstr "Levanta" + +#: sphinx/directives/desc.py:116 +msgid "Variable" +msgstr "Variável" + +#: sphinx/directives/desc.py:119 +msgid "Returns" +msgstr "Retorna" + +#: sphinx/directives/desc.py:128 +msgid "Return type" +msgstr "Tipo de retorno" + +#: sphinx/directives/desc.py:213 +#, fuzzy +msgid "Parameter" +msgstr "Parâmetros" + +#: sphinx/directives/desc.py:217 +msgid "Parameters" +msgstr "Parâmetros" + +#: sphinx/directives/desc.py:465 +#, python-format +msgid "%scommand line option; %s" +msgstr "%sopção de linha de comando; %s" + +#: sphinx/directives/other.py:101 +msgid "Platforms: " +msgstr "Plataformas: " + +#: sphinx/directives/other.py:106 +#, python-format +msgid "%s (module)" +msgstr "%s (módulo)" + +#: sphinx/directives/other.py:146 +msgid "Section author: " +msgstr "Autor da seção: " + +#: sphinx/directives/other.py:148 +msgid "Module author: " +msgstr "Autor do módulo: " + +#: sphinx/directives/other.py:150 +msgid "Author: " +msgstr "Autor: " + +#: sphinx/directives/other.py:249 +msgid "See also" +msgstr "Veja também" + +#: sphinx/ext/autodoc.py:442 +#, python-format +msgid " Bases: %s" +msgstr "" + +#: sphinx/ext/autodoc.py:566 sphinx/ext/autodoc.py:583 +#, python-format +msgid "alias of :class:`%s`" +msgstr "" + +#: sphinx/ext/todo.py:31 +msgid "Todo" +msgstr "Por fazer" + +#: sphinx/ext/todo.py:75 +#, python-format +msgid "(The original entry is located in %s, line %d and can be found " +msgstr "(A entrada original está localizada em %s, linha %d e pode ser encontrada " + +#: sphinx/ext/todo.py:81 +msgid "here" +msgstr "aqui" + +#: sphinx/locale/__init__.py:15 +msgid "Attention" +msgstr "Atenção" + +#: sphinx/locale/__init__.py:16 +msgid "Caution" +msgstr "Cuidado" + +#: sphinx/locale/__init__.py:17 +msgid "Danger" +msgstr "Perigo" + +#: sphinx/locale/__init__.py:18 +msgid "Error" +msgstr "Erro" + +#: sphinx/locale/__init__.py:19 +msgid "Hint" +msgstr "Dica" + +#: sphinx/locale/__init__.py:20 +msgid "Important" +msgstr "Importante" + +#: sphinx/locale/__init__.py:21 +msgid "Note" +msgstr "Nota" + +#: sphinx/locale/__init__.py:22 +msgid "See Also" +msgstr "Veja Também" + +#: sphinx/locale/__init__.py:23 +msgid "Tip" +msgstr "Dica" + +#: sphinx/locale/__init__.py:24 +msgid "Warning" +msgstr "Aviso" + +#: sphinx/locale/__init__.py:28 +#, python-format +msgid "New in version %s" +msgstr "Novo na versão %s" + +#: sphinx/locale/__init__.py:29 +#, python-format +msgid "Changed in version %s" +msgstr "Alterado na versão %s" + +#: sphinx/locale/__init__.py:30 +#, python-format +msgid "Deprecated since version %s" +msgstr "Obsoleto desde a versão %s" + +#: sphinx/locale/__init__.py:34 +msgid "module" +msgstr "módulo" + +#: sphinx/locale/__init__.py:35 +msgid "keyword" +msgstr "palavra-chave" + +#: sphinx/locale/__init__.py:36 +msgid "operator" +msgstr "operador" + +#: sphinx/locale/__init__.py:37 +msgid "object" +msgstr "objeto" + +#: sphinx/locale/__init__.py:38 +msgid "exception" +msgstr "exceção" + +#: sphinx/locale/__init__.py:39 +msgid "statement" +msgstr "comando" + +#: sphinx/locale/__init__.py:40 +msgid "built-in function" +msgstr "função interna" + +#: sphinx/static/doctools.js:139 sphinx/writers/html.py:425 +msgid "Permalink to this headline" +msgstr "Link permanente para este título" + +#: sphinx/static/doctools.js:145 sphinx/writers/html.py:80 +msgid "Permalink to this definition" +msgstr "Link permanente para esta definição" + +#: sphinx/static/doctools.js:174 +msgid "Hide Search Matches" +msgstr "Esconder Resultados da Pesquisa" + +#: sphinx/static/searchtools.js:274 +msgid "Searching" +msgstr "Pesquisando" + +#: sphinx/static/searchtools.js:279 +msgid "Preparing search..." +msgstr "Preparando pesquisa..." + +#: sphinx/static/searchtools.js:338 +msgid "module, in " +msgstr "módulo, em " + +#: sphinx/static/searchtools.js:347 +msgid ", in " +msgstr ", em " + +#: sphinx/static/searchtools.js:453 sphinx/templates/search.html:25 +msgid "Search Results" +msgstr "Resultados da Pesquisa" + +#: sphinx/static/searchtools.js:455 +msgid "" +"Your search did not match any documents. Please make sure that all words " +"are spelled correctly and that you've selected enough categories." +msgstr "" +"Sua pesquisa não encontrou nenhum documento. Por favor assegure-se de que" +" todas as palavras foram digitadas corretamente e de que você tenha " +"selecionado o mínimo de categorias." + +#: sphinx/static/searchtools.js:457 +#, python-format +msgid "Search finished, found %s page(s) matching the search query." +msgstr "" +"Pesquisa finalizada, foram encontrada(s) %s página(s) que conferem com o " +"critério de pesquisa." + +#: sphinx/templates/defindex.html:2 +msgid "Overview" +msgstr "Visão geral" + +#: sphinx/templates/defindex.html:11 +msgid "Indices and tables:" +msgstr "Índices e tabelas:" + +#: sphinx/templates/defindex.html:14 +msgid "Complete Table of Contents" +msgstr "Tabela de Conteúdo Completa" + +#: sphinx/templates/defindex.html:15 +msgid "lists all sections and subsections" +msgstr "Lista todas seções e subseções" + +#: sphinx/templates/defindex.html:17 +msgid "search this documentation" +msgstr "Pesquisar esta documentação" + +#: sphinx/templates/defindex.html:20 +msgid "quick access to all modules" +msgstr "acesso rápido para todos os módulos" + +#: sphinx/templates/defindex.html:22 +msgid "all functions, classes, terms" +msgstr "todas funções, classes, termos" + +#: sphinx/templates/genindex-single.html:5 +#, python-format +msgid "Index – %(key)s" +msgstr "Índice – %(key)s" + +#: sphinx/templates/genindex-single.html:44 +#: sphinx/templates/genindex-split.html:14 +#: sphinx/templates/genindex-split.html:27 sphinx/templates/genindex.html:54 +msgid "Full index on one page" +msgstr "Índice completo em uma página" + +#: sphinx/templates/genindex-split.html:7 +msgid "Index pages by letter" +msgstr "Paginas de índice por letra" + +#: sphinx/templates/genindex-split.html:15 +msgid "can be huge" +msgstr "pode ser enorme" + +#: sphinx/templates/layout.html:9 +msgid "Navigation" +msgstr "Navegação" + +#: sphinx/templates/layout.html:40 +msgid "Table Of Contents" +msgstr "Tabela de Conteúdo" + +#: sphinx/templates/layout.html:46 +msgid "Previous topic" +msgstr "Tópico anterior" + +#: sphinx/templates/layout.html:48 +msgid "previous chapter" +msgstr "capítulo anterior" + +#: sphinx/templates/layout.html:51 +msgid "Next topic" +msgstr "Próximo tópico" + +#: sphinx/templates/layout.html:53 +msgid "next chapter" +msgstr "próximo capítulo" + +#: sphinx/templates/layout.html:58 +msgid "This Page" +msgstr "Esta Página" + +#: sphinx/templates/layout.html:61 +msgid "Show Source" +msgstr "Exibir Fonte" + +#: sphinx/templates/layout.html:71 +msgid "Quick search" +msgstr "Pesquisa rápida" + +#: sphinx/templates/layout.html:74 +msgid "Go" +msgstr "Ir" + +#: sphinx/templates/layout.html:78 +#, fuzzy +msgid "Enter search terms or a module, class or function name." +msgstr "Informe o nome de um módulo, classe ou função." + +#: sphinx/templates/layout.html:115 +#, python-format +msgid "Search within %(docstitle)s" +msgstr "Pesquisar dentro de %(docstitle)s" + +#: sphinx/templates/layout.html:124 +msgid "About these documents" +msgstr "Sobre estes documentos" + +#: sphinx/templates/layout.html:127 sphinx/templates/search.html:2 +#: sphinx/templates/search.html:5 +msgid "Search" +msgstr "Pesquisar" + +#: sphinx/templates/layout.html:129 +msgid "Copyright" +msgstr "Copyright" + +#: sphinx/templates/layout.html:174 +#, python-format +msgid "© <a href=\"%(path)s\">Copyright</a> %(copyright)s." +msgstr "© <a href=\"%(path)s\">Copyright</a> %(copyright)s." + +#: sphinx/templates/layout.html:176 +#, python-format +msgid "© Copyright %(copyright)s." +msgstr "© Copyright %(copyright)s." + +#: sphinx/templates/layout.html:179 +#, python-format +msgid "Last updated on %(last_updated)s." +msgstr "Última atualização em %(last_updated)s." + +#: sphinx/templates/layout.html:182 +#, python-format +msgid "" +"Created using <a href=\"http://sphinx.pocoo.org/\">Sphinx</a> " +"%(sphinx_version)s." +msgstr "" +"Criado com <a href=\"http://sphinx.pocoo.org/\">Sphinx</a> " +"%(sphinx_version)s." + +#: sphinx/templates/modindex.html:36 +msgid "Deprecated" +msgstr "Obsoleto" + +#: sphinx/templates/opensearch.xml:4 +#, python-format +msgid "Search %(docstitle)s" +msgstr "Pesquisar em %(docstitle)s" + +#: sphinx/templates/search.html:9 +msgid "" +"Please activate JavaScript to enable the search\n" +" functionality." +msgstr "" + +#: sphinx/templates/search.html:14 +#, fuzzy +msgid "" +"From here you can search these documents. Enter your search\n" +" words into the box below and click \"search\". Note that the search\n" +" function will automatically search for all of the words. Pages\n" +" containing fewer words won't appear in the result list." +msgstr "" +"A partir daqui você pode pesquisar estes documentos. Preencha suas \n" +" palavras de pesquisa na caixa abaixo e clique em \"pesquisar\". " +"Observe que a função de pesquisa\n" +" irá pesquisar automaticamente por todas as palavras.\n" +" Páginas contendo menos palavras não irão aparecer na lista de " +"resultado." + +#: sphinx/templates/search.html:21 +msgid "search" +msgstr "pesquisar" + +#: sphinx/templates/search.html:27 +msgid "Your search did not match any results." +msgstr "Sua pesquisa não encontrou nenhum resultado." + +#: sphinx/templates/changes/frameset.html:5 +#: sphinx/templates/changes/versionchanges.html:12 +#, python-format +msgid "Changes in Version %(version)s — %(docstitle)s" +msgstr "Alterações na Versão%(version)s — %(docstitle)s" + +#: sphinx/templates/changes/rstsource.html:5 +#, python-format +msgid "%(filename)s — %(docstitle)s" +msgstr "%(filename)s — %(docstitle)s" + +#: sphinx/templates/changes/versionchanges.html:17 +#, python-format +msgid "Automatically generated list of changes in version %(version)s" +msgstr "Lista de alterações na versão %(version)s gerada automaticamente" + +#: sphinx/templates/changes/versionchanges.html:18 +msgid "Library changes" +msgstr "Alterações na biblioteca" + +#: sphinx/templates/changes/versionchanges.html:23 +msgid "C API changes" +msgstr "Alterações na API C" + +#: sphinx/templates/changes/versionchanges.html:25 +msgid "Other changes" +msgstr "Outras alterações" + +#: sphinx/writers/latex.py:173 +msgid "Release" +msgstr "Versão" + +#: sphinx/writers/text.py:166 +#, python-format +msgid "Platform: %s" +msgstr "Plataforma: %s" + +#: sphinx/writers/text.py:427 +msgid "[image]" +msgstr "[imagem]" + diff --git a/sphinx/locale/sl/LC_MESSAGES/sphinx.js b/sphinx/locale/sl/LC_MESSAGES/sphinx.js new file mode 100644 index 000000000..e00eb23b7 --- /dev/null +++ b/sphinx/locale/sl/LC_MESSAGES/sphinx.js @@ -0,0 +1 @@ +Documentation.addTranslations({"locale": "sl", "plural_expr": "0", "messages": {"module, in ": "modul, v ", "Preparing search...": "Pripravljam iskanje...", "Your search did not match any documents. Please make sure that all words are spelled correctly and that you've selected enough categories.": "Za va\u0161e iskanje ni rezultatov. Prosimo preglejte ali so vse besede pravilno \u010drkovane in ali ste izbrali dovolj kategorij.", "Search finished, found %s page(s) matching the search query.": "Iskanje kon\u010dano, najdeno %s strani, ki ustrezajo iskalnemu nizu.", ", in ": ", v ", "Permalink to this headline": "Povezava na naslov", "Searching": "I\u0161\u010dem", "Permalink to this definition": "Povezava na to definicijo", "Hide Search Matches": "Skrij Resultate Iskanja", "Search Results": "Rezultati Iskanja"}}); \ No newline at end of file diff --git a/sphinx/locale/sl/LC_MESSAGES/sphinx.mo b/sphinx/locale/sl/LC_MESSAGES/sphinx.mo new file mode 100644 index 000000000..e8cc5a6e8 Binary files /dev/null and b/sphinx/locale/sl/LC_MESSAGES/sphinx.mo differ diff --git a/sphinx/locale/sl/LC_MESSAGES/sphinx.po b/sphinx/locale/sl/LC_MESSAGES/sphinx.po new file mode 100644 index 000000000..f980ee1bc --- /dev/null +++ b/sphinx/locale/sl/LC_MESSAGES/sphinx.po @@ -0,0 +1,592 @@ + +msgid "" +msgstr "" +"Project-Id-Version: Sphinx\n" +"Report-Msgid-Bugs-To: EMAIL@ADDRESS\n" +"POT-Creation-Date: 2008-09-11 23:58+0200\n" +"PO-Revision-Date: 2009-01-24 18:39+0000\n" +"Last-Translator: Rok Garbas <rok.garbas@gmail.com>\n" +"Language-Team: Rok Garbas <rok.garbas@gmail.com>\n" +"Plural-Forms: nplurals=1; plural=0\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=utf-8\n" +"Content-Transfer-Encoding: 8bit\n" +"Generated-By: Babel 0.9.3\n" + +#: sphinx/environment.py:104 sphinx/writers/latex.py:170 +#, python-format +msgid "%B %d, %Y" +msgstr "%d %B, %Y" + +#: sphinx/environment.py:300 sphinx/templates/genindex-single.html:2 +#: sphinx/templates/genindex-split.html:2 +#: sphinx/templates/genindex-split.html:5 sphinx/templates/genindex.html:2 +#: sphinx/templates/genindex.html:5 sphinx/templates/genindex.html:48 +#: sphinx/templates/layout.html:126 sphinx/writers/latex.py:176 +msgid "Index" +msgstr "Abecedni seznam" + +#: sphinx/environment.py:301 sphinx/writers/latex.py:175 +msgid "Module Index" +msgstr "Seznam modulov" + +#: sphinx/environment.py:302 sphinx/templates/defindex.html:16 +msgid "Search Page" +msgstr "Iskalna stran" + +#: sphinx/roles.py:53 sphinx/directives/desc.py:580 +#, python-format +msgid "environment variable; %s" +msgstr "globalna spremenljivka; %s" + +#: sphinx/roles.py:60 +#, python-format +msgid "Python Enhancement Proposals!PEP %s" +msgstr "Python Enhancement Proposals!PEP %s" + +#: sphinx/builders/changes.py:64 +msgid "Builtins" +msgstr "Vgrajeni deli" + +#: sphinx/builders/changes.py:66 +msgid "Module level" +msgstr "Nivo modula" + +#: sphinx/builders/html.py:118 +#, python-format +msgid "%b %d, %Y" +msgstr "%d %b, %Y" + +#: sphinx/builders/html.py:137 sphinx/templates/defindex.html:21 +msgid "General Index" +msgstr "Splošni abecedni seznam" + +#: sphinx/builders/html.py:137 +msgid "index" +msgstr "abecedni seznam" + +#: sphinx/builders/html.py:139 sphinx/builders/htmlhelp.py:182 +#: sphinx/builders/qthelp.py:131 sphinx/templates/defindex.html:19 +#: sphinx/templates/modindex.html:2 sphinx/templates/modindex.html:13 +msgid "Global Module Index" +msgstr "Splošen Seznam Modulov" + +#: sphinx/builders/html.py:139 +msgid "modules" +msgstr "Moduli" + +#: sphinx/builders/html.py:179 +msgid "next" +msgstr "naprej" + +#: sphinx/builders/html.py:186 +msgid "previous" +msgstr "nazaj" + +#: sphinx/builders/latex.py:155 sphinx/builders/pdf.py:162 +msgid " (in " +msgstr "(v " + +#: sphinx/directives/desc.py:25 +#, python-format +msgid "%s() (built-in function)" +msgstr "%s() (vgrajene funkcije)" + +#: sphinx/directives/desc.py:26 sphinx/directives/desc.py:42 +#: sphinx/directives/desc.py:54 +#, python-format +msgid "%s() (in module %s)" +msgstr "%s() (v modulu %s)" + +#: sphinx/directives/desc.py:29 +#, python-format +msgid "%s (built-in variable)" +msgstr "%s (vgrajene spremenljivke)" + +#: sphinx/directives/desc.py:30 sphinx/directives/desc.py:78 +#, python-format +msgid "%s (in module %s)" +msgstr "%s (v modulu %s)" + +#: sphinx/directives/desc.py:33 +#, python-format +msgid "%s (built-in class)" +msgstr "%s (vgrajen razred)" + +#: sphinx/directives/desc.py:34 +#, python-format +msgid "%s (class in %s)" +msgstr "%s (razred v %s)" + +#: sphinx/directives/desc.py:46 +#, python-format +msgid "%s() (%s.%s method)" +msgstr "%s() (%s.%s metoda)" + +#: sphinx/directives/desc.py:48 +#, python-format +msgid "%s() (%s method)" +msgstr "%s() (%s metoda)" + +#: sphinx/directives/desc.py:58 +#, python-format +msgid "%s() (%s.%s static method)" +msgstr "%s() (%s.%s statična metoda)" + +#: sphinx/directives/desc.py:60 +#, python-format +msgid "%s() (%s static method)" +msgstr "%s() (%s statična metoda)" + +#: sphinx/directives/desc.py:82 +#, python-format +msgid "%s (%s.%s attribute)" +msgstr "%s (%s.%s atribut)" + +#: sphinx/directives/desc.py:84 +#, python-format +msgid "%s (%s attribute)" +msgstr "%s (%s atribut)" + +#: sphinx/directives/desc.py:86 +#, python-format +msgid "%s (C function)" +msgstr "%s (C funkcija)" + +#: sphinx/directives/desc.py:88 +#, python-format +msgid "%s (C member)" +msgstr "%s (C član)" + +#: sphinx/directives/desc.py:90 +#, python-format +msgid "%s (C macro)" +msgstr "%s (C makro)" + +#: sphinx/directives/desc.py:92 +#, python-format +msgid "%s (C type)" +msgstr "%s (C tip)" + +#: sphinx/directives/desc.py:94 +#, python-format +msgid "%s (C variable)" +msgstr "%s (C spremenljivka)" + +#: sphinx/directives/desc.py:112 +msgid "Raises" +msgstr "Javi" + +#: sphinx/directives/desc.py:116 +msgid "Variable" +msgstr "Spremenljivka" + +#: sphinx/directives/desc.py:119 +msgid "Returns" +msgstr "Vrne" + +#: sphinx/directives/desc.py:128 +msgid "Return type" +msgstr "Vrne tip" + +#: sphinx/directives/desc.py:213 +#, fuzzy +msgid "Parameter" +msgstr "Parametri" + +#: sphinx/directives/desc.py:217 +msgid "Parameters" +msgstr "Parametri" + +#: sphinx/directives/desc.py:465 +#, python-format +msgid "%scommand line option; %s" +msgstr "%sopcija komandne linije; %s" + +#: sphinx/directives/other.py:101 +msgid "Platforms: " +msgstr "Platforma:" + +#: sphinx/directives/other.py:106 +#, python-format +msgid "%s (module)" +msgstr "%s (modul)" + +#: sphinx/directives/other.py:146 +msgid "Section author: " +msgstr "Avtor sekcije:" + +#: sphinx/directives/other.py:148 +msgid "Module author: " +msgstr "Avtor modula:" + +#: sphinx/directives/other.py:150 +msgid "Author: " +msgstr "Avtor:" + +#: sphinx/directives/other.py:249 +msgid "See also" +msgstr "Poglej tudi" + +#: sphinx/ext/autodoc.py:442 +#, python-format +msgid " Bases: %s" +msgstr "" + +#: sphinx/ext/autodoc.py:566 sphinx/ext/autodoc.py:583 +#, python-format +msgid "alias of :class:`%s`" +msgstr "" + +#: sphinx/ext/todo.py:31 +msgid "Todo" +msgstr "Naredi" + +#: sphinx/ext/todo.py:75 +#, python-format +msgid "(The original entry is located in %s, line %d and can be found " +msgstr "(Originalen vnos se nahajana v %s, vrstica %d in jo je moč poiskati " + +#: sphinx/ext/todo.py:81 +msgid "here" +msgstr "tukaj" + +#: sphinx/locale/__init__.py:15 +msgid "Attention" +msgstr "Pozor" + +#: sphinx/locale/__init__.py:16 +msgid "Caution" +msgstr "Previdno" + +#: sphinx/locale/__init__.py:17 +msgid "Danger" +msgstr "Navarno" + +#: sphinx/locale/__init__.py:18 +msgid "Error" +msgstr "Napaka" + +#: sphinx/locale/__init__.py:19 +msgid "Hint" +msgstr "Nasvet" + +#: sphinx/locale/__init__.py:20 +msgid "Important" +msgstr "Pomembno" + +#: sphinx/locale/__init__.py:21 +msgid "Note" +msgstr "Opomba" + +#: sphinx/locale/__init__.py:22 +msgid "See Also" +msgstr "Poglej Tudi" + +#: sphinx/locale/__init__.py:23 +msgid "Tip" +msgstr "Nasvet" + +#: sphinx/locale/__init__.py:24 +msgid "Warning" +msgstr "Opozorilo" + +#: sphinx/locale/__init__.py:28 +#, python-format +msgid "New in version %s" +msgstr "Novo v verziji %s" + +#: sphinx/locale/__init__.py:29 +#, python-format +msgid "Changed in version %s" +msgstr "Spemenjeno v verziji %s" + +#: sphinx/locale/__init__.py:30 +#, python-format +msgid "Deprecated since version %s" +msgstr "Zastarelo od verzije %s" + +#: sphinx/locale/__init__.py:34 +msgid "module" +msgstr "modul" + +#: sphinx/locale/__init__.py:35 +msgid "keyword" +msgstr "kllučna beseda" + +#: sphinx/locale/__init__.py:36 +msgid "operator" +msgstr "operator" + +#: sphinx/locale/__init__.py:37 +msgid "object" +msgstr "objekt" + +#: sphinx/locale/__init__.py:38 +msgid "exception" +msgstr "izjema" + +#: sphinx/locale/__init__.py:39 +msgid "statement" +msgstr "izjava" + +#: sphinx/locale/__init__.py:40 +msgid "built-in function" +msgstr "vgrajene funkcije" + +#: sphinx/static/doctools.js:139 sphinx/writers/html.py:425 +msgid "Permalink to this headline" +msgstr "Povezava na naslov" + +#: sphinx/static/doctools.js:145 sphinx/writers/html.py:80 +msgid "Permalink to this definition" +msgstr "Povezava na to definicijo" + +#: sphinx/static/doctools.js:174 +msgid "Hide Search Matches" +msgstr "Skrij Resultate Iskanja" + +#: sphinx/static/searchtools.js:274 +msgid "Searching" +msgstr "Iščem" + +#: sphinx/static/searchtools.js:279 +msgid "Preparing search..." +msgstr "Pripravljam iskanje..." + +#: sphinx/static/searchtools.js:338 +msgid "module, in " +msgstr "modul, v " + +#: sphinx/static/searchtools.js:347 +msgid ", in " +msgstr ", v " + +#: sphinx/static/searchtools.js:453 sphinx/templates/search.html:25 +msgid "Search Results" +msgstr "Rezultati Iskanja" + +#: sphinx/static/searchtools.js:455 +msgid "" +"Your search did not match any documents. Please make sure that all words " +"are spelled correctly and that you've selected enough categories." +msgstr "" +"Za vaše iskanje ni rezultatov. Prosimo preglejte ali so vse besede " +"pravilno črkovane in ali ste izbrali dovolj kategorij." + +#: sphinx/static/searchtools.js:457 +#, python-format +msgid "Search finished, found %s page(s) matching the search query." +msgstr "Iskanje končano, najdeno %s strani, ki ustrezajo iskalnemu nizu." + +#: sphinx/templates/defindex.html:2 +msgid "Overview" +msgstr "Pregled" + +#: sphinx/templates/defindex.html:11 +msgid "Indices and tables:" +msgstr "Kazalo in tabele:" + +#: sphinx/templates/defindex.html:14 +msgid "Complete Table of Contents" +msgstr "Popoln Seznam Vsebine" + +#: sphinx/templates/defindex.html:15 +msgid "lists all sections and subsections" +msgstr "prikazi vse sekcije in podsekcije" + +#: sphinx/templates/defindex.html:17 +msgid "search this documentation" +msgstr "isči po dokumentaciji" + +#: sphinx/templates/defindex.html:20 +msgid "quick access to all modules" +msgstr "hiter dostop do vseh modulov" + +#: sphinx/templates/defindex.html:22 +msgid "all functions, classes, terms" +msgstr "vse funkcije, rezredi, termini" + +#: sphinx/templates/genindex-single.html:5 +#, python-format +msgid "Index – %(key)s" +msgstr "Seznam – %(key)s" + +#: sphinx/templates/genindex-single.html:44 +#: sphinx/templates/genindex-split.html:14 +#: sphinx/templates/genindex-split.html:27 sphinx/templates/genindex.html:54 +msgid "Full index on one page" +msgstr "Poln indeks na eni strani" + +#: sphinx/templates/genindex-split.html:7 +msgid "Index pages by letter" +msgstr "Indeksiraj strani po črki" + +#: sphinx/templates/genindex-split.html:15 +msgid "can be huge" +msgstr "lahko je veliko" + +#: sphinx/templates/layout.html:9 +msgid "Navigation" +msgstr "Navigacija" + +#: sphinx/templates/layout.html:40 +msgid "Table Of Contents" +msgstr "Seznam Vsebine" + +#: sphinx/templates/layout.html:46 +msgid "Previous topic" +msgstr "Prejšnja tema" + +#: sphinx/templates/layout.html:48 +msgid "previous chapter" +msgstr "prejšnje poglavje" + +#: sphinx/templates/layout.html:51 +msgid "Next topic" +msgstr "Naslednja tema" + +#: sphinx/templates/layout.html:53 +msgid "next chapter" +msgstr "naslednje poglavje" + +#: sphinx/templates/layout.html:58 +msgid "This Page" +msgstr "Ta stran" + +#: sphinx/templates/layout.html:61 +msgid "Show Source" +msgstr "Prikaži izvorno kodo" + +#: sphinx/templates/layout.html:71 +msgid "Quick search" +msgstr "Hitro iskanje" + +#: sphinx/templates/layout.html:74 +msgid "Go" +msgstr "Potrdi" + +#: sphinx/templates/layout.html:78 +#, fuzzy +msgid "Enter search terms or a module, class or function name." +msgstr "Vnesi ime mudla, razreda ali funkcije." + +#: sphinx/templates/layout.html:115 +#, python-format +msgid "Search within %(docstitle)s" +msgstr "Išči med %(docstitle)s" + +#: sphinx/templates/layout.html:124 +msgid "About these documents" +msgstr "O teh dokumentih" + +#: sphinx/templates/layout.html:127 sphinx/templates/search.html:2 +#: sphinx/templates/search.html:5 +msgid "Search" +msgstr "Išči" + +#: sphinx/templates/layout.html:129 +msgid "Copyright" +msgstr "Vse pravice pridržane" + +#: sphinx/templates/layout.html:174 +#, python-format +msgid "© <a href=\"%(path)s\">Copyright</a> %(copyright)s." +msgstr "© <a href=\"%(path)s\">Vse pravice pridržane</a> %(copyright)s." + +#: sphinx/templates/layout.html:176 +#, python-format +msgid "© Copyright %(copyright)s." +msgstr "© Vse pravice pridržane %(copyright)s." + +#: sphinx/templates/layout.html:179 +#, python-format +msgid "Last updated on %(last_updated)s." +msgstr "Zadnjič posodobljeno na %(last_updated)s." + +#: sphinx/templates/layout.html:182 +#, python-format +msgid "" +"Created using <a href=\"http://sphinx.pocoo.org/\">Sphinx</a> " +"%(sphinx_version)s." +msgstr "" +"Narejeno s <a href=\"http://sphinx.pocoo.org/\">Sphinx</a> " +"%(sphinx_version)s." + +#: sphinx/templates/modindex.html:36 +msgid "Deprecated" +msgstr "Zastarelo" + +#: sphinx/templates/opensearch.xml:4 +#, python-format +msgid "Search %(docstitle)s" +msgstr "Išči %(docstitle)s" + +#: sphinx/templates/search.html:9 +msgid "" +"Please activate JavaScript to enable the search\n" +" functionality." +msgstr "" + +#: sphinx/templates/search.html:14 +#, fuzzy +msgid "" +"From here you can search these documents. Enter your search\n" +" words into the box below and click \"search\". Note that the search\n" +" function will automatically search for all of the words. Pages\n" +" containing fewer words won't appear in the result list." +msgstr "" +"O tukaj lahko isčete dokumente. Vnesite iskalni\n" +" niz v polje spodaj in pritisnite \"išči\". Sproženo iskanje\n" +" bo iskalo po vseh besedah v iskalnem nizu. Strani, ki ne\n" +" vsebujejo vseh besed ne bodo prikazane na seznamu rezultatov." + +#: sphinx/templates/search.html:21 +msgid "search" +msgstr "išči" + +#: sphinx/templates/search.html:27 +msgid "Your search did not match any results." +msgstr "Vaše iskanje ni imelo nobenega zadetka." + +#: sphinx/templates/changes/frameset.html:5 +#: sphinx/templates/changes/versionchanges.html:12 +#, python-format +msgid "Changes in Version %(version)s — %(docstitle)s" +msgstr "Spremembe v Verziji %(version)s — %(docstitle)s" + +#: sphinx/templates/changes/rstsource.html:5 +#, python-format +msgid "%(filename)s — %(docstitle)s" +msgstr "%(filename)s — %(docstitle)s" + +#: sphinx/templates/changes/versionchanges.html:17 +#, python-format +msgid "Automatically generated list of changes in version %(version)s" +msgstr "Avtomatsko generiran seznam sprememb v verziji %(version)s" + +#: sphinx/templates/changes/versionchanges.html:18 +msgid "Library changes" +msgstr "Spremembe knjižnice" + +#: sphinx/templates/changes/versionchanges.html:23 +msgid "C API changes" +msgstr "C API spremembe" + +#: sphinx/templates/changes/versionchanges.html:25 +msgid "Other changes" +msgstr "Ostale spremembe" + +#: sphinx/writers/latex.py:173 +msgid "Release" +msgstr "Izdaja" + +#: sphinx/writers/text.py:166 +#, python-format +msgid "Platform: %s" +msgstr "Platforma: %s" + +#: sphinx/writers/text.py:427 +msgid "[image]" +msgstr "[slika]" + diff --git a/sphinx/locale/sphinx.pot b/sphinx/locale/sphinx.pot index a36000a14..657f5df16 100644 --- a/sphinx/locale/sphinx.pot +++ b/sphinx/locale/sphinx.pot @@ -1,14 +1,14 @@ # Translations template for Sphinx. -# Copyright (C) 2008 ORGANIZATION +# Copyright (C) 2009 ORGANIZATION # This file is distributed under the same license as the Sphinx project. -# FIRST AUTHOR <EMAIL@ADDRESS>, 2008. +# FIRST AUTHOR <EMAIL@ADDRESS>, 2009. # #, fuzzy msgid "" msgstr "" -"Project-Id-Version: Sphinx 0.5\n" +"Project-Id-Version: Sphinx 0.6\n" "Report-Msgid-Bugs-To: EMAIL@ADDRESS\n" -"POT-Creation-Date: 2008-09-11 23:58+0200\n" +"POT-Creation-Date: 2009-01-24 18:39+0000\n" "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" "Last-Translator: FULL NAME <EMAIL@ADDRESS>\n" "Language-Team: LANGUAGE <LL@li.org>\n" @@ -17,228 +17,243 @@ msgstr "" "Content-Transfer-Encoding: 8bit\n" "Generated-By: Babel 0.9.3\n" -#: sphinx/builder.py:400 -#, python-format -msgid "%b %d, %Y" -msgstr "" - -#: sphinx/builder.py:419 sphinx/templates/defindex.html:21 -msgid "General Index" -msgstr "" - -#: sphinx/builder.py:419 -msgid "index" -msgstr "" - -#: sphinx/builder.py:421 sphinx/htmlhelp.py:155 -#: sphinx/templates/defindex.html:19 sphinx/templates/modindex.html:2 -#: sphinx/templates/modindex.html:13 -msgid "Global Module Index" -msgstr "" - -#: sphinx/builder.py:421 -msgid "modules" -msgstr "" - -#: sphinx/builder.py:457 -msgid "next" -msgstr "" - -#: sphinx/builder.py:464 -msgid "previous" -msgstr "" - -#: sphinx/builder.py:1108 -msgid "Builtins" -msgstr "" - -#: sphinx/builder.py:1110 -msgid "Module level" -msgstr "" - -#: sphinx/environment.py:107 sphinx/latexwriter.py:129 +#: sphinx/environment.py:104 sphinx/writers/latex.py:170 #, python-format msgid "%B %d, %Y" msgstr "" -#: sphinx/environment.py:270 sphinx/latexwriter.py:190 -#: sphinx/templates/genindex-single.html:2 +#: sphinx/environment.py:300 sphinx/templates/genindex-single.html:2 #: sphinx/templates/genindex-split.html:2 #: sphinx/templates/genindex-split.html:5 sphinx/templates/genindex.html:2 #: sphinx/templates/genindex.html:5 sphinx/templates/genindex.html:48 +#: sphinx/templates/layout.html:126 sphinx/writers/latex.py:176 msgid "Index" msgstr "" -#: sphinx/environment.py:271 sphinx/latexwriter.py:188 +#: sphinx/environment.py:301 sphinx/writers/latex.py:175 msgid "Module Index" msgstr "" -#: sphinx/environment.py:272 sphinx/templates/defindex.html:16 +#: sphinx/environment.py:302 sphinx/templates/defindex.html:16 msgid "Search Page" msgstr "" -#: sphinx/htmlwriter.py:73 sphinx/static/doctools.js:145 -msgid "Permalink to this definition" -msgstr "" - -#: sphinx/htmlwriter.py:375 sphinx/static/doctools.js:139 -msgid "Permalink to this headline" -msgstr "" - -#: sphinx/latexwriter.py:143 -msgid "Release" -msgstr "" - -#: sphinx/roles.py:52 sphinx/directives/desc.py:514 +#: sphinx/roles.py:53 sphinx/directives/desc.py:580 #, python-format msgid "environment variable; %s" msgstr "" -#: sphinx/roles.py:59 +#: sphinx/roles.py:60 #, python-format msgid "Python Enhancement Proposals!PEP %s" msgstr "" -#: sphinx/textwriter.py:151 +#: sphinx/builders/changes.py:64 +msgid "Builtins" +msgstr "" + +#: sphinx/builders/changes.py:66 +msgid "Module level" +msgstr "" + +#: sphinx/builders/html.py:118 #, python-format -msgid "Platform: %s" +msgid "%b %d, %Y" msgstr "" -#: sphinx/textwriter.py:353 -msgid "[image]" +#: sphinx/builders/html.py:137 sphinx/templates/defindex.html:21 +msgid "General Index" msgstr "" -#: sphinx/directives/desc.py:26 +#: sphinx/builders/html.py:137 +msgid "index" +msgstr "" + +#: sphinx/builders/html.py:139 sphinx/builders/htmlhelp.py:182 +#: sphinx/builders/qthelp.py:131 sphinx/templates/defindex.html:19 +#: sphinx/templates/modindex.html:2 sphinx/templates/modindex.html:13 +msgid "Global Module Index" +msgstr "" + +#: sphinx/builders/html.py:139 +msgid "modules" +msgstr "" + +#: sphinx/builders/html.py:179 +msgid "next" +msgstr "" + +#: sphinx/builders/html.py:186 +msgid "previous" +msgstr "" + +#: sphinx/builders/latex.py:155 sphinx/builders/pdf.py:162 +msgid " (in " +msgstr "" + +#: sphinx/directives/desc.py:25 #, python-format msgid "%s() (built-in function)" msgstr "" -#: sphinx/directives/desc.py:27 sphinx/directives/desc.py:41 -#: sphinx/directives/desc.py:53 +#: sphinx/directives/desc.py:26 sphinx/directives/desc.py:42 +#: sphinx/directives/desc.py:54 #, python-format msgid "%s() (in module %s)" msgstr "" -#: sphinx/directives/desc.py:30 +#: sphinx/directives/desc.py:29 #, python-format msgid "%s (built-in variable)" msgstr "" -#: sphinx/directives/desc.py:31 sphinx/directives/desc.py:65 +#: sphinx/directives/desc.py:30 sphinx/directives/desc.py:78 #, python-format msgid "%s (in module %s)" msgstr "" #: sphinx/directives/desc.py:33 #, python-format +msgid "%s (built-in class)" +msgstr "" + +#: sphinx/directives/desc.py:34 +#, python-format msgid "%s (class in %s)" msgstr "" -#: sphinx/directives/desc.py:45 +#: sphinx/directives/desc.py:46 #, python-format msgid "%s() (%s.%s method)" msgstr "" -#: sphinx/directives/desc.py:47 +#: sphinx/directives/desc.py:48 #, python-format msgid "%s() (%s method)" msgstr "" -#: sphinx/directives/desc.py:57 +#: sphinx/directives/desc.py:58 #, python-format msgid "%s() (%s.%s static method)" msgstr "" -#: sphinx/directives/desc.py:59 +#: sphinx/directives/desc.py:60 #, python-format msgid "%s() (%s static method)" msgstr "" -#: sphinx/directives/desc.py:69 +#: sphinx/directives/desc.py:82 #, python-format msgid "%s (%s.%s attribute)" msgstr "" -#: sphinx/directives/desc.py:71 +#: sphinx/directives/desc.py:84 #, python-format msgid "%s (%s attribute)" msgstr "" -#: sphinx/directives/desc.py:73 +#: sphinx/directives/desc.py:86 #, python-format msgid "%s (C function)" msgstr "" -#: sphinx/directives/desc.py:75 +#: sphinx/directives/desc.py:88 #, python-format msgid "%s (C member)" msgstr "" -#: sphinx/directives/desc.py:77 +#: sphinx/directives/desc.py:90 #, python-format msgid "%s (C macro)" msgstr "" -#: sphinx/directives/desc.py:79 +#: sphinx/directives/desc.py:92 #, python-format msgid "%s (C type)" msgstr "" -#: sphinx/directives/desc.py:81 +#: sphinx/directives/desc.py:94 #, python-format msgid "%s (C variable)" msgstr "" -#: sphinx/directives/desc.py:99 +#: sphinx/directives/desc.py:112 msgid "Raises" msgstr "" -#: sphinx/directives/desc.py:103 +#: sphinx/directives/desc.py:116 msgid "Variable" msgstr "" -#: sphinx/directives/desc.py:106 +#: sphinx/directives/desc.py:119 msgid "Returns" msgstr "" -#: sphinx/directives/desc.py:113 +#: sphinx/directives/desc.py:128 msgid "Return type" msgstr "" -#: sphinx/directives/desc.py:140 +#: sphinx/directives/desc.py:213 +msgid "Parameter" +msgstr "" + +#: sphinx/directives/desc.py:217 msgid "Parameters" msgstr "" -#: sphinx/directives/desc.py:402 +#: sphinx/directives/desc.py:465 #, python-format -msgid "command line option; %s" +msgid "%scommand line option; %s" msgstr "" -#: sphinx/directives/other.py:102 +#: sphinx/directives/other.py:101 msgid "Platforms: " msgstr "" -#: sphinx/directives/other.py:107 +#: sphinx/directives/other.py:106 #, python-format msgid "%s (module)" msgstr "" -#: sphinx/directives/other.py:147 +#: sphinx/directives/other.py:146 msgid "Section author: " msgstr "" -#: sphinx/directives/other.py:149 +#: sphinx/directives/other.py:148 msgid "Module author: " msgstr "" -#: sphinx/directives/other.py:151 +#: sphinx/directives/other.py:150 msgid "Author: " msgstr "" -#: sphinx/directives/other.py:233 +#: sphinx/directives/other.py:249 msgid "See also" msgstr "" +#: sphinx/ext/autodoc.py:442 +#, python-format +msgid " Bases: %s" +msgstr "" + +#: sphinx/ext/autodoc.py:566 sphinx/ext/autodoc.py:583 +#, python-format +msgid "alias of :class:`%s`" +msgstr "" + +#: sphinx/ext/todo.py:31 +msgid "Todo" +msgstr "" + +#: sphinx/ext/todo.py:75 +#, python-format +msgid "(The original entry is located in %s, line %d and can be found " +msgstr "" + +#: sphinx/ext/todo.py:81 +msgid "here" +msgstr "" + #: sphinx/locale/__init__.py:15 msgid "Attention" msgstr "" @@ -322,6 +337,14 @@ msgstr "" msgid "built-in function" msgstr "" +#: sphinx/static/doctools.js:139 sphinx/writers/html.py:425 +msgid "Permalink to this headline" +msgstr "" + +#: sphinx/static/doctools.js:145 sphinx/writers/html.py:80 +msgid "Permalink to this definition" +msgstr "" + #: sphinx/static/doctools.js:174 msgid "Hide Search Matches" msgstr "" @@ -334,17 +357,25 @@ msgstr "" msgid "Preparing search..." msgstr "" -#: sphinx/static/searchtools.js:401 sphinx/templates/search.html:18 +#: sphinx/static/searchtools.js:338 +msgid "module, in " +msgstr "" + +#: sphinx/static/searchtools.js:347 +msgid ", in " +msgstr "" + +#: sphinx/static/searchtools.js:453 sphinx/templates/search.html:25 msgid "Search Results" msgstr "" -#: sphinx/static/searchtools.js:403 +#: sphinx/static/searchtools.js:455 msgid "" "Your search did not match any documents. Please make sure that all words " "are spelled correctly and that you've selected enough categories." msgstr "" -#: sphinx/static/searchtools.js:405 +#: sphinx/static/searchtools.js:457 #, python-format msgid "Search finished, found %s page(s) matching the search query." msgstr "" @@ -408,27 +439,23 @@ msgstr "" msgid "Previous topic" msgstr "" -#: sphinx/templates/layout.html:47 +#: sphinx/templates/layout.html:48 msgid "previous chapter" msgstr "" -#: sphinx/templates/layout.html:50 +#: sphinx/templates/layout.html:51 msgid "Next topic" msgstr "" -#: sphinx/templates/layout.html:51 +#: sphinx/templates/layout.html:53 msgid "next chapter" msgstr "" -#: sphinx/templates/layout.html:55 +#: sphinx/templates/layout.html:58 msgid "This Page" msgstr "" -#: sphinx/templates/layout.html:59 -msgid "Suggest Change" -msgstr "" - -#: sphinx/templates/layout.html:60 sphinx/templates/layout.html:62 +#: sphinx/templates/layout.html:61 msgid "Show Source" msgstr "" @@ -436,75 +463,55 @@ msgstr "" msgid "Quick search" msgstr "" -#: sphinx/templates/layout.html:71 -msgid "Keyword search" -msgstr "" - -#: sphinx/templates/layout.html:73 +#: sphinx/templates/layout.html:74 msgid "Go" msgstr "" #: sphinx/templates/layout.html:78 -msgid "Enter a module, class or function name." +msgid "Enter search terms or a module, class or function name." msgstr "" -#: sphinx/templates/layout.html:118 +#: sphinx/templates/layout.html:115 #, python-format msgid "Search within %(docstitle)s" msgstr "" -#: sphinx/templates/layout.html:127 +#: sphinx/templates/layout.html:124 msgid "About these documents" msgstr "" -#: sphinx/templates/layout.html:129 -msgid "Global table of contents" -msgstr "" - -#: sphinx/templates/layout.html:130 -msgid "Global index" -msgstr "" - -#: sphinx/templates/layout.html:131 sphinx/templates/search.html:2 +#: sphinx/templates/layout.html:127 sphinx/templates/search.html:2 #: sphinx/templates/search.html:5 msgid "Search" msgstr "" -#: sphinx/templates/layout.html:133 +#: sphinx/templates/layout.html:129 msgid "Copyright" msgstr "" -#: sphinx/templates/layout.html:178 +#: sphinx/templates/layout.html:174 #, python-format msgid "© <a href=\"%(path)s\">Copyright</a> %(copyright)s." msgstr "" -#: sphinx/templates/layout.html:180 +#: sphinx/templates/layout.html:176 #, python-format msgid "© Copyright %(copyright)s." msgstr "" -#: sphinx/templates/layout.html:183 +#: sphinx/templates/layout.html:179 #, python-format msgid "Last updated on %(last_updated)s." msgstr "" -#: sphinx/templates/layout.html:186 +#: sphinx/templates/layout.html:182 #, python-format msgid "" "Created using <a href=\"http://sphinx.pocoo.org/\">Sphinx</a> " "%(sphinx_version)s." msgstr "" -#: sphinx/templates/modindex.html:15 -msgid "Most popular modules:" -msgstr "" - -#: sphinx/templates/modindex.html:24 -msgid "Show modules only available on these platforms" -msgstr "" - -#: sphinx/templates/modindex.html:56 +#: sphinx/templates/modindex.html:36 msgid "Deprecated" msgstr "" @@ -513,26 +520,25 @@ msgstr "" msgid "Search %(docstitle)s" msgstr "" -#: sphinx/templates/page.html:8 +#: sphinx/templates/search.html:9 msgid "" -"<strong>Note:</strong> You requested an out-of-date URL from this server." -" We've tried to redirect you to the new location of this page, but it may" -" not be the right one." +"Please activate JavaScript to enable the search\n" +" functionality." msgstr "" -#: sphinx/templates/search.html:7 +#: sphinx/templates/search.html:14 msgid "" "From here you can search these documents. Enter your search\n" " words into the box below and click \"search\". Note that the search\n" " function will automatically search for all of the words. Pages\n" -" containing less words won't appear in the result list." +" containing fewer words won't appear in the result list." msgstr "" -#: sphinx/templates/search.html:14 +#: sphinx/templates/search.html:21 msgid "search" msgstr "" -#: sphinx/templates/search.html:20 +#: sphinx/templates/search.html:27 msgid "Your search did not match any results." msgstr "" @@ -564,3 +570,16 @@ msgstr "" msgid "Other changes" msgstr "" +#: sphinx/writers/latex.py:173 +msgid "Release" +msgstr "" + +#: sphinx/writers/text.py:166 +#, python-format +msgid "Platform: %s" +msgstr "" + +#: sphinx/writers/text.py:427 +msgid "[image]" +msgstr "" + diff --git a/sphinx/locale/uk_UA/LC_MESSAGES/sphinx.js b/sphinx/locale/uk_UA/LC_MESSAGES/sphinx.js new file mode 100644 index 000000000..d1089bf16 --- /dev/null +++ b/sphinx/locale/uk_UA/LC_MESSAGES/sphinx.js @@ -0,0 +1 @@ +Documentation.addTranslations({"locale": "uk_UA", "plural_expr": "(n%10==1 && n%100!=11 ? 0 : n%10>=2 && n%10<=4 && (n%100<10 || n%100>=20) ? 1 : 2)", "messages": {"module, in ": "\u043c\u043e\u0434\u0443\u043b\u044c, \u0432 ", "Preparing search...": "\u041f\u0456\u0434\u0433\u043e\u0442\u043e\u0432\u043a\u0430 \u0434\u043e \u043f\u043e\u0448\u0443\u043a\u0443...", "Your search did not match any documents. Please make sure that all words are spelled correctly and that you've selected enough categories.": "\u0412\u0430\u0448 \u043f\u043e\u0448\u0443\u043a \u043d\u0435 \u0432\u0438\u044f\u0432\u0438\u0432 \u0436\u043e\u0434\u043d\u043e\u0433\u043e \u0441\u043f\u0456\u0432\u043f\u0430\u0434\u0456\u043d\u043d\u044f. \u0411\u0443\u0434\u044c-\u043b\u0430\u0441\u043a\u0430 \u043f\u0435\u0440\u0435\u043a\u043e\u043d\u0430\u0439\u0442\u0435\u0441\u044f \u0449\u043e \u0432\u0441\u0456 \u0441\u043b\u043e\u0432\u0430 \u043d\u0430\u0431\u0440\u0430\u043d\u0456 \u043f\u0440\u0430\u0432\u0438\u043b\u044c\u043d\u043e \u0456 \u0432\u0438 \u043e\u0431\u0440\u0430\u043b\u0438 \u0434\u043e\u0441\u0442\u0430\u0442\u043d\u044c\u043e \u043a\u0430\u0442\u0435\u0433\u043e\u0440\u0456\u0439.", "Search finished, found %s page(s) matching the search query.": "\u041f\u043e\u0448\u0443\u043a \u0437\u0430\u043a\u0456\u043d\u0447\u0435\u043d\u043e, \u0437\u043d\u0430\u0439\u0434\u0435\u043d\u043e %s \u0441\u0442\u043e\u0440\u0456\u043d\u043e\u043a \u044f\u043a\u0456 \u0441\u043f\u0456\u0432\u043f\u0430\u043b\u0438 \u0437 \u043f\u043e\u0448\u0443\u043a\u043e\u0432\u0438\u043c \u0437\u0430\u043f\u0438\u0442\u043e\u043c.", ", in ": ", \u0432 ", "Permalink to this headline": "\u041f\u043e\u0441\u0442\u0456\u0439\u043d\u0435 \u043f\u043e\u0441\u0438\u043b\u0430\u043d\u043d\u044f \u043d\u0430 \u0446\u0435\u0439 \u0437\u0430\u0433\u043e\u043b\u043e\u0432\u043e\u043a", "Searching": "\u0428\u0443\u043a\u0430\u044e", "Permalink to this definition": "\u041f\u043e\u0441\u0442\u0456\u0439\u043d\u0435 \u043f\u043e\u0441\u0438\u043b\u0430\u043d\u043d\u044f \u043d\u0430 \u0446\u0435 \u0432\u0438\u0437\u043d\u0430\u0447\u0435\u043d\u043d\u044f", "Hide Search Matches": "\u041f\u0440\u0438\u0445\u043e\u0432\u0430\u0442\u0438 \u0441\u043f\u0456\u0432\u043f\u0430\u0434\u0456\u043d\u043d\u044f \u043f\u043e\u0448\u0443\u043a\u0443", "Search Results": "\u0420\u0435\u0437\u0443\u043b\u044c\u0442\u0430\u0442\u0438 \u043f\u043e\u0448\u0443\u043a\u0443"}}); \ No newline at end of file diff --git a/sphinx/locale/uk_UA/LC_MESSAGES/sphinx.mo b/sphinx/locale/uk_UA/LC_MESSAGES/sphinx.mo new file mode 100644 index 000000000..db1ce221b Binary files /dev/null and b/sphinx/locale/uk_UA/LC_MESSAGES/sphinx.mo differ diff --git a/sphinx/locale/uk_UA/LC_MESSAGES/sphinx.po b/sphinx/locale/uk_UA/LC_MESSAGES/sphinx.po new file mode 100644 index 000000000..9f6992f0d --- /dev/null +++ b/sphinx/locale/uk_UA/LC_MESSAGES/sphinx.po @@ -0,0 +1,595 @@ +# Ukrainian (Ukraine) translations for Sphinx. +# Copyright (C) 2009 ORGANIZATION +# This file is distributed under the same license as the Sphinx project. +# Petro Sasnyk <petro@sasnyk.name>, 2009. +# +msgid "" +msgstr "" +"Project-Id-Version: Sphinx 0.6\n" +"Report-Msgid-Bugs-To: EMAIL@ADDRESS\n" +"POT-Creation-Date: 2008-12-28 23:40+0100\n" +"PO-Revision-Date: 2009-01-14 17:34+0200\n" +"Last-Translator: Petro Sasnyk <petro@sasnyk.name>\n" +"Language-Team: uk_UA <LL@li.org>\n" +"Plural-Forms: nplurals=3; plural=(n%10==1 && n%100!=11 ? 0 : n%10>=2 && " +"n%10<=4 && (n%100<10 || n%100>=20) ? 1 : 2)\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=utf-8\n" +"Content-Transfer-Encoding: 8bit\n" +"Generated-By: Babel 0.9.4\n" + +#: sphinx/environment.py:104 sphinx/writers/latex.py:170 +#, python-format +msgid "%B %d, %Y" +msgstr "" + +#: sphinx/environment.py:300 sphinx/templates/genindex-single.html:2 +#: sphinx/templates/genindex-split.html:2 +#: sphinx/templates/genindex-split.html:5 sphinx/templates/genindex.html:2 +#: sphinx/templates/genindex.html:5 sphinx/templates/genindex.html:48 +#: sphinx/templates/layout.html:126 sphinx/writers/latex.py:176 +msgid "Index" +msgstr "Індекс" + +#: sphinx/environment.py:301 sphinx/writers/latex.py:175 +msgid "Module Index" +msgstr "Індекс модулів" + +#: sphinx/environment.py:302 sphinx/templates/defindex.html:16 +msgid "Search Page" +msgstr "Сторінка пошуку" + +#: sphinx/roles.py:53 sphinx/directives/desc.py:580 +#, python-format +msgid "environment variable; %s" +msgstr "змінна оточення; %s" + +#: sphinx/roles.py:60 +#, python-format +msgid "Python Enhancement Proposals!PEP %s" +msgstr "Python Enhancement Proposals!PEP %s" + +#: sphinx/builders/changes.py:64 +msgid "Builtins" +msgstr "Вбудовані елементи" + +#: sphinx/builders/changes.py:66 +msgid "Module level" +msgstr "Рівень модуля" + +#: sphinx/builders/html.py:118 +#, python-format +msgid "%b %d, %Y" +msgstr "%b %d, %Y" + +#: sphinx/builders/html.py:137 sphinx/templates/defindex.html:21 +msgid "General Index" +msgstr "Загальний індекс" + +#: sphinx/builders/html.py:137 +msgid "index" +msgstr "індекс" + +#: sphinx/builders/html.py:139 sphinx/builders/htmlhelp.py:182 +#: sphinx/builders/qthelp.py:131 sphinx/templates/defindex.html:19 +#: sphinx/templates/modindex.html:2 sphinx/templates/modindex.html:13 +msgid "Global Module Index" +msgstr "Загальний індекс модулів" + +#: sphinx/builders/html.py:139 +msgid "modules" +msgstr "модулі" + +#: sphinx/builders/html.py:179 +msgid "next" +msgstr "наступний" + +#: sphinx/builders/html.py:186 +msgid "previous" +msgstr "попередній" + +#: sphinx/builders/latex.py:155 +msgid " (in " +msgstr " (в " + +#: sphinx/directives/desc.py:25 +#, python-format +msgid "%s() (built-in function)" +msgstr "%s() (вбудована функція)" + +#: sphinx/directives/desc.py:26 sphinx/directives/desc.py:42 +#: sphinx/directives/desc.py:54 +#, python-format +msgid "%s() (in module %s)" +msgstr "%s() (в модулі %s)" + +#: sphinx/directives/desc.py:29 +#, python-format +msgid "%s (built-in variable)" +msgstr "%s (вбудована змінна)" + +#: sphinx/directives/desc.py:30 sphinx/directives/desc.py:78 +#, python-format +msgid "%s (in module %s)" +msgstr "%s (в модулі %s)" + +#: sphinx/directives/desc.py:33 +#, python-format +msgid "%s (built-in class)" +msgstr "%s (вбудований клас)" + +#: sphinx/directives/desc.py:34 +#, python-format +msgid "%s (class in %s)" +msgstr "%s (клас в %s)" + +#: sphinx/directives/desc.py:46 +#, python-format +msgid "%s() (%s.%s method)" +msgstr "%s() (%s.%s метод)" + +#: sphinx/directives/desc.py:48 +#, python-format +msgid "%s() (%s method)" +msgstr "%s() (%s метод)" + +#: sphinx/directives/desc.py:58 +#, python-format +msgid "%s() (%s.%s static method)" +msgstr "%s() (%s.%s статичний метод)" + +#: sphinx/directives/desc.py:60 +#, python-format +msgid "%s() (%s static method)" +msgstr "%s() (%s статичний метод)" + +#: sphinx/directives/desc.py:82 +#, python-format +msgid "%s (%s.%s attribute)" +msgstr "%s (%s.%s атрибут)" + +#: sphinx/directives/desc.py:84 +#, python-format +msgid "%s (%s attribute)" +msgstr "%s (%s атрибут)" + +#: sphinx/directives/desc.py:86 +#, python-format +msgid "%s (C function)" +msgstr "%s (С функція)" + +#: sphinx/directives/desc.py:88 +#, python-format +msgid "%s (C member)" +msgstr "%s (C член)" + +#: sphinx/directives/desc.py:90 +#, python-format +msgid "%s (C macro)" +msgstr "%s (C макрос)" + +#: sphinx/directives/desc.py:92 +#, python-format +msgid "%s (C type)" +msgstr "%s (C тип)" + +#: sphinx/directives/desc.py:94 +#, python-format +msgid "%s (C variable)" +msgstr "%s (C змінна)" + +#: sphinx/directives/desc.py:112 +msgid "Raises" +msgstr "Викликає" + +#: sphinx/directives/desc.py:116 +msgid "Variable" +msgstr "Змінна" + +#: sphinx/directives/desc.py:119 +msgid "Returns" +msgstr "Повертає" + +#: sphinx/directives/desc.py:128 +msgid "Return type" +msgstr "Тип повернення" + +#: sphinx/directives/desc.py:213 +msgid "Parameter" +msgstr "Параметр" + +#: sphinx/directives/desc.py:217 +msgid "Parameters" +msgstr "Параметри" + +#: sphinx/directives/desc.py:465 +#, python-format +msgid "%scommand line option; %s" +msgstr "%sопція командного рядка; %s" + +#: sphinx/directives/other.py:101 +msgid "Platforms: " +msgstr "Платформи: " + +#: sphinx/directives/other.py:106 +#, python-format +msgid "%s (module)" +msgstr "%s (модуль)" + +#: sphinx/directives/other.py:146 +msgid "Section author: " +msgstr "Автор секції: " + +#: sphinx/directives/other.py:148 +msgid "Module author: " +msgstr "Автор модуля: " + +#: sphinx/directives/other.py:150 +msgid "Author: " +msgstr "Автор: " + +#: sphinx/directives/other.py:249 +msgid "See also" +msgstr "Дивись також" + +#: sphinx/ext/autodoc.py:442 +#, python-format +msgid " Bases: %s" +msgstr " Базовий: %s" + +#: sphinx/ext/autodoc.py:563 sphinx/ext/autodoc.py:580 +#, python-format +msgid "alias of :class:`%s`" +msgstr "синонім :class:`%s`" + +#: sphinx/ext/todo.py:31 +msgid "Todo" +msgstr "Доробити" + +#: sphinx/ext/todo.py:75 +#, python-format +msgid "(The original entry is located in %s, line %d and can be found " +msgstr "(Початкове входження знаходиться в %s, рядок %d і може бути знайдений " + +#: sphinx/ext/todo.py:81 +msgid "here" +msgstr "тут" + +#: sphinx/locale/__init__.py:15 +msgid "Attention" +msgstr "Увага" + +#: sphinx/locale/__init__.py:16 +msgid "Caution" +msgstr "Застереження" + +#: sphinx/locale/__init__.py:17 +msgid "Danger" +msgstr "Небезпека" + +#: sphinx/locale/__init__.py:18 +msgid "Error" +msgstr "Помилка" + +#: sphinx/locale/__init__.py:19 +msgid "Hint" +msgstr "Підказка" + +#: sphinx/locale/__init__.py:20 +msgid "Important" +msgstr "Важливо" + +#: sphinx/locale/__init__.py:21 +msgid "Note" +msgstr "Примітка" + +#: sphinx/locale/__init__.py:22 +msgid "See Also" +msgstr "Дивись також" + +#: sphinx/locale/__init__.py:23 +msgid "Tip" +msgstr "Порада" + +#: sphinx/locale/__init__.py:24 +msgid "Warning" +msgstr "Попередження" + +#: sphinx/locale/__init__.py:28 +#, python-format +msgid "New in version %s" +msgstr "Нове в версії %s" + +#: sphinx/locale/__init__.py:29 +#, python-format +msgid "Changed in version %s" +msgstr "Змінено в версії %s" + +#: sphinx/locale/__init__.py:30 +#, python-format +msgid "Deprecated since version %s" +msgstr "Застаріло починаючи з версії %s" + +#: sphinx/locale/__init__.py:34 +msgid "module" +msgstr "модуль" + +#: sphinx/locale/__init__.py:35 +msgid "keyword" +msgstr "ключове слово" + +#: sphinx/locale/__init__.py:36 +msgid "operator" +msgstr "оператор" + +#: sphinx/locale/__init__.py:37 +msgid "object" +msgstr "об'єкт" + +#: sphinx/locale/__init__.py:38 +msgid "exception" +msgstr "виняткова ситуація" + +#: sphinx/locale/__init__.py:39 +msgid "statement" +msgstr "вираз" + +#: sphinx/locale/__init__.py:40 +msgid "built-in function" +msgstr "вбудована функція" + +#: sphinx/static/doctools.js:139 sphinx/writers/html.py:425 +msgid "Permalink to this headline" +msgstr "Постійне посилання на цей заголовок" + +#: sphinx/static/doctools.js:145 sphinx/writers/html.py:80 +msgid "Permalink to this definition" +msgstr "Постійне посилання на це визначення" + +#: sphinx/static/doctools.js:174 +msgid "Hide Search Matches" +msgstr "Приховати співпадіння пошуку" + +#: sphinx/static/searchtools.js:274 +msgid "Searching" +msgstr "Шукаю" + +#: sphinx/static/searchtools.js:279 +msgid "Preparing search..." +msgstr "Підготовка до пошуку..." + +#: sphinx/static/searchtools.js:338 +msgid "module, in " +msgstr "модуль, в " + +#: sphinx/static/searchtools.js:347 +msgid ", in " +msgstr ", в " + +#: sphinx/static/searchtools.js:453 sphinx/templates/search.html:25 +msgid "Search Results" +msgstr "Результати пошуку" + +#: sphinx/static/searchtools.js:455 +msgid "" +"Your search did not match any documents. Please make sure that all words " +"are spelled correctly and that you've selected enough categories." +msgstr "" +"Ваш пошук не виявив жодного співпадіння. Будь-ласка переконайтеся що всі " +"слова набрані правильно і ви обрали достатньо категорій." + +#: sphinx/static/searchtools.js:457 +#, python-format +msgid "Search finished, found %s page(s) matching the search query." +msgstr "Пошук закінчено, знайдено %s сторінок які співпали з пошуковим запитом." + +#: sphinx/templates/defindex.html:2 +msgid "Overview" +msgstr "Огляд" + +#: sphinx/templates/defindex.html:11 +msgid "Indices and tables:" +msgstr "Індекси та таблиці:" + +#: sphinx/templates/defindex.html:14 +msgid "Complete Table of Contents" +msgstr "Повний Зміст" + +#: sphinx/templates/defindex.html:15 +msgid "lists all sections and subsections" +msgstr "перелічити всі секції та підсекції" + +#: sphinx/templates/defindex.html:17 +msgid "search this documentation" +msgstr "шукати цю документацію" + +#: sphinx/templates/defindex.html:20 +msgid "quick access to all modules" +msgstr "швидкий доступ до всіх модулів" + +#: sphinx/templates/defindex.html:22 +msgid "all functions, classes, terms" +msgstr "всі функції, класи, терміни" + +#: sphinx/templates/genindex-single.html:5 +#, python-format +msgid "Index – %(key)s" +msgstr "Індекс – %(key)" + +#: sphinx/templates/genindex-single.html:44 +#: sphinx/templates/genindex-split.html:14 +#: sphinx/templates/genindex-split.html:27 sphinx/templates/genindex.html:54 +msgid "Full index on one page" +msgstr "Повний індекс на одній сторінці" + +#: sphinx/templates/genindex-split.html:7 +msgid "Index pages by letter" +msgstr "Індексні сторінки по символам" + +#: sphinx/templates/genindex-split.html:15 +msgid "can be huge" +msgstr "може бути величезним" + +#: sphinx/templates/layout.html:9 +msgid "Navigation" +msgstr "Навігація" + +#: sphinx/templates/layout.html:40 +msgid "Table Of Contents" +msgstr "Зміст" + +#: sphinx/templates/layout.html:46 +msgid "Previous topic" +msgstr "Попередній розділ" + +#: sphinx/templates/layout.html:48 +msgid "previous chapter" +msgstr "Попередній розділ" + +#: sphinx/templates/layout.html:51 +msgid "Next topic" +msgstr "Наступна тема" + +#: sphinx/templates/layout.html:53 +msgid "next chapter" +msgstr "наступний розділ" + +#: sphinx/templates/layout.html:58 +msgid "This Page" +msgstr "Ця сторінка" + +#: sphinx/templates/layout.html:61 +msgid "Show Source" +msgstr "Відобразити вихідний текст" + +#: sphinx/templates/layout.html:71 +msgid "Quick search" +msgstr "Швидкий пошук" + +#: sphinx/templates/layout.html:74 +msgid "Go" +msgstr "Вперед" + +#: sphinx/templates/layout.html:78 +msgid "Enter search terms or a module, class or function name." +msgstr "Введіть пошуковий термін, модуль, клас чи назву функції." + +#: sphinx/templates/layout.html:115 +#, python-format +msgid "Search within %(docstitle)s" +msgstr "Шукати в %(docstitle)s" + +#: sphinx/templates/layout.html:124 +msgid "About these documents" +msgstr "Про ці документи" + +#: sphinx/templates/layout.html:127 sphinx/templates/search.html:2 +#: sphinx/templates/search.html:5 +msgid "Search" +msgstr "Пошук" + +#: sphinx/templates/layout.html:129 +msgid "Copyright" +msgstr "Авторські права" + +#: sphinx/templates/layout.html:174 +#, python-format +msgid "© <a href=\"%(path)s\">Copyright</a> %(copyright)s." +msgstr "© <a href=\"%(path)s\">Copyright</a> %(copyright)s." + +#: sphinx/templates/layout.html:176 +#, python-format +msgid "© Copyright %(copyright)s." +msgstr "© Copyright %(copyright)s." + +#: sphinx/templates/layout.html:179 +#, python-format +msgid "Last updated on %(last_updated)s." +msgstr "Востаннє оновлено %(last_updated)s." + +#: sphinx/templates/layout.html:182 +#, python-format +msgid "" +"Created using <a href=\"http://sphinx.pocoo.org/\">Sphinx</a> " +"%(sphinx_version)s." +msgstr "" +"Створено з використанням <a href=\"http://sphinx.pocoo.org/\">Sphinx</a> " +"%(sphinx_version)s." + +#: sphinx/templates/modindex.html:36 +msgid "Deprecated" +msgstr "Застарілий" + +#: sphinx/templates/opensearch.xml:4 +#, python-format +msgid "Search %(docstitle)s" +msgstr "Пошук %(docstitle)s" + +#: sphinx/templates/search.html:9 +msgid "" +"Please activate JavaScript to enable the search\n" +" functionality." +msgstr "Будь-ласка вімкніть підтримку JavaScript, щоб ввікнути\n" +" пошук." + +#: sphinx/templates/search.html:14 +msgid "" +"From here you can search these documents. Enter your search\n" +" words into the box below and click \"search\". Note that the search\n" +" function will automatically search for all of the words. Pages\n" +" containing fewer words won't appear in the result list." +msgstr "" +"Звідси ви можете шукати ці документи. Введіть ваші пошукові\n" +" слова в поле нижче та натисніть \"пошук\". Зауважте що функція\n" +" пошуку автоматично шукатиме за всіма словами. Сторінки\n" +" що містять менше слів не з'являться в результуючому списку." + +#: sphinx/templates/search.html:21 +msgid "search" +msgstr "пошук" + +#: sphinx/templates/search.html:27 +msgid "Your search did not match any results." +msgstr "Ваш пошук не виявив жодних співпадінь." + +#: sphinx/templates/changes/frameset.html:5 +#: sphinx/templates/changes/versionchanges.html:12 +#, python-format +msgid "Changes in Version %(version)s — %(docstitle)s" +msgstr "Зміни в Версії %(version)s — %(docstitle)" + +#: sphinx/templates/changes/rstsource.html:5 +#, python-format +msgid "%(filename)s — %(docstitle)s" +msgstr "%(filename) — %(docstitle)" + +#: sphinx/templates/changes/versionchanges.html:17 +#, python-format +msgid "Automatically generated list of changes in version %(version)s" +msgstr "Автоматичного згенерований список змін в версії %(version)" + +#: sphinx/templates/changes/versionchanges.html:18 +msgid "Library changes" +msgstr "Зміни в бібліотеці" + +#: sphinx/templates/changes/versionchanges.html:23 +msgid "C API changes" +msgstr "зміни C API" + +#: sphinx/templates/changes/versionchanges.html:25 +msgid "Other changes" +msgstr "Інші зміни" + +#: sphinx/writers/latex.py:173 +msgid "Release" +msgstr "Реліз" + +#: sphinx/writers/text.py:166 +#, python-format +msgid "Platform: %s" +msgstr "Платформа: %s" + +#: sphinx/writers/text.py:427 +msgid "[image]" +msgstr "" + diff --git a/sphinx/locale/zh_TW/LC_MESSAGES/sphinx.js b/sphinx/locale/zh_TW/LC_MESSAGES/sphinx.js new file mode 100644 index 000000000..753831003 --- /dev/null +++ b/sphinx/locale/zh_TW/LC_MESSAGES/sphinx.js @@ -0,0 +1 @@ +Documentation.addTranslations({"locale": "zh_TW", "plural_expr": "0", "messages": {"module, in ": "", "Preparing search...": "\u6e96\u5099\u641c\u5c0b...", "Your search did not match any documents. Please make sure that all words are spelled correctly and that you've selected enough categories.": "", "Search finished, found %s page(s) matching the search query.": "", ", in ": "", "Permalink to this headline": "", "Searching": "\u641c\u5c0b\u4e2d", "Permalink to this definition": "", "Hide Search Matches": "", "Search Results": "\u641c\u5c0b\u7d50\u679c"}}); \ No newline at end of file diff --git a/sphinx/locale/zh_TW/LC_MESSAGES/sphinx.mo b/sphinx/locale/zh_TW/LC_MESSAGES/sphinx.mo new file mode 100644 index 000000000..f0576ccd2 Binary files /dev/null and b/sphinx/locale/zh_TW/LC_MESSAGES/sphinx.mo differ diff --git a/sphinx/locale/zh_TW/LC_MESSAGES/sphinx.po b/sphinx/locale/zh_TW/LC_MESSAGES/sphinx.po new file mode 100644 index 000000000..9dc3c8ea2 --- /dev/null +++ b/sphinx/locale/zh_TW/LC_MESSAGES/sphinx.po @@ -0,0 +1,587 @@ +# Chinese (Taiwan) translations for Sphinx. +# Copyright (C) 2008 ORGANIZATION +# This file is distributed under the same license as the Sphinx project. +# Fred Lin <gasolin@gmail.com>, 2008. +# +msgid "" +msgstr "" +"Project-Id-Version: Sphinx 0.5\n" +"Report-Msgid-Bugs-To: EMAIL@ADDRESS\n" +"POT-Creation-Date: 2008-11-09 19:46+0100\n" +"PO-Revision-Date: 2009-01-24 18:39+0000\n" +"Last-Translator: Fred Lin <gasolin@gmail.com>\n" +"Language-Team: tw <LL@li.org>\n" +"Plural-Forms: nplurals=1; plural=0\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=utf-8\n" +"Content-Transfer-Encoding: 8bit\n" +"Generated-By: Babel 0.9.3\n" + +#: sphinx/environment.py:104 sphinx/writers/latex.py:170 +#, python-format +msgid "%B %d, %Y" +msgstr "%Y 年 %m 月 %d 日" + +#: sphinx/environment.py:300 sphinx/templates/genindex-single.html:2 +#: sphinx/templates/genindex-split.html:2 +#: sphinx/templates/genindex-split.html:5 sphinx/templates/genindex.html:2 +#: sphinx/templates/genindex.html:5 sphinx/templates/genindex.html:48 +#: sphinx/templates/layout.html:126 sphinx/writers/latex.py:176 +msgid "Index" +msgstr "索引" + +#: sphinx/environment.py:301 sphinx/writers/latex.py:175 +msgid "Module Index" +msgstr "模組索引" + +#: sphinx/environment.py:302 sphinx/templates/defindex.html:16 +msgid "Search Page" +msgstr "搜尋頁面" + +#: sphinx/roles.py:53 sphinx/directives/desc.py:580 +#, python-format +msgid "environment variable; %s" +msgstr "環境變數; %s" + +#: sphinx/roles.py:60 +#, python-format +msgid "Python Enhancement Proposals!PEP %s" +msgstr "Python 建議文件!PEP %s" + +#: sphinx/builders/changes.py:64 +msgid "Builtins" +msgstr "" + +#: sphinx/builders/changes.py:66 +msgid "Module level" +msgstr "" + +#: sphinx/builders/html.py:118 +#, python-format +msgid "%b %d, %Y" +msgstr "%Y 年 %m 月 %d 日" + +#: sphinx/builders/html.py:137 sphinx/templates/defindex.html:21 +msgid "General Index" +msgstr "總索引" + +#: sphinx/builders/html.py:137 +msgid "index" +msgstr "索引" + +#: sphinx/builders/html.py:139 sphinx/builders/htmlhelp.py:182 +#: sphinx/builders/qthelp.py:131 sphinx/templates/defindex.html:19 +#: sphinx/templates/modindex.html:2 sphinx/templates/modindex.html:13 +msgid "Global Module Index" +msgstr "" + +#: sphinx/builders/html.py:139 +msgid "modules" +msgstr "模組" + +#: sphinx/builders/html.py:179 +msgid "next" +msgstr "下一頁" + +#: sphinx/builders/html.py:186 +msgid "previous" +msgstr "上一頁" + +#: sphinx/builders/latex.py:155 sphinx/builders/pdf.py:162 +msgid " (in " +msgstr "" + +#: sphinx/directives/desc.py:25 +#, python-format +msgid "%s() (built-in function)" +msgstr "%s() (內建函式)" + +#: sphinx/directives/desc.py:26 sphinx/directives/desc.py:42 +#: sphinx/directives/desc.py:54 +#, python-format +msgid "%s() (in module %s)" +msgstr "%s() (在 %s 模組中)" + +#: sphinx/directives/desc.py:29 +#, python-format +msgid "%s (built-in variable)" +msgstr "%s (內建變數)" + +#: sphinx/directives/desc.py:30 sphinx/directives/desc.py:78 +#, python-format +msgid "%s (in module %s)" +msgstr "%s() (在 %s 模組中)" + +#: sphinx/directives/desc.py:33 +#, python-format +msgid "%s (built-in class)" +msgstr "%s (內建類別)" + +#: sphinx/directives/desc.py:34 +#, python-format +msgid "%s (class in %s)" +msgstr "" + +#: sphinx/directives/desc.py:46 +#, python-format +msgid "%s() (%s.%s method)" +msgstr "%s() (%s.%s 方法)" + +#: sphinx/directives/desc.py:48 +#, python-format +msgid "%s() (%s method)" +msgstr "%s() (%s 方法)" + +#: sphinx/directives/desc.py:58 +#, python-format +msgid "%s() (%s.%s static method)" +msgstr "%s() (%s.%s 靜態方法)" + +#: sphinx/directives/desc.py:60 +#, python-format +msgid "%s() (%s static method)" +msgstr "%s() (%s 靜態方法)" + +#: sphinx/directives/desc.py:82 +#, python-format +msgid "%s (%s.%s attribute)" +msgstr "%s (%s.%s 屬性)" + +#: sphinx/directives/desc.py:84 +#, python-format +msgid "%s (%s attribute)" +msgstr "%s (%s 屬性)" + +#: sphinx/directives/desc.py:86 +#, python-format +msgid "%s (C function)" +msgstr "%s (C 函式)" + +#: sphinx/directives/desc.py:88 +#, python-format +msgid "%s (C member)" +msgstr "%s (C 成員)" + +#: sphinx/directives/desc.py:90 +#, python-format +msgid "%s (C macro)" +msgstr "%s (C 巨集)" + +#: sphinx/directives/desc.py:92 +#, python-format +msgid "%s (C type)" +msgstr "%s (C 類別)" + +#: sphinx/directives/desc.py:94 +#, python-format +msgid "%s (C variable)" +msgstr "%s (C 變數)" + +#: sphinx/directives/desc.py:112 +msgid "Raises" +msgstr "" + +#: sphinx/directives/desc.py:116 +msgid "Variable" +msgstr "變數" + +#: sphinx/directives/desc.py:119 +msgid "Returns" +msgstr "返回" + +#: sphinx/directives/desc.py:128 +msgid "Return type" +msgstr "返回類別" + +#: sphinx/directives/desc.py:213 +#, fuzzy +msgid "Parameter" +msgstr "參數" + +#: sphinx/directives/desc.py:217 +msgid "Parameters" +msgstr "參數" + +#: sphinx/directives/desc.py:465 +#, python-format +msgid "%scommand line option; %s" +msgstr "%s命令列選項; %s" + +#: sphinx/directives/other.py:101 +msgid "Platforms: " +msgstr "平台" + +#: sphinx/directives/other.py:106 +#, python-format +msgid "%s (module)" +msgstr "%s (模組)" + +#: sphinx/directives/other.py:146 +msgid "Section author: " +msgstr "Section 作者：" + +#: sphinx/directives/other.py:148 +msgid "Module author: " +msgstr "模組作者：" + +#: sphinx/directives/other.py:150 +msgid "Author: " +msgstr "作者：" + +#: sphinx/directives/other.py:249 +msgid "See also" +msgstr "" + +#: sphinx/ext/autodoc.py:442 +#, python-format +msgid " Bases: %s" +msgstr "" + +#: sphinx/ext/autodoc.py:566 sphinx/ext/autodoc.py:583 +#, python-format +msgid "alias of :class:`%s`" +msgstr "" + +#: sphinx/ext/todo.py:31 +msgid "Todo" +msgstr "待辦" + +#: sphinx/ext/todo.py:75 +#, python-format +msgid "(The original entry is located in %s, line %d and can be found " +msgstr "" + +#: sphinx/ext/todo.py:81 +msgid "here" +msgstr "" + +#: sphinx/locale/__init__.py:15 +msgid "Attention" +msgstr "注意" + +#: sphinx/locale/__init__.py:16 +msgid "Caution" +msgstr "警示" + +#: sphinx/locale/__init__.py:17 +msgid "Danger" +msgstr "危險" + +#: sphinx/locale/__init__.py:18 +msgid "Error" +msgstr "錯誤" + +#: sphinx/locale/__init__.py:19 +msgid "Hint" +msgstr "提示" + +#: sphinx/locale/__init__.py:20 +msgid "Important" +msgstr "重要" + +#: sphinx/locale/__init__.py:21 +msgid "Note" +msgstr "註解" + +#: sphinx/locale/__init__.py:22 +msgid "See Also" +msgstr "" + +#: sphinx/locale/__init__.py:23 +msgid "Tip" +msgstr "小技巧" + +#: sphinx/locale/__init__.py:24 +msgid "Warning" +msgstr "警告" + +#: sphinx/locale/__init__.py:28 +#, python-format +msgid "New in version %s" +msgstr "%s 版新功能" + +#: sphinx/locale/__init__.py:29 +#, python-format +msgid "Changed in version %s" +msgstr "在 %s 版改變" + +#: sphinx/locale/__init__.py:30 +#, python-format +msgid "Deprecated since version %s" +msgstr "%s 版後已移除" + +#: sphinx/locale/__init__.py:34 +msgid "module" +msgstr "模組" + +#: sphinx/locale/__init__.py:35 +msgid "keyword" +msgstr "關鍵字" + +#: sphinx/locale/__init__.py:36 +msgid "operator" +msgstr "運算子" + +#: sphinx/locale/__init__.py:37 +msgid "object" +msgstr "物件" + +#: sphinx/locale/__init__.py:38 +msgid "exception" +msgstr "例外" + +#: sphinx/locale/__init__.py:39 +msgid "statement" +msgstr "" + +#: sphinx/locale/__init__.py:40 +msgid "built-in function" +msgstr "內建函式" + +#: sphinx/static/doctools.js:139 sphinx/writers/html.py:425 +msgid "Permalink to this headline" +msgstr "" + +#: sphinx/static/doctools.js:145 sphinx/writers/html.py:80 +msgid "Permalink to this definition" +msgstr "" + +#: sphinx/static/doctools.js:174 +msgid "Hide Search Matches" +msgstr "" + +#: sphinx/static/searchtools.js:274 +msgid "Searching" +msgstr "搜尋中" + +#: sphinx/static/searchtools.js:279 +msgid "Preparing search..." +msgstr "準備搜尋..." + +#: sphinx/static/searchtools.js:338 +msgid "module, in " +msgstr "" + +#: sphinx/static/searchtools.js:347 +msgid ", in " +msgstr "" + +#: sphinx/static/searchtools.js:453 sphinx/templates/search.html:25 +msgid "Search Results" +msgstr "搜尋結果" + +#: sphinx/static/searchtools.js:455 +msgid "" +"Your search did not match any documents. Please make sure that all words " +"are spelled correctly and that you've selected enough categories." +msgstr "" + +#: sphinx/static/searchtools.js:457 +#, python-format +msgid "Search finished, found %s page(s) matching the search query." +msgstr "" + +#: sphinx/templates/defindex.html:2 +msgid "Overview" +msgstr "" + +#: sphinx/templates/defindex.html:11 +msgid "Indices and tables:" +msgstr "" + +#: sphinx/templates/defindex.html:14 +msgid "Complete Table of Contents" +msgstr "" + +#: sphinx/templates/defindex.html:15 +msgid "lists all sections and subsections" +msgstr "" + +#: sphinx/templates/defindex.html:17 +msgid "search this documentation" +msgstr "" + +#: sphinx/templates/defindex.html:20 +msgid "quick access to all modules" +msgstr "" + +#: sphinx/templates/defindex.html:22 +msgid "all functions, classes, terms" +msgstr "" + +#: sphinx/templates/genindex-single.html:5 +#, python-format +msgid "Index – %(key)s" +msgstr "" + +#: sphinx/templates/genindex-single.html:44 +#: sphinx/templates/genindex-split.html:14 +#: sphinx/templates/genindex-split.html:27 sphinx/templates/genindex.html:54 +msgid "Full index on one page" +msgstr "" + +#: sphinx/templates/genindex-split.html:7 +msgid "Index pages by letter" +msgstr "" + +#: sphinx/templates/genindex-split.html:15 +msgid "can be huge" +msgstr "" + +#: sphinx/templates/layout.html:9 +msgid "Navigation" +msgstr "瀏覽" + +#: sphinx/templates/layout.html:40 +msgid "Table Of Contents" +msgstr "內容目錄" + +#: sphinx/templates/layout.html:46 +msgid "Previous topic" +msgstr "上一個主題" + +#: sphinx/templates/layout.html:48 +msgid "previous chapter" +msgstr "上一章" + +#: sphinx/templates/layout.html:51 +msgid "Next topic" +msgstr "下一個主題" + +#: sphinx/templates/layout.html:53 +msgid "next chapter" +msgstr "下一章" + +#: sphinx/templates/layout.html:58 +msgid "This Page" +msgstr "本頁" + +#: sphinx/templates/layout.html:61 +msgid "Show Source" +msgstr "顯示原始碼" + +#: sphinx/templates/layout.html:71 +msgid "Quick search" +msgstr "快速搜尋" + +#: sphinx/templates/layout.html:74 +msgid "Go" +msgstr "" + +#: sphinx/templates/layout.html:78 +#, fuzzy +msgid "Enter search terms or a module, class or function name." +msgstr "輸入一個模組、類別、或是函式名稱." + +#: sphinx/templates/layout.html:115 +#, python-format +msgid "Search within %(docstitle)s" +msgstr "在 %(docstitle)s 中搜尋" + +#: sphinx/templates/layout.html:124 +msgid "About these documents" +msgstr "" + +#: sphinx/templates/layout.html:127 sphinx/templates/search.html:2 +#: sphinx/templates/search.html:5 +msgid "Search" +msgstr "搜尋" + +#: sphinx/templates/layout.html:129 +msgid "Copyright" +msgstr "版權所有" + +#: sphinx/templates/layout.html:174 +#, python-format +msgid "© <a href=\"%(path)s\">Copyright</a> %(copyright)s." +msgstr "" + +#: sphinx/templates/layout.html:176 +#, python-format +msgid "© Copyright %(copyright)s." +msgstr "" + +#: sphinx/templates/layout.html:179 +#, python-format +msgid "Last updated on %(last_updated)s." +msgstr "最後更新日期是 %(last_updated)s." + +#: sphinx/templates/layout.html:182 +#, python-format +msgid "" +"Created using <a href=\"http://sphinx.pocoo.org/\">Sphinx</a> " +"%(sphinx_version)s." +msgstr "" + +#: sphinx/templates/modindex.html:36 +msgid "Deprecated" +msgstr "已移除" + +#: sphinx/templates/opensearch.xml:4 +#, python-format +msgid "Search %(docstitle)s" +msgstr "搜尋 %(docstitle)s" + +#: sphinx/templates/search.html:9 +msgid "" +"Please activate JavaScript to enable the search\n" +" functionality." +msgstr "" + +#: sphinx/templates/search.html:14 +msgid "" +"From here you can search these documents. Enter your search\n" +" words into the box below and click \"search\". Note that the search\n" +" function will automatically search for all of the words. Pages\n" +" containing fewer words won't appear in the result list." +msgstr "" + +#: sphinx/templates/search.html:21 +msgid "search" +msgstr "搜尋" + +#: sphinx/templates/search.html:27 +msgid "Your search did not match any results." +msgstr "" + +#: sphinx/templates/changes/frameset.html:5 +#: sphinx/templates/changes/versionchanges.html:12 +#, python-format +msgid "Changes in Version %(version)s — %(docstitle)s" +msgstr "" + +#: sphinx/templates/changes/rstsource.html:5 +#, python-format +msgid "%(filename)s — %(docstitle)s" +msgstr "" + +#: sphinx/templates/changes/versionchanges.html:17 +#, python-format +msgid "Automatically generated list of changes in version %(version)s" +msgstr "" + +#: sphinx/templates/changes/versionchanges.html:18 +msgid "Library changes" +msgstr "" + +#: sphinx/templates/changes/versionchanges.html:23 +msgid "C API changes" +msgstr "C API 改變" + +#: sphinx/templates/changes/versionchanges.html:25 +msgid "Other changes" +msgstr "其他改變：" + +#: sphinx/writers/latex.py:173 +msgid "Release" +msgstr "釋出" + +#: sphinx/writers/text.py:166 +#, python-format +msgid "Platform: %s" +msgstr "平台：%s" + +#: sphinx/writers/text.py:427 +msgid "[image]" +msgstr "[圖片]" + diff --git a/sphinx/pycode/Grammar.txt b/sphinx/pycode/Grammar.txt new file mode 100644 index 000000000..1f4a50ffb --- /dev/null +++ b/sphinx/pycode/Grammar.txt @@ -0,0 +1,155 @@ +# Grammar for Python + +# Note: Changing the grammar specified in this file will most likely +# require corresponding changes in the parser module +# (../Modules/parsermodule.c). If you can't make the changes to +# that module yourself, please co-ordinate the required changes +# with someone who can; ask around on python-dev for help. Fred +# Drake <fdrake@acm.org> will probably be listening there. + +# NOTE WELL: You should also follow all the steps listed in PEP 306, +# "How to Change Python's Grammar" + +# Commands for Kees Blom's railroad program +#diagram:token NAME +#diagram:token NUMBER +#diagram:token STRING +#diagram:token NEWLINE +#diagram:token ENDMARKER +#diagram:token INDENT +#diagram:output\input python.bla +#diagram:token DEDENT +#diagram:output\textwidth 20.04cm\oddsidemargin 0.0cm\evensidemargin 0.0cm +#diagram:rules + +# Start symbols for the grammar: +# file_input is a module or sequence of commands read from an input file; +# single_input is a single interactive statement; +# eval_input is the input for the eval() and input() functions. +# NB: compound_stmt in single_input is followed by extra NEWLINE! +file_input: (NEWLINE | stmt)* ENDMARKER +single_input: NEWLINE | simple_stmt | compound_stmt NEWLINE +eval_input: testlist NEWLINE* ENDMARKER + +decorator: '@' dotted_name [ '(' [arglist] ')' ] NEWLINE +decorators: decorator+ +decorated: decorators (classdef | funcdef) +funcdef: 'def' NAME parameters ['->' test] ':' suite +parameters: '(' [typedargslist] ')' +typedargslist: ((tfpdef ['=' test] ',')* + ('*' [tname] (',' tname ['=' test])* [',' '**' tname] | '**' tname) + | tfpdef ['=' test] (',' tfpdef ['=' test])* [',']) +tname: NAME [':' test] +tfpdef: tname | '(' tfplist ')' +tfplist: tfpdef (',' tfpdef)* [','] +varargslist: ((vfpdef ['=' test] ',')* + ('*' [vname] (',' vname ['=' test])* [',' '**' vname] | '**' vname) + | vfpdef ['=' test] (',' vfpdef ['=' test])* [',']) +vname: NAME +vfpdef: vname | '(' vfplist ')' +vfplist: vfpdef (',' vfpdef)* [','] + +stmt: simple_stmt | compound_stmt +simple_stmt: small_stmt (';' small_stmt)* [';'] NEWLINE +small_stmt: (expr_stmt | print_stmt | del_stmt | pass_stmt | flow_stmt | + import_stmt | global_stmt | exec_stmt | assert_stmt) +expr_stmt: testlist (augassign (yield_expr|testlist) | + ('=' (yield_expr|testlist))*) +augassign: ('+=' | '-=' | '*=' | '/=' | '%=' | '&=' | '|=' | '^=' | + '<<=' | '>>=' | '**=' | '//=') +# For normal assignments, additional restrictions enforced by the interpreter +print_stmt: 'print' ( [ test (',' test)* [','] ] | + '>>' test [ (',' test)+ [','] ] ) +del_stmt: 'del' exprlist +pass_stmt: 'pass' +flow_stmt: break_stmt | continue_stmt | return_stmt | raise_stmt | yield_stmt +break_stmt: 'break' +continue_stmt: 'continue' +return_stmt: 'return' [testlist] +yield_stmt: yield_expr +raise_stmt: 'raise' [test ['from' test | ',' test [',' test]]] +import_stmt: import_name | import_from +import_name: 'import' dotted_as_names +import_from: ('from' ('.'* dotted_name | '.'+) + 'import' ('*' | '(' import_as_names ')' | import_as_names)) +import_as_name: NAME ['as' NAME] +dotted_as_name: dotted_name ['as' NAME] +import_as_names: import_as_name (',' import_as_name)* [','] +dotted_as_names: dotted_as_name (',' dotted_as_name)* +dotted_name: NAME ('.' NAME)* +global_stmt: ('global' | 'nonlocal') NAME (',' NAME)* +exec_stmt: 'exec' expr ['in' test [',' test]] +assert_stmt: 'assert' test [',' test] + +compound_stmt: if_stmt | while_stmt | for_stmt | try_stmt | with_stmt | funcdef | classdef | decorated +if_stmt: 'if' test ':' suite ('elif' test ':' suite)* ['else' ':' suite] +while_stmt: 'while' test ':' suite ['else' ':' suite] +for_stmt: 'for' exprlist 'in' testlist ':' suite ['else' ':' suite] +try_stmt: ('try' ':' suite + ((except_clause ':' suite)+ + ['else' ':' suite] + ['finally' ':' suite] | + 'finally' ':' suite)) +with_stmt: 'with' test [ with_var ] ':' suite +with_var: 'as' expr +# NB compile.c makes sure that the default except clause is last +except_clause: 'except' [test [(',' | 'as') test]] +suite: simple_stmt | NEWLINE INDENT stmt+ DEDENT + +# Backward compatibility cruft to support: +# [ x for x in lambda: True, lambda: False if x() ] +# even while also allowing: +# lambda x: 5 if x else 2 +# (But not a mix of the two) +testlist_safe: old_test [(',' old_test)+ [',']] +old_test: or_test | old_lambdef +old_lambdef: 'lambda' [varargslist] ':' old_test + +test: or_test ['if' or_test 'else' test] | lambdef +or_test: and_test ('or' and_test)* +and_test: not_test ('and' not_test)* +not_test: 'not' not_test | comparison +comparison: expr (comp_op expr)* +comp_op: '<'|'>'|'=='|'>='|'<='|'<>'|'!='|'in'|'not' 'in'|'is'|'is' 'not' +expr: xor_expr ('|' xor_expr)* +xor_expr: and_expr ('^' and_expr)* +and_expr: shift_expr ('&' shift_expr)* +shift_expr: arith_expr (('<<'|'>>') arith_expr)* +arith_expr: term (('+'|'-') term)* +term: factor (('*'|'/'|'%'|'//') factor)* +factor: ('+'|'-'|'~') factor | power +power: atom trailer* ['**' factor] +atom: ('(' [yield_expr|testlist_gexp] ')' | + '[' [listmaker] ']' | + '{' [dictsetmaker] '}' | + '`' testlist1 '`' | + NAME | NUMBER | STRING+ | '.' '.' '.') +listmaker: test ( comp_for | (',' test)* [','] ) +testlist_gexp: test ( comp_for | (',' test)* [','] ) +lambdef: 'lambda' [varargslist] ':' test +trailer: '(' [arglist] ')' | '[' subscriptlist ']' | '.' NAME +subscriptlist: subscript (',' subscript)* [','] +subscript: test | [test] ':' [test] [sliceop] +sliceop: ':' [test] +exprlist: expr (',' expr)* [','] +testlist: test (',' test)* [','] +dictsetmaker: ( (test ':' test (comp_for | (',' test ':' test)* [','])) | + (test (comp_for | (',' test)* [','])) ) + +classdef: 'class' NAME ['(' [arglist] ')'] ':' suite + +arglist: (argument ',')* (argument [','] + |'*' test (',' argument)* [',' '**' test] + |'**' test) +argument: test [comp_for] | test '=' test # Really [keyword '='] test + +comp_iter: comp_for | comp_if +comp_for: 'for' exprlist 'in' testlist_safe [comp_iter] +comp_if: 'if' old_test [comp_iter] + +testlist1: test (',' test)* + +# not used in grammar, but may appear in "node" passed from Parser to Compiler +encoding_decl: NAME + +yield_expr: 'yield' [testlist] diff --git a/sphinx/pycode/__init__.py b/sphinx/pycode/__init__.py new file mode 100644 index 000000000..d195d6c3a --- /dev/null +++ b/sphinx/pycode/__init__.py @@ -0,0 +1,310 @@ +# -*- coding: utf-8 -*- +""" + sphinx.pycode + ~~~~~~~~~~~~~ + + Utilities parsing and analyzing Python code. + + :copyright: Copyright 2007-2009 by the Sphinx team, see AUTHORS. + :license: BSD, see LICENSE for details. +""" + +import re +import sys +from os import path +from cStringIO import StringIO + +from sphinx.pycode import nodes +from sphinx.pycode.pgen2 import driver, token, tokenize, parse, literals +from sphinx.util.docstrings import prepare_docstring, prepare_commentdoc + + +# load the Python grammar +_grammarfile = path.join(path.dirname(__file__), 'Grammar.txt') +pygrammar = driver.load_grammar(_grammarfile) +pydriver = driver.Driver(pygrammar, convert=nodes.convert) + +# an object with attributes corresponding to token and symbol names +class sym: pass +for k, v in pygrammar.symbol2number.iteritems(): + setattr(sym, k, v) +for k, v in token.tok_name.iteritems(): + setattr(sym, v, k) + +# a dict mapping terminal and nonterminal numbers to their names +number2name = pygrammar.number2symbol.copy() +number2name.update(token.tok_name) + + +# a regex to recognize coding cookies +_coding_re = re.compile(r'coding[:=]\s*([-\w.]+)') + +_eq = nodes.Leaf(token.EQUAL, '=') + + +class AttrDocVisitor(nodes.NodeVisitor): + """ + Visitor that collects docstrings for attribute assignments on toplevel and + in classes. + + 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.encoding = encoding + self.namespace = [] + self.collected = {} + + def visit_classdef(self, node): + self.namespace.append(node[1].value) + self.generic_visit(node) + self.namespace.pop() + + def visit_expr_stmt(self, node): + """Visit an assignment which may have a special comment before it.""" + if _eq not in node.children: + # not an assignment (we don't care for augmented assignments) + return + pnode = node[0] + prefix = pnode.get_prefix() + # if the assignment is the first statement on a new indentation + # level, its preceding whitespace and comments are not assigned + # to that token, but the first INDENT or DEDENT token + while not prefix: + pnode = pnode.get_prev_leaf() + if not pnode or pnode.type not in (token.INDENT, token.DEDENT): + break + prefix = pnode.get_prefix() + prefix = prefix.decode(self.encoding) + docstring = prepare_commentdoc(prefix) + if docstring: + self.add_docstring(node, docstring) + + def visit_simple_stmt(self, node): + """Visit a docstring statement which may have an assignment before.""" + if node[0].type != token.STRING: + # not a docstring; but still need to visit children + return self.generic_visit(node) + prev = node.get_prev_sibling() + if not prev: + return + if prev.type == sym.simple_stmt and \ + prev[0].type == sym.expr_stmt and _eq in prev[0].children: + # need to "eval" the string because it's returned in its + # original form + docstring = literals.evalString(node[0].value, self.encoding) + 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 + continue + namespace = '.'.join(self.namespace) + if namespace.startswith(self.scope): + self.collected[namespace, target.value] = docstring + + +class PycodeError(Exception): + def __str__(self): + res = self.args[0] + if len(self.args) > 1: + res += ' (exception was: %r)' % self.args[1] + return res + + +class ModuleAnalyzer(object): + # cache for analyzer objects -- caches both by module and file name + cache = {} + + @classmethod + def for_string(cls, string, modname, srcname='<string>'): + return cls(StringIO(string), modname, srcname) + + @classmethod + def for_file(cls, filename, modname): + if ('file', filename) in cls.cache: + return cls.cache['file', filename] + try: + fileobj = open(filename, 'r') + except Exception, err: + raise PycodeError('error opening %r' % filename, err) + obj = cls(fileobj, modname, filename) + cls.cache['file', filename] = obj + return obj + + @classmethod + def for_module(cls, modname): + if ('module', modname) in cls.cache: + entry = cls.cache['module', modname] + if isinstance(entry, PycodeError): + raise entry + return entry + + try: + if modname not in sys.modules: + try: + __import__(modname) + except ImportError, err: + raise PycodeError('error importing %r' % modname, err) + mod = sys.modules[modname] + if hasattr(mod, '__loader__'): + try: + source = mod.__loader__.get_source(modname) + except Exception, err: + raise PycodeError('error getting source for %r' % modname, + err) + obj = cls.for_string(source, modname) + cls.cache['module', modname] = obj + return obj + filename = getattr(mod, '__file__', None) + if filename is None: + raise PycodeError('no source found for module %r' % modname) + filename = path.normpath(filename) + lfilename = filename.lower() + if lfilename.endswith('.pyo') or lfilename.endswith('.pyc'): + filename = filename[:-1] + elif not lfilename.endswith('.py'): + raise PycodeError('source is not a .py file: %r' % filename) + if not path.isfile(filename): + raise PycodeError('source file is not present: %r' % filename) + obj = cls.for_file(filename, modname) + except PycodeError, err: + cls.cache['module', modname] = err + raise + cls.cache['module', modname] = obj + return obj + + def __init__(self, source, modname, srcname): + # name of the module + self.modname = modname + # name of the source file + self.srcname = srcname + # file-like object yielding source lines + self.source = source + + # will be filled by tokenize() + self.tokens = None + # will be filled by parse() + self.parsetree = None + # will be filled by find_attr_docs() + self.attr_docs = None + # will be filled by find_tags() + self.tags = None + + def tokenize(self): + """Generate tokens from the source.""" + if self.tokens is not None: + return + self.tokens = list(tokenize.generate_tokens(self.source.readline)) + self.source.close() + + def parse(self): + """Parse the generated source tokens.""" + if self.parsetree is not None: + return + self.tokenize() + try: + self.parsetree = pydriver.parse_tokens(self.tokens) + except parse.ParseError, err: + raise PycodeError('parsing failed', err) + # find the source code encoding + encoding = sys.getdefaultencoding() + comments = self.parsetree.get_prefix() + for line in comments.splitlines()[:2]: + match = _coding_re.search(line) + if match is not None: + encoding = match.group(1) + break + self.encoding = encoding + + def find_attr_docs(self, scope=''): + """Find class and module-level attributes and their documentation.""" + if self.attr_docs is not None: + return self.attr_docs + self.parse() + attr_visitor = AttrDocVisitor(number2name, scope, self.encoding) + attr_visitor.visit(self.parsetree) + self.attr_docs = attr_visitor.collected + return attr_visitor.collected + + def find_tags(self): + """Find class, function and method definitions and their location.""" + if self.tags is not None: + return self.tags + self.tokenize() + result = {} + namespace = [] + stack = [] + indent = 0 + defline = False + expect_indent = False + def tokeniter(ignore = (token.COMMENT, token.NL)): + for tokentup in self.tokens: + if tokentup[0] not in ignore: + yield tokentup + tokeniter = tokeniter() + for type, tok, spos, epos, line in tokeniter: + if expect_indent: + if type != token.INDENT: + # no suite -- one-line definition + assert stack + dtype, fullname, startline, _ = stack.pop() + endline = epos[0] + namespace.pop() + result[fullname] = (dtype, startline, endline) + expect_indent = False + if tok in ('def', 'class'): + name = tokeniter.next()[1] + namespace.append(name) + fullname = '.'.join(namespace) + stack.append((tok, fullname, spos[0], indent)) + defline = True + elif type == token.INDENT: + expect_indent = False + indent += 1 + elif type == token.DEDENT: + indent -= 1 + # if the stacklevel is the same as it was before the last + # def/class block, this dedent closes that block + if stack and indent == stack[-1][3]: + dtype, fullname, startline, _ = stack.pop() + endline = spos[0] + namespace.pop() + result[fullname] = (dtype, startline, endline) + elif type == token.NEWLINE: + # if this line contained a definition, expect an INDENT + # to start the suite; if there is no such INDENT + # it's a one-line definition + if defline: + defline = False + expect_indent = True + self.tags = result + return result + + +if __name__ == '__main__': + import time, pprint + x0 = time.time() + #ma = ModuleAnalyzer.for_file(__file__.rstrip('c'), 'sphinx.builders.html') + ma = ModuleAnalyzer.for_file('sphinx/builders/html.py', + 'sphinx.builders.html') + ma.tokenize() + x1 = time.time() + ma.parse() + x2 = time.time() + #for (ns, name), doc in ma.find_attr_docs().iteritems(): + # print '>>', ns, name + # print '\n'.join(doc) + pprint.pprint(ma.find_tags()) + x3 = time.time() + #print nodes.nice_repr(ma.parsetree, number2name) + print "tokenizing %.4f, parsing %.4f, finding %.4f" % (x1-x0, x2-x1, x3-x2) diff --git a/sphinx/pycode/nodes.py b/sphinx/pycode/nodes.py new file mode 100644 index 000000000..f8f57740e --- /dev/null +++ b/sphinx/pycode/nodes.py @@ -0,0 +1,205 @@ +# -*- coding: utf-8 -*- +""" + sphinx.pycode.nodes + ~~~~~~~~~~~~~~~~~~~ + + Parse tree node implementations. + + :copyright: Copyright 2007-2009 by the Sphinx team, see AUTHORS. + :license: BSD, see LICENSE for details. +""" + + +class BaseNode(object): + """ + Node superclass for both terminal and nonterminal nodes. + """ + parent = None + + def _eq(self, other): + raise NotImplementedError + + def __eq__(self, other): + if self.__class__ is not other.__class__: + return NotImplemented + return self._eq(other) + + def __ne__(self, other): + if self.__class__ is not other.__class__: + return NotImplemented + return not self._eq(other) + + def get_prev_sibling(self): + """Return previous child in parent's children, or None.""" + if self.parent is None: + return None + for i, child in enumerate(self.parent.children): + if child is self: + if i == 0: + return None + return self.parent.children[i-1] + + def get_next_sibling(self): + """Return next child in parent's children, or None.""" + if self.parent is None: + return None + for i, child in enumerate(self.parent.children): + if child is self: + try: + return self.parent.children[i+1] + except IndexError: + return None + + def get_prev_leaf(self): + """Return the leaf node that precedes this node in the parse tree.""" + def last_child(node): + if isinstance(node, Leaf): + return node + elif not node.children: + return None + else: + return last_child(node.children[-1]) + if self.parent is None: + return None + prev = self.get_prev_sibling() + if isinstance(prev, Leaf): + return prev + elif prev is not None: + return last_child(prev) + return self.parent.get_prev_leaf() + + def get_next_leaf(self): + """Return self if leaf, otherwise the leaf node that succeeds this + node in the parse tree. + """ + node = self + while not isinstance(node, Leaf): + assert node.children + node = node.children[0] + return node + + def get_lineno(self): + """Return the line number which generated the invocant node.""" + return self.get_next_leaf().lineno + + def get_prefix(self): + """Return the prefix of the next leaf node.""" + # only leaves carry a prefix + return self.get_next_leaf().prefix + + +class Node(BaseNode): + """ + Node implementation for nonterminals. + """ + + def __init__(self, type, children, context=None): + # type of nonterminals is >= 256 + # assert type >= 256, type + self.type = type + self.children = list(children) + for ch in self.children: + # assert ch.parent is None, repr(ch) + ch.parent = self + + def __repr__(self): + return '%s(%s, %r)' % (self.__class__.__name__, + self.type, self.children) + + def __str__(self): + """This reproduces the input source exactly.""" + return ''.join(map(str, self.children)) + + def _eq(self, other): + return (self.type, self.children) == (other.type, other.children) + + # support indexing the node directly instead of .children + + def __getitem__(self, index): + return self.children[index] + + def __iter__(self): + return iter(self.children) + + def __len__(self): + return len(self.children) + + +class Leaf(BaseNode): + """ + Node implementation for leaf nodes (terminals). + """ + prefix = '' # Whitespace and comments preceding this token in the input + lineno = 0 # Line where this token starts in the input + column = 0 # Column where this token tarts in the input + + def __init__(self, type, value, context=None): + # type of terminals is below 256 + # assert 0 <= type < 256, type + self.type = type + self.value = value + if context is not None: + self.prefix, (self.lineno, self.column) = context + + def __repr__(self): + return '%s(%r, %r, %r)' % (self.__class__.__name__, + self.type, self.value, self.prefix) + + def __str__(self): + """This reproduces the input source exactly.""" + return self.prefix + str(self.value) + + def _eq(self, other): + """Compares two nodes for equality.""" + return (self.type, self.value) == (other.type, other.value) + + +def convert(grammar, raw_node): + """Convert raw node to a Node or Leaf instance.""" + type, value, context, children = raw_node + if children or type in grammar.number2symbol: + # If there's exactly one child, return that child instead of + # creating a new node. + if len(children) == 1: + return children[0] + return Node(type, children, context=context) + else: + return Leaf(type, value, context=context) + + +def nice_repr(node, number2name, prefix=False): + def _repr(node): + if isinstance(node, Leaf): + return "%s(%r)" % (number2name[node.type], node.value) + else: + return "%s(%s)" % (number2name[node.type], + ', '.join(map(_repr, node.children))) + def _prepr(node): + if isinstance(node, Leaf): + return "%s(%r, %r)" % (number2name[node.type], + node.prefix, node.value) + else: + return "%s(%s)" % (number2name[node.type], + ', '.join(map(_prepr, node.children))) + return (prefix and _prepr or _repr)(node) + + +class NodeVisitor(object): + def __init__(self, number2name, *args): + self.number2name = number2name + self.init(*args) + + def init(self, *args): + pass + + def visit(self, node): + """Visit a node.""" + method = 'visit_' + self.number2name[node.type] + visitor = getattr(self, method, self.generic_visit) + return visitor(node) + + def generic_visit(self, node): + """Called if no explicit visitor function exists for a node.""" + if isinstance(node, Node): + for child in node: + self.visit(child) diff --git a/sphinx/pycode/pgen2/__init__.py b/sphinx/pycode/pgen2/__init__.py new file mode 100644 index 000000000..af3904845 --- /dev/null +++ b/sphinx/pycode/pgen2/__init__.py @@ -0,0 +1,4 @@ +# Copyright 2004-2005 Elemental Security, Inc. All Rights Reserved. +# Licensed to PSF under a Contributor Agreement. + +"""The pgen2 package.""" diff --git a/sphinx/pycode/pgen2/driver.py b/sphinx/pycode/pgen2/driver.py new file mode 100644 index 000000000..edc882fa2 --- /dev/null +++ b/sphinx/pycode/pgen2/driver.py @@ -0,0 +1,145 @@ +# Copyright 2004-2005 Elemental Security, Inc. All Rights Reserved. +# Licensed to PSF under a Contributor Agreement. + +# Modifications: +# Copyright 2006 Google, Inc. All Rights Reserved. +# Licensed to PSF under a Contributor Agreement. + +"""Parser driver. + +This provides a high-level interface to parse a file into a syntax tree. + +""" + +__author__ = "Guido van Rossum <guido@python.org>" + +__all__ = ["Driver", "load_grammar"] + +# Python imports +import os +import logging +import sys + +# Pgen imports +from sphinx.pycode.pgen2 import grammar, parse, token, tokenize, pgen + + +class Driver(object): + + def __init__(self, grammar, convert=None, logger=None): + self.grammar = grammar + if logger is None: + logger = logging.getLogger() + self.logger = logger + self.convert = convert + + def parse_tokens(self, tokens, debug=False): + """Parse a series of tokens and return the syntax tree.""" + # XXX Move the prefix computation into a wrapper around tokenize. + p = parse.Parser(self.grammar, self.convert) + p.setup() + lineno = 1 + column = 0 + type = value = start = end = line_text = None + prefix = "" + opmap = grammar.opmap + for type, value, start, end, line_text in tokens: + if start != (lineno, column): + assert (lineno, column) <= start, ((lineno, column), start) + s_lineno, s_column = start + if lineno < s_lineno: + prefix += "\n" * (s_lineno - lineno) + lineno = s_lineno + column = 0 + if column < s_column: + prefix += line_text[column:s_column] + column = s_column + if type in (tokenize.COMMENT, tokenize.NL): + prefix += value + lineno, column = end + if value.endswith("\n"): + lineno += 1 + column = 0 + continue + if type == token.OP: + type = opmap[value] + # if debug: + # self.logger.debug("%s %r (prefix=%r)", + # token.tok_name[type], value, prefix) + if p.addtoken(type, value, (prefix, start)): + # if debug: + # self.logger.debug("Stop.") + break + prefix = "" + lineno, column = end + if value.endswith("\n"): + lineno += 1 + column = 0 + else: + # We never broke out -- EOF is too soon (how can this happen???) + raise parse.ParseError("incomplete input", type, value, line_text) + return p.rootnode + + def parse_stream_raw(self, stream, debug=False): + """Parse a stream and return the syntax tree.""" + tokens = tokenize.generate_tokens(stream.readline) + return self.parse_tokens(tokens, debug) + + def parse_stream(self, stream, debug=False): + """Parse a stream and return the syntax tree.""" + return self.parse_stream_raw(stream, debug) + + def parse_file(self, filename, debug=False): + """Parse a file and return the syntax tree.""" + stream = open(filename) + try: + return self.parse_stream(stream, debug) + finally: + stream.close() + + def parse_string(self, text, debug=False): + """Parse a string and return the syntax tree.""" + tokens = tokenize.generate_tokens(generate_lines(text).next) + return self.parse_tokens(tokens, debug) + + +def generate_lines(text): + """Generator that behaves like readline without using StringIO.""" + for line in text.splitlines(True): + yield line + while True: + yield "" + + +def load_grammar(gt="Grammar.txt", gp=None, + save=True, force=False, logger=None): + """Load the grammar (maybe from a pickle).""" + if logger is None: + logger = logging.getLogger() + if gp is None: + head, tail = os.path.splitext(gt) + if tail == ".txt": + tail = "" + gp = head + tail + ".".join(map(str, sys.version_info)) + ".pickle" + if force or not _newer(gp, gt): + logger.info("Generating grammar tables from %s", gt) + g = pgen.generate_grammar(gt) + if save: + logger.info("Writing grammar tables to %s", gp) + try: + g.dump(gp) + except IOError, e: + logger.info("Writing failed:"+str(e)) + else: + g = grammar.Grammar() + g.load(gp) + return g + + +def _newer(a, b): + """Inquire whether file a was written since file b.""" + if not os.path.exists(a): + return False + if not os.path.exists(b): + return True + return os.path.getmtime(a) >= os.path.getmtime(b) diff --git a/sphinx/pycode/pgen2/grammar.py b/sphinx/pycode/pgen2/grammar.py new file mode 100644 index 000000000..381d80e82 --- /dev/null +++ b/sphinx/pycode/pgen2/grammar.py @@ -0,0 +1,171 @@ +# Copyright 2004-2005 Elemental Security, Inc. All Rights Reserved. +# Licensed to PSF under a Contributor Agreement. + +"""This module defines the data structures used to represent a grammar. + +These are a bit arcane because they are derived from the data +structures used by Python's 'pgen' parser generator. + +There's also a table here mapping operators to their names in the +token module; the Python tokenize module reports all operators as the +fallback token code OP, but the parser needs the actual token code. + +""" + +# Python imports +import pickle + +# Local imports +from sphinx.pycode.pgen2 import token, tokenize + + +class Grammar(object): + """Pgen parsing tables tables conversion class. + + Once initialized, this class supplies the grammar tables for the + parsing engine implemented by parse.py. The parsing engine + accesses the instance variables directly. The class here does not + provide initialization of the tables; several subclasses exist to + do this (see the conv and pgen modules). + + The load() method reads the tables from a pickle file, which is + much faster than the other ways offered by subclasses. The pickle + file is written by calling dump() (after loading the grammar + tables using a subclass). The report() method prints a readable + representation of the tables to stdout, for debugging. + + The instance variables are as follows: + + symbol2number -- a dict mapping symbol names to numbers. Symbol + numbers are always 256 or higher, to distinguish + them from token numbers, which are between 0 and + 255 (inclusive). + + number2symbol -- a dict mapping numbers to symbol names; + these two are each other's inverse. + + states -- a list of DFAs, where each DFA is a list of + states, each state is is a list of arcs, and each + arc is a (i, j) pair where i is a label and j is + a state number. The DFA number is the index into + this list. (This name is slightly confusing.) + Final states are represented by a special arc of + the form (0, j) where j is its own state number. + + dfas -- a dict mapping symbol numbers to (DFA, first) + pairs, where DFA is an item from the states list + above, and first is a set of tokens that can + begin this grammar rule (represented by a dict + whose values are always 1). + + labels -- a list of (x, y) pairs where x is either a token + number or a symbol number, and y is either None + or a string; the strings are keywords. The label + number is the index in this list; label numbers + are used to mark state transitions (arcs) in the + DFAs. + + start -- the number of the grammar's start symbol. + + keywords -- a dict mapping keyword strings to arc labels. + + tokens -- a dict mapping token numbers to arc labels. + + """ + + def __init__(self): + self.symbol2number = {} + self.number2symbol = {} + self.states = [] + self.dfas = {} + self.labels = [(0, "EMPTY")] + self.keywords = {} + self.tokens = {} + self.symbol2label = {} + self.start = 256 + + def dump(self, filename): + """Dump the grammar tables to a pickle file.""" + f = open(filename, "wb") + pickle.dump(self.__dict__, f, 2) + f.close() + + def load(self, filename): + """Load the grammar tables from a pickle file.""" + f = open(filename, "rb") + d = pickle.load(f) + f.close() + self.__dict__.update(d) + + def report(self): + """Dump the grammar tables to standard output, for debugging.""" + from pprint import pprint + print "s2n" + pprint(self.symbol2number) + print "n2s" + pprint(self.number2symbol) + print "states" + pprint(self.states) + print "dfas" + pprint(self.dfas) + print "labels" + pprint(self.labels) + print "start", self.start + + +# Map from operator to number (since tokenize doesn't do this) + +opmap_raw = """ +( LPAR +) RPAR +[ LSQB +] RSQB +: COLON +, COMMA +; SEMI ++ PLUS +- MINUS +* STAR +/ SLASH +| VBAR +& AMPER +< LESS +> GREATER += EQUAL +. DOT +% PERCENT +` BACKQUOTE +{ LBRACE +} RBRACE +@ AT +== EQEQUAL +!= NOTEQUAL +<> NOTEQUAL +<= LESSEQUAL +>= GREATEREQUAL +~ TILDE +^ CIRCUMFLEX +<< LEFTSHIFT +>> RIGHTSHIFT +** DOUBLESTAR ++= PLUSEQUAL +-= MINEQUAL +*= STAREQUAL +/= SLASHEQUAL +%= PERCENTEQUAL +&= AMPEREQUAL +|= VBAREQUAL +^= CIRCUMFLEXEQUAL +<<= LEFTSHIFTEQUAL +>>= RIGHTSHIFTEQUAL +**= DOUBLESTAREQUAL +// DOUBLESLASH +//= DOUBLESLASHEQUAL +-> RARROW +""" + +opmap = {} +for line in opmap_raw.splitlines(): + if line: + op, name = line.split() + opmap[op] = getattr(token, name) diff --git a/sphinx/pycode/pgen2/literals.py b/sphinx/pycode/pgen2/literals.py new file mode 100644 index 000000000..319002910 --- /dev/null +++ b/sphinx/pycode/pgen2/literals.py @@ -0,0 +1,96 @@ +# Copyright 2004-2005 Elemental Security, Inc. All Rights Reserved. +# Licensed to PSF under a Contributor Agreement. + +# Extended to handle raw and unicode literals by Georg Brandl. + +"""Safely evaluate Python string literals without using eval().""" + +import re + +simple_escapes = {"a": "\a", + "b": "\b", + "f": "\f", + "n": "\n", + "r": "\r", + "t": "\t", + "v": "\v", + "'": "'", + '"': '"', + "\\": "\\"} + +def convert_hex(x, n): + if len(x) < n+1: + raise ValueError("invalid hex string escape ('\\%s')" % x) + try: + return int(x[1:], 16) + except ValueError: + raise ValueError("invalid hex string escape ('\\%s')" % x) + +def escape(m): + all, tail = m.group(0, 1) + assert all.startswith("\\") + esc = simple_escapes.get(tail) + if esc is not None: + return esc + elif tail.startswith("x"): + return chr(convert_hex(tail, 2)) + elif tail.startswith('u'): + return unichr(convert_hex(tail, 4)) + elif tail.startswith('U'): + return unichr(convert_hex(tail, 8)) + elif tail.startswith('N'): + import unicodedata + try: + return unicodedata.lookup(tail[1:-1]) + except KeyError: + raise ValueError("undefined character name %r" % tail[1:-1]) + else: + try: + return chr(int(tail, 8)) + except ValueError: + raise ValueError("invalid octal string escape ('\\%s')" % tail) + +def escaperaw(m): + all, tail = m.group(0, 1) + if tail.startswith('u'): + return unichr(convert_hex(tail, 4)) + elif tail.startswith('U'): + return unichr(convert_hex(tail, 8)) + else: + return all + +escape_re = re.compile(r"\\(\'|\"|\\|[abfnrtv]|x.{0,2}|[0-7]{1,3})") +uni_escape_re = re.compile(r"\\(\'|\"|\\|[abfnrtv]|x.{0,2}|[0-7]{1,3}|" + r"u[0-9a-fA-F]{0,4}|U[0-9a-fA-F]{0,8}|N\{.+?\})") + +def evalString(s, encoding=None): + regex = escape_re + repl = escape + if encoding: + s = s.decode(encoding) + if s.startswith('u') or s.startswith('U'): + regex = uni_escape_re + s = s[1:] + if s.startswith('r') or s.startswith('R'): + repl = escaperaw + s = s[1:] + assert s.startswith("'") or s.startswith('"'), repr(s[:1]) + q = s[0] + if s[:3] == q*3: + q = q*3 + assert s.endswith(q), repr(s[-len(q):]) + assert len(s) >= 2*len(q) + s = s[len(q):-len(q)] + return regex.sub(repl, s) + +def test(): + for i in range(256): + c = chr(i) + s = repr(c) + e = evalString(s) + if e != c: + print i, c, s, e + + +if __name__ == "__main__": + test() diff --git a/sphinx/pycode/pgen2/parse.c b/sphinx/pycode/pgen2/parse.c new file mode 100644 index 000000000..fd0e9ff94 --- /dev/null +++ b/sphinx/pycode/pgen2/parse.c @@ -0,0 +1,3261 @@ +/* Generated by Cython 0.9.8.1 on Thu Jan 1 23:45:38 2009 */ + +#define PY_SSIZE_T_CLEAN +#include "Python.h" +#include "structmember.h" +#ifndef PY_LONG_LONG + #define PY_LONG_LONG LONG_LONG +#endif +#ifndef DL_EXPORT + #define DL_EXPORT(t) t +#endif +#if PY_VERSION_HEX < 0x02040000 + #define METH_COEXIST 0 +#endif +#if PY_VERSION_HEX < 0x02050000 + typedef int Py_ssize_t; + #define PY_SSIZE_T_MAX INT_MAX + #define PY_SSIZE_T_MIN INT_MIN + #define PyInt_FromSsize_t(z) PyInt_FromLong(z) + #define PyInt_AsSsize_t(o) PyInt_AsLong(o) + #define PyNumber_Index(o) PyNumber_Int(o) + #define PyIndex_Check(o) PyNumber_Check(o) +#endif +#if PY_VERSION_HEX < 0x02060000 + #define Py_REFCNT(ob) (((PyObject*)(ob))->ob_refcnt) + #define Py_TYPE(ob) (((PyObject*)(ob))->ob_type) + #define Py_SIZE(ob) (((PyVarObject*)(ob))->ob_size) + #define PyVarObject_HEAD_INIT(type, size) \ + PyObject_HEAD_INIT(type) size, + #define PyType_Modified(t) + + typedef struct { + void *buf; + Py_ssize_t len; + int readonly; + const char *format; + int ndim; + Py_ssize_t *shape; + Py_ssize_t *strides; + Py_ssize_t *suboffsets; + Py_ssize_t itemsize; + void *internal; + } Py_buffer; + + #define PyBUF_SIMPLE 0 + #define PyBUF_WRITABLE 0x0001 + #define PyBUF_LOCK 0x0002 + #define PyBUF_FORMAT 0x0004 + #define PyBUF_ND 0x0008 + #define PyBUF_STRIDES (0x0010 | PyBUF_ND) + #define PyBUF_C_CONTIGUOUS (0x0020 | PyBUF_STRIDES) + #define PyBUF_F_CONTIGUOUS (0x0040 | PyBUF_STRIDES) + #define PyBUF_ANY_CONTIGUOUS (0x0080 | PyBUF_STRIDES) + #define PyBUF_INDIRECT (0x0100 | PyBUF_STRIDES) + +#endif +#if PY_MAJOR_VERSION < 3 + #define __Pyx_BUILTIN_MODULE_NAME "__builtin__" +#else + #define __Pyx_BUILTIN_MODULE_NAME "builtins" +#endif +#if PY_MAJOR_VERSION >= 3 + #define Py_TPFLAGS_CHECKTYPES 0 + #define Py_TPFLAGS_HAVE_INDEX 0 +#endif +#if PY_MAJOR_VERSION >= 3 + #define PyBaseString_Type PyUnicode_Type + #define PyString_Type PyBytes_Type + #define PyInt_Type PyLong_Type + #define PyInt_Check(op) PyLong_Check(op) + #define PyInt_CheckExact(op) PyLong_CheckExact(op) + #define PyInt_FromString PyLong_FromString + #define PyInt_FromUnicode PyLong_FromUnicode + #define PyInt_FromLong PyLong_FromLong + #define PyInt_FromSize_t PyLong_FromSize_t + #define PyInt_FromSsize_t PyLong_FromSsize_t + #define PyInt_AsLong PyLong_AsLong + #define PyInt_AS_LONG PyLong_AS_LONG + #define PyInt_AsSsize_t PyLong_AsSsize_t + #define PyInt_AsUnsignedLongMask PyLong_AsUnsignedLongMask + #define PyInt_AsUnsignedLongLongMask PyLong_AsUnsignedLongLongMask + #define __Pyx_PyNumber_Divide(x,y) PyNumber_TrueDivide(x,y) +#else + #define __Pyx_PyNumber_Divide(x,y) PyNumber_Divide(x,y) + #define PyBytes_Type PyString_Type +#endif +#if PY_MAJOR_VERSION >= 3 + #define PyMethod_New(func, self, klass) PyInstanceMethod_New(func) +#endif +#if !defined(WIN32) && !defined(MS_WINDOWS) + #ifndef __stdcall + #define __stdcall + #endif + #ifndef __cdecl + #define __cdecl + #endif +#else + #define _USE_MATH_DEFINES +#endif +#ifdef __cplusplus +#define __PYX_EXTERN_C extern "C" +#else +#define __PYX_EXTERN_C extern +#endif +#include <math.h> +#define __PYX_HAVE_API__sphinx__pycode__pgen2__parse + + +#ifdef __GNUC__ +#define INLINE __inline__ +#elif _WIN32 +#define INLINE __inline +#else +#define INLINE +#endif + +typedef struct {PyObject **p; char *s; long n; char is_unicode; char intern; char is_identifier;} __Pyx_StringTabEntry; /*proto*/ + + + +static int __pyx_skip_dispatch = 0; + + +/* Type Conversion Predeclarations */ + +#if PY_MAJOR_VERSION < 3 +#define __Pyx_PyBytes_FromString PyString_FromString +#define __Pyx_PyBytes_AsString PyString_AsString +#else +#define __Pyx_PyBytes_FromString PyBytes_FromString +#define __Pyx_PyBytes_AsString PyBytes_AsString +#endif + +#define __Pyx_PyBool_FromLong(b) ((b) ? (Py_INCREF(Py_True), Py_True) : (Py_INCREF(Py_False), Py_False)) +static INLINE int __Pyx_PyObject_IsTrue(PyObject* x); +static INLINE PY_LONG_LONG __pyx_PyInt_AsLongLong(PyObject* x); +static INLINE unsigned PY_LONG_LONG __pyx_PyInt_AsUnsignedLongLong(PyObject* x); +static INLINE Py_ssize_t __pyx_PyIndex_AsSsize_t(PyObject* b); + +#define __pyx_PyInt_AsLong(x) (PyInt_CheckExact(x) ? PyInt_AS_LONG(x) : PyInt_AsLong(x)) +#define __pyx_PyFloat_AsDouble(x) (PyFloat_CheckExact(x) ? PyFloat_AS_DOUBLE(x) : PyFloat_AsDouble(x)) + +static INLINE unsigned char __pyx_PyInt_unsigned_char(PyObject* x); +static INLINE unsigned short __pyx_PyInt_unsigned_short(PyObject* x); +static INLINE char __pyx_PyInt_char(PyObject* x); +static INLINE short __pyx_PyInt_short(PyObject* x); +static INLINE int __pyx_PyInt_int(PyObject* x); +static INLINE long __pyx_PyInt_long(PyObject* x); +static INLINE signed char __pyx_PyInt_signed_char(PyObject* x); +static INLINE signed short __pyx_PyInt_signed_short(PyObject* x); +static INLINE signed int __pyx_PyInt_signed_int(PyObject* x); +static INLINE signed long __pyx_PyInt_signed_long(PyObject* x); +static INLINE long double __pyx_PyInt_long_double(PyObject* x); +#ifdef __GNUC__ +/* Test for GCC > 2.95 */ +#if __GNUC__ > 2 || (__GNUC__ == 2 && (__GNUC_MINOR__ > 95)) +#define likely(x) __builtin_expect(!!(x), 1) +#define unlikely(x) __builtin_expect(!!(x), 0) +#else /* __GNUC__ > 2 ... */ +#define likely(x) (x) +#define unlikely(x) (x) +#endif /* __GNUC__ > 2 ... */ +#else /* __GNUC__ */ +#define likely(x) (x) +#define unlikely(x) (x) +#endif /* __GNUC__ */ + +static PyObject *__pyx_m; +static PyObject *__pyx_b; +static PyObject *__pyx_empty_tuple; +static int __pyx_lineno; +static int __pyx_clineno = 0; +static const char * __pyx_cfilenm= __FILE__; +static const char *__pyx_filename; +static const char **__pyx_f; + +static INLINE void __Pyx_RaiseArgtupleTooLong(Py_ssize_t num_expected, Py_ssize_t num_found); /*proto*/ + +static PyObject *__Pyx_Import(PyObject *name, PyObject *from_list); /*proto*/ + +static PyObject *__Pyx_GetName(PyObject *dict, PyObject *name); /*proto*/ + +static PyObject *__Pyx_CreateClass(PyObject *bases, PyObject *dict, PyObject *name, char *modname); /*proto*/ + +static INLINE PyObject *__Pyx_GetItemInt(PyObject *o, Py_ssize_t i, int is_unsigned) { + PyObject *r; + if (PyList_CheckExact(o) && 0 <= i && i < PyList_GET_SIZE(o)) { + r = PyList_GET_ITEM(o, i); + Py_INCREF(r); + } + else if (PyTuple_CheckExact(o) && 0 <= i && i < PyTuple_GET_SIZE(o)) { + r = PyTuple_GET_ITEM(o, i); + Py_INCREF(r); + } + else if (Py_TYPE(o)->tp_as_sequence && Py_TYPE(o)->tp_as_sequence->sq_item && (likely(i >= 0) || !is_unsigned)) + r = PySequence_GetItem(o, i); + else { + PyObject *j = (likely(i >= 0) || !is_unsigned) ? PyInt_FromLong(i) : PyLong_FromUnsignedLongLong((sizeof(unsigned long long) > sizeof(Py_ssize_t) ? (1ULL << (sizeof(Py_ssize_t)*8)) : 0) + i); + if (!j) + return 0; + r = PyObject_GetItem(o, j); + Py_DECREF(j); + } + return r; +} + +static PyObject *__Pyx_UnpackItem(PyObject *, Py_ssize_t index); /*proto*/ +static int __Pyx_EndUnpack(PyObject *); /*proto*/ + +static void __Pyx_Raise(PyObject *type, PyObject *value, PyObject *tb); /*proto*/ + +static INLINE PyObject* __Pyx_PyObject_Append(PyObject* L, PyObject* x) { + if (likely(PyList_CheckExact(L))) { + if (PyList_Append(L, x) < 0) return NULL; + Py_INCREF(Py_None); + return Py_None; // this is just to have an accurate signature + } + else { + return PyObject_CallMethod(L, "append", "(O)", x); + } +} + +static INLINE int __Pyx_SetItemInt(PyObject *o, Py_ssize_t i, PyObject *v, int is_unsigned) { + int r; + if (PyList_CheckExact(o) && 0 <= i && i < PyList_GET_SIZE(o)) { + Py_DECREF(PyList_GET_ITEM(o, i)); + Py_INCREF(v); + PyList_SET_ITEM(o, i, v); + return 1; + } + else if (Py_TYPE(o)->tp_as_sequence && Py_TYPE(o)->tp_as_sequence->sq_ass_item && (likely(i >= 0) || !is_unsigned)) + r = PySequence_SetItem(o, i, v); + else { + PyObject *j = (likely(i >= 0) || !is_unsigned) ? PyInt_FromLong(i) : PyLong_FromUnsignedLongLong((sizeof(unsigned long long) > sizeof(Py_ssize_t) ? (1ULL << (sizeof(Py_ssize_t)*8)) : 0) + i); + if (!j) + return -1; + r = PyObject_SetItem(o, j, v); + Py_DECREF(j); + } + return r; +} + +static void __Pyx_WriteUnraisable(const char *name); /*proto*/ + +static int __Pyx_SetVtable(PyObject *dict, void *vtable); /*proto*/ + +static void __Pyx_AddTraceback(const char *funcname); /*proto*/ + +static int __Pyx_InitStrings(__Pyx_StringTabEntry *t); /*proto*/ + +/* Type declarations */ + +/* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":31 + * + * + * cdef class Parser: # <<<<<<<<<<<<<< + * cdef public grammar, stack, rootnode, used_names + * cdef _grammar_dfas, _grammar_labels, _grammar_keywords, _grammar_tokens + */ + +struct __pyx_obj_6sphinx_6pycode_5pgen2_5parse_Parser { + PyObject_HEAD + struct __pyx_vtabstruct_6sphinx_6pycode_5pgen2_5parse_Parser *__pyx_vtab; + PyObject *grammar; + PyObject *stack; + PyObject *rootnode; + PyObject *used_names; + PyObject *_grammar_dfas; + PyObject *_grammar_labels; + PyObject *_grammar_keywords; + PyObject *_grammar_tokens; + PyObject *_grammar_number2symbol; +}; + + +struct __pyx_vtabstruct_6sphinx_6pycode_5pgen2_5parse_Parser { + int (*classify)(struct __pyx_obj_6sphinx_6pycode_5pgen2_5parse_Parser *, PyObject *, PyObject *, PyObject *); + void (*shift)(struct __pyx_obj_6sphinx_6pycode_5pgen2_5parse_Parser *, PyObject *, PyObject *, PyObject *, PyObject *); + void (*push)(struct __pyx_obj_6sphinx_6pycode_5pgen2_5parse_Parser *, PyObject *, PyObject *, PyObject *, PyObject *); + void (*pop)(struct __pyx_obj_6sphinx_6pycode_5pgen2_5parse_Parser *); + PyObject *(*convert)(struct __pyx_obj_6sphinx_6pycode_5pgen2_5parse_Parser *, PyObject *); +}; +static struct __pyx_vtabstruct_6sphinx_6pycode_5pgen2_5parse_Parser *__pyx_vtabptr_6sphinx_6pycode_5pgen2_5parse_Parser; +/* Module declarations from sphinx.pycode.pgen2.parse */ + +static PyTypeObject *__pyx_ptype_6sphinx_6pycode_5pgen2_5parse_Parser = 0; + + +/* Implementation of sphinx.pycode.pgen2.parse */ +static char __pyx_k_2[] = "Exception to signal the parser is stuck."; +static PyObject *__pyx_int_0; +static PyObject *__pyx_int_1; +static char __pyx_k___init__[] = "__init__"; +static PyObject *__pyx_kp___init__; +static char __pyx_k_setup[] = "setup"; +static PyObject *__pyx_kp_setup; +static char __pyx_k_addtoken[] = "addtoken"; +static PyObject *__pyx_kp_addtoken; +static char __pyx_k_1[] = "sphinx.pycode.nodes"; +static PyObject *__pyx_kp_1; +static char __pyx_k_Node[] = "Node"; +static PyObject *__pyx_kp_Node; +static char __pyx_k_Leaf[] = "Leaf"; +static PyObject *__pyx_kp_Leaf; +static char __pyx_k_ParseError[] = "ParseError"; +static PyObject *__pyx_kp_ParseError; +static char __pyx_k_Exception[] = "Exception"; +static PyObject *__pyx_kp_Exception; +static char __pyx_k_msg[] = "msg"; +static PyObject *__pyx_kp_msg; +static char __pyx_k_type[] = "type"; +static PyObject *__pyx_kp_type; +static char __pyx_k_value[] = "value"; +static PyObject *__pyx_kp_value; +static char __pyx_k_context[] = "context"; +static PyObject *__pyx_kp_context; +static char __pyx_k_dfas[] = "dfas"; +static PyObject *__pyx_kp_dfas; +static char __pyx_k_labels[] = "labels"; +static PyObject *__pyx_kp_labels; +static char __pyx_k_keywords[] = "keywords"; +static PyObject *__pyx_kp_keywords; +static char __pyx_k_tokens[] = "tokens"; +static PyObject *__pyx_kp_tokens; +static char __pyx_k_4[] = "number2symbol"; +static PyObject *__pyx_kp_4; +static char __pyx_k_start[] = "start"; +static PyObject *__pyx_kp_start; +static char __pyx_k_add[] = "add"; +static PyObject *__pyx_kp_add; +static char __pyx_k_get[] = "get"; +static PyObject *__pyx_kp_get; +static char __pyx_k_append[] = "append"; +static PyObject *__pyx_kp_append; +static char __pyx_k_pop[] = "pop"; +static PyObject *__pyx_kp_pop; +static char __pyx_k_used_names[] = "used_names"; +static PyObject *__pyx_kp_used_names; +static PyObject *__pyx_kp_2; +static PyObject *__pyx_builtin_Exception; +static PyObject *__pyx_kp_3; +static char __pyx_k_3[] = "%s: type=%r, value=%r, context=%r"; +static PyObject *__pyx_kp_5; +static PyObject *__pyx_kp_6; +static char __pyx_k_5[] = "too much input"; +static char __pyx_k_6[] = "bad input"; +static PyObject *__pyx_kp_7; +static char __pyx_k_7[] = "bad token"; + +/* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":22 + * """Exception to signal the parser is stuck.""" + * + * def __init__(self, msg, type, value, context): # <<<<<<<<<<<<<< + * Exception.__init__(self, "%s: type=%r, value=%r, context=%r" % + * (msg, type, value, context)) + */ + +static PyObject *__pyx_pf_6sphinx_6pycode_5pgen2_5parse_10ParseError___init__(PyObject *__pyx_self, PyObject *__pyx_args, PyObject *__pyx_kwds); /*proto*/ +static PyMethodDef __pyx_mdef_6sphinx_6pycode_5pgen2_5parse_10ParseError___init__ = {"__init__", (PyCFunction)__pyx_pf_6sphinx_6pycode_5pgen2_5parse_10ParseError___init__, METH_VARARGS|METH_KEYWORDS, 0}; +static PyObject *__pyx_pf_6sphinx_6pycode_5pgen2_5parse_10ParseError___init__(PyObject *__pyx_self, PyObject *__pyx_args, PyObject *__pyx_kwds) { + PyObject *__pyx_v_self = 0; + PyObject *__pyx_v_msg = 0; + PyObject *__pyx_v_type = 0; + PyObject *__pyx_v_value = 0; + PyObject *__pyx_v_context = 0; + PyObject *__pyx_r; + PyObject *__pyx_1 = 0; + PyObject *__pyx_2 = 0; + PyObject *__pyx_3 = 0; + static char *__pyx_argnames[] = {"self","msg","type","value","context",0}; + __pyx_self = __pyx_self; + if (likely(!__pyx_kwds) && likely(PyTuple_GET_SIZE(__pyx_args) == 5)) { + __pyx_v_self = PyTuple_GET_ITEM(__pyx_args, 0); + __pyx_v_msg = PyTuple_GET_ITEM(__pyx_args, 1); + __pyx_v_type = PyTuple_GET_ITEM(__pyx_args, 2); + __pyx_v_value = PyTuple_GET_ITEM(__pyx_args, 3); + __pyx_v_context = PyTuple_GET_ITEM(__pyx_args, 4); + } + else { + if (unlikely(!PyArg_ParseTupleAndKeywords(__pyx_args, __pyx_kwds, "OOOOO", __pyx_argnames, &__pyx_v_self, &__pyx_v_msg, &__pyx_v_type, &__pyx_v_value, &__pyx_v_context))) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 22; __pyx_clineno = __LINE__; goto __pyx_L3_error;} + } + goto __pyx_L4; + __pyx_L3_error:; + __Pyx_AddTraceback("sphinx.pycode.pgen2.parse.ParseError.__init__"); + return NULL; + __pyx_L4:; + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":23 + * + * def __init__(self, msg, type, value, context): + * Exception.__init__(self, "%s: type=%r, value=%r, context=%r" % # <<<<<<<<<<<<<< + * (msg, type, value, context)) + * self.msg = msg + */ + __pyx_1 = PyObject_GetAttr(__pyx_builtin_Exception, __pyx_kp___init__); if (unlikely(!__pyx_1)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 23; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":24 + * def __init__(self, msg, type, value, context): + * Exception.__init__(self, "%s: type=%r, value=%r, context=%r" % + * (msg, type, value, context)) # <<<<<<<<<<<<<< + * self.msg = msg + * self.type = type + */ + __pyx_2 = PyTuple_New(4); if (unlikely(!__pyx_2)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 24; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_INCREF(__pyx_v_msg); + PyTuple_SET_ITEM(__pyx_2, 0, __pyx_v_msg); + Py_INCREF(__pyx_v_type); + PyTuple_SET_ITEM(__pyx_2, 1, __pyx_v_type); + Py_INCREF(__pyx_v_value); + PyTuple_SET_ITEM(__pyx_2, 2, __pyx_v_value); + Py_INCREF(__pyx_v_context); + PyTuple_SET_ITEM(__pyx_2, 3, __pyx_v_context); + __pyx_3 = PyNumber_Remainder(__pyx_kp_3, ((PyObject *)__pyx_2)); if (unlikely(!__pyx_3)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 23; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(((PyObject *)__pyx_2)); __pyx_2 = 0; + __pyx_2 = PyTuple_New(2); if (unlikely(!__pyx_2)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 23; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_INCREF(__pyx_v_self); + PyTuple_SET_ITEM(__pyx_2, 0, __pyx_v_self); + PyTuple_SET_ITEM(__pyx_2, 1, __pyx_3); + __pyx_3 = 0; + __pyx_3 = PyObject_Call(__pyx_1, ((PyObject *)__pyx_2), NULL); if (unlikely(!__pyx_3)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 23; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_1); __pyx_1 = 0; + Py_DECREF(((PyObject *)__pyx_2)); __pyx_2 = 0; + Py_DECREF(__pyx_3); __pyx_3 = 0; + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":25 + * Exception.__init__(self, "%s: type=%r, value=%r, context=%r" % + * (msg, type, value, context)) + * self.msg = msg # <<<<<<<<<<<<<< + * self.type = type + * self.value = value + */ + if (PyObject_SetAttr(__pyx_v_self, __pyx_kp_msg, __pyx_v_msg) < 0) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 25; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":26 + * (msg, type, value, context)) + * self.msg = msg + * self.type = type # <<<<<<<<<<<<<< + * self.value = value + * self.context = context + */ + if (PyObject_SetAttr(__pyx_v_self, __pyx_kp_type, __pyx_v_type) < 0) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 26; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":27 + * self.msg = msg + * self.type = type + * self.value = value # <<<<<<<<<<<<<< + * self.context = context + * + */ + if (PyObject_SetAttr(__pyx_v_self, __pyx_kp_value, __pyx_v_value) < 0) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 27; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":28 + * self.type = type + * self.value = value + * self.context = context # <<<<<<<<<<<<<< + * + * + */ + if (PyObject_SetAttr(__pyx_v_self, __pyx_kp_context, __pyx_v_context) < 0) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 28; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + + __pyx_r = Py_None; Py_INCREF(Py_None); + goto __pyx_L0; + __pyx_L1_error:; + Py_XDECREF(__pyx_1); + Py_XDECREF(__pyx_2); + Py_XDECREF(__pyx_3); + __Pyx_AddTraceback("sphinx.pycode.pgen2.parse.ParseError.__init__"); + __pyx_r = NULL; + __pyx_L0:; + return __pyx_r; +} + +/* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":36 + * cdef _grammar_number2symbol + * + * def __init__(self, grammar, convert=None): # <<<<<<<<<<<<<< + * self.grammar = grammar + * #self.convert = convert or noconvert + */ + +static int __pyx_pf_6sphinx_6pycode_5pgen2_5parse_6Parser___init__(PyObject *__pyx_v_self, PyObject *__pyx_args, PyObject *__pyx_kwds); /*proto*/ +static int __pyx_pf_6sphinx_6pycode_5pgen2_5parse_6Parser___init__(PyObject *__pyx_v_self, PyObject *__pyx_args, PyObject *__pyx_kwds) { + PyObject *__pyx_v_grammar = 0; + PyObject *__pyx_v_convert = 0; + int __pyx_r; + PyObject *__pyx_1 = 0; + static char *__pyx_argnames[] = {"grammar","convert",0}; + __pyx_v_convert = Py_None; + if (likely(!__pyx_kwds) && likely(1 <= PyTuple_GET_SIZE(__pyx_args)) && likely(PyTuple_GET_SIZE(__pyx_args) <= 2)) { + __pyx_v_grammar = PyTuple_GET_ITEM(__pyx_args, 0); + if (PyTuple_GET_SIZE(__pyx_args) > 1) { + __pyx_v_convert = PyTuple_GET_ITEM(__pyx_args, 1); + } + } + else { + if (unlikely(!PyArg_ParseTupleAndKeywords(__pyx_args, __pyx_kwds, "O|O", __pyx_argnames, &__pyx_v_grammar, &__pyx_v_convert))) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 36; __pyx_clineno = __LINE__; goto __pyx_L3_error;} + } + goto __pyx_L4; + __pyx_L3_error:; + __Pyx_AddTraceback("sphinx.pycode.pgen2.parse.Parser.__init__"); + return -1; + __pyx_L4:; + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":37 + * + * def __init__(self, grammar, convert=None): + * self.grammar = grammar # <<<<<<<<<<<<<< + * #self.convert = convert or noconvert + * + */ + Py_INCREF(__pyx_v_grammar); + Py_DECREF(((struct __pyx_obj_6sphinx_6pycode_5pgen2_5parse_Parser *)__pyx_v_self)->grammar); + ((struct __pyx_obj_6sphinx_6pycode_5pgen2_5parse_Parser *)__pyx_v_self)->grammar = __pyx_v_grammar; + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":40 + * #self.convert = convert or noconvert + * + * self._grammar_dfas = grammar.dfas # <<<<<<<<<<<<<< + * self._grammar_labels = grammar.labels + * self._grammar_keywords = grammar.keywords + */ + __pyx_1 = PyObject_GetAttr(__pyx_v_grammar, __pyx_kp_dfas); if (unlikely(!__pyx_1)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 40; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(((struct __pyx_obj_6sphinx_6pycode_5pgen2_5parse_Parser *)__pyx_v_self)->_grammar_dfas); + ((struct __pyx_obj_6sphinx_6pycode_5pgen2_5parse_Parser *)__pyx_v_self)->_grammar_dfas = __pyx_1; + __pyx_1 = 0; + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":41 + * + * self._grammar_dfas = grammar.dfas + * self._grammar_labels = grammar.labels # <<<<<<<<<<<<<< + * self._grammar_keywords = grammar.keywords + * self._grammar_tokens = grammar.tokens + */ + __pyx_1 = PyObject_GetAttr(__pyx_v_grammar, __pyx_kp_labels); if (unlikely(!__pyx_1)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 41; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(((struct __pyx_obj_6sphinx_6pycode_5pgen2_5parse_Parser *)__pyx_v_self)->_grammar_labels); + ((struct __pyx_obj_6sphinx_6pycode_5pgen2_5parse_Parser *)__pyx_v_self)->_grammar_labels = __pyx_1; + __pyx_1 = 0; + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":42 + * self._grammar_dfas = grammar.dfas + * self._grammar_labels = grammar.labels + * self._grammar_keywords = grammar.keywords # <<<<<<<<<<<<<< + * self._grammar_tokens = grammar.tokens + * self._grammar_number2symbol = grammar.number2symbol + */ + __pyx_1 = PyObject_GetAttr(__pyx_v_grammar, __pyx_kp_keywords); if (unlikely(!__pyx_1)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 42; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(((struct __pyx_obj_6sphinx_6pycode_5pgen2_5parse_Parser *)__pyx_v_self)->_grammar_keywords); + ((struct __pyx_obj_6sphinx_6pycode_5pgen2_5parse_Parser *)__pyx_v_self)->_grammar_keywords = __pyx_1; + __pyx_1 = 0; + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":43 + * self._grammar_labels = grammar.labels + * self._grammar_keywords = grammar.keywords + * self._grammar_tokens = grammar.tokens # <<<<<<<<<<<<<< + * self._grammar_number2symbol = grammar.number2symbol + * + */ + __pyx_1 = PyObject_GetAttr(__pyx_v_grammar, __pyx_kp_tokens); if (unlikely(!__pyx_1)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 43; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(((struct __pyx_obj_6sphinx_6pycode_5pgen2_5parse_Parser *)__pyx_v_self)->_grammar_tokens); + ((struct __pyx_obj_6sphinx_6pycode_5pgen2_5parse_Parser *)__pyx_v_self)->_grammar_tokens = __pyx_1; + __pyx_1 = 0; + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":44 + * self._grammar_keywords = grammar.keywords + * self._grammar_tokens = grammar.tokens + * self._grammar_number2symbol = grammar.number2symbol # <<<<<<<<<<<<<< + * + * def setup(self, start=None): + */ + __pyx_1 = PyObject_GetAttr(__pyx_v_grammar, __pyx_kp_4); if (unlikely(!__pyx_1)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 44; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(((struct __pyx_obj_6sphinx_6pycode_5pgen2_5parse_Parser *)__pyx_v_self)->_grammar_number2symbol); + ((struct __pyx_obj_6sphinx_6pycode_5pgen2_5parse_Parser *)__pyx_v_self)->_grammar_number2symbol = __pyx_1; + __pyx_1 = 0; + + __pyx_r = 0; + goto __pyx_L0; + __pyx_L1_error:; + Py_XDECREF(__pyx_1); + __Pyx_AddTraceback("sphinx.pycode.pgen2.parse.Parser.__init__"); + __pyx_r = -1; + __pyx_L0:; + return __pyx_r; +} + +/* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":46 + * self._grammar_number2symbol = grammar.number2symbol + * + * def setup(self, start=None): # <<<<<<<<<<<<<< + * if start is None: + * start = self.grammar.start + */ + +static PyObject *__pyx_pf_6sphinx_6pycode_5pgen2_5parse_6Parser_setup(PyObject *__pyx_v_self, PyObject *__pyx_args, PyObject *__pyx_kwds); /*proto*/ +static PyObject *__pyx_pf_6sphinx_6pycode_5pgen2_5parse_6Parser_setup(PyObject *__pyx_v_self, PyObject *__pyx_args, PyObject *__pyx_kwds) { + PyObject *__pyx_v_start = 0; + PyObject *__pyx_v_newnode; + PyObject *__pyx_v_stackentry; + PyObject *__pyx_r; + int __pyx_1; + PyObject *__pyx_2 = 0; + PyObject *__pyx_3 = 0; + static char *__pyx_argnames[] = {"start",0}; + __pyx_v_start = Py_None; + if (likely(!__pyx_kwds) && likely(0 <= PyTuple_GET_SIZE(__pyx_args)) && likely(PyTuple_GET_SIZE(__pyx_args) <= 1)) { + if (PyTuple_GET_SIZE(__pyx_args) > 0) { + __pyx_v_start = PyTuple_GET_ITEM(__pyx_args, 0); + } + } + else { + if (unlikely(!PyArg_ParseTupleAndKeywords(__pyx_args, __pyx_kwds, "|O", __pyx_argnames, &__pyx_v_start))) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 46; __pyx_clineno = __LINE__; goto __pyx_L3_error;} + } + goto __pyx_L4; + __pyx_L3_error:; + __Pyx_AddTraceback("sphinx.pycode.pgen2.parse.Parser.setup"); + return NULL; + __pyx_L4:; + Py_INCREF(__pyx_v_start); + __pyx_v_newnode = Py_None; Py_INCREF(Py_None); + __pyx_v_stackentry = Py_None; Py_INCREF(Py_None); + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":47 + * + * def setup(self, start=None): + * if start is None: # <<<<<<<<<<<<<< + * start = self.grammar.start + * # Each stack entry is a tuple: (dfa, state, node). + */ + __pyx_1 = (__pyx_v_start == Py_None); + if (__pyx_1) { + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":48 + * def setup(self, start=None): + * if start is None: + * start = self.grammar.start # <<<<<<<<<<<<<< + * # Each stack entry is a tuple: (dfa, state, node). + * # A node is a tuple: (type, value, context, children), + */ + __pyx_2 = PyObject_GetAttr(((struct __pyx_obj_6sphinx_6pycode_5pgen2_5parse_Parser *)__pyx_v_self)->grammar, __pyx_kp_start); if (unlikely(!__pyx_2)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 48; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_v_start); + __pyx_v_start = __pyx_2; + __pyx_2 = 0; + goto __pyx_L5; + } + __pyx_L5:; + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":52 + * # A node is a tuple: (type, value, context, children), + * # where children is a list of nodes or None, and context may be None. + * newnode = (start, None, None, []) # <<<<<<<<<<<<<< + * stackentry = (self._grammar_dfas[start], 0, newnode) + * self.stack = [stackentry] + */ + __pyx_2 = PyList_New(0); if (unlikely(!__pyx_2)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 52; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + __pyx_3 = PyTuple_New(4); if (unlikely(!__pyx_3)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 52; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_INCREF(__pyx_v_start); + PyTuple_SET_ITEM(__pyx_3, 0, __pyx_v_start); + Py_INCREF(Py_None); + PyTuple_SET_ITEM(__pyx_3, 1, Py_None); + Py_INCREF(Py_None); + PyTuple_SET_ITEM(__pyx_3, 2, Py_None); + PyTuple_SET_ITEM(__pyx_3, 3, ((PyObject *)__pyx_2)); + __pyx_2 = 0; + Py_DECREF(__pyx_v_newnode); + __pyx_v_newnode = ((PyObject *)__pyx_3); + __pyx_3 = 0; + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":53 + * # where children is a list of nodes or None, and context may be None. + * newnode = (start, None, None, []) + * stackentry = (self._grammar_dfas[start], 0, newnode) # <<<<<<<<<<<<<< + * self.stack = [stackentry] + * self.rootnode = None + */ + __pyx_2 = PyObject_GetItem(((struct __pyx_obj_6sphinx_6pycode_5pgen2_5parse_Parser *)__pyx_v_self)->_grammar_dfas, __pyx_v_start); if (!__pyx_2) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 53; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + __pyx_3 = PyTuple_New(3); if (unlikely(!__pyx_3)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 53; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + PyTuple_SET_ITEM(__pyx_3, 0, __pyx_2); + Py_INCREF(__pyx_int_0); + PyTuple_SET_ITEM(__pyx_3, 1, __pyx_int_0); + Py_INCREF(__pyx_v_newnode); + PyTuple_SET_ITEM(__pyx_3, 2, __pyx_v_newnode); + __pyx_2 = 0; + Py_DECREF(__pyx_v_stackentry); + __pyx_v_stackentry = ((PyObject *)__pyx_3); + __pyx_3 = 0; + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":54 + * newnode = (start, None, None, []) + * stackentry = (self._grammar_dfas[start], 0, newnode) + * self.stack = [stackentry] # <<<<<<<<<<<<<< + * self.rootnode = None + * self.used_names = set() # Aliased to self.rootnode.used_names in pop() + */ + __pyx_2 = PyList_New(1); if (unlikely(!__pyx_2)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 54; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_INCREF(__pyx_v_stackentry); + PyList_SET_ITEM(__pyx_2, 0, __pyx_v_stackentry); + Py_DECREF(((struct __pyx_obj_6sphinx_6pycode_5pgen2_5parse_Parser *)__pyx_v_self)->stack); + ((struct __pyx_obj_6sphinx_6pycode_5pgen2_5parse_Parser *)__pyx_v_self)->stack = ((PyObject *)__pyx_2); + __pyx_2 = 0; + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":55 + * stackentry = (self._grammar_dfas[start], 0, newnode) + * self.stack = [stackentry] + * self.rootnode = None # <<<<<<<<<<<<<< + * self.used_names = set() # Aliased to self.rootnode.used_names in pop() + * + */ + Py_INCREF(Py_None); + Py_DECREF(((struct __pyx_obj_6sphinx_6pycode_5pgen2_5parse_Parser *)__pyx_v_self)->rootnode); + ((struct __pyx_obj_6sphinx_6pycode_5pgen2_5parse_Parser *)__pyx_v_self)->rootnode = Py_None; + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":56 + * self.stack = [stackentry] + * self.rootnode = None + * self.used_names = set() # Aliased to self.rootnode.used_names in pop() # <<<<<<<<<<<<<< + * + * def addtoken(self, type, value, context): + */ + __pyx_3 = PyObject_Call(((PyObject*)&PySet_Type), ((PyObject *)__pyx_empty_tuple), NULL); if (unlikely(!__pyx_3)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 56; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(((struct __pyx_obj_6sphinx_6pycode_5pgen2_5parse_Parser *)__pyx_v_self)->used_names); + ((struct __pyx_obj_6sphinx_6pycode_5pgen2_5parse_Parser *)__pyx_v_self)->used_names = __pyx_3; + __pyx_3 = 0; + + __pyx_r = Py_None; Py_INCREF(Py_None); + goto __pyx_L0; + __pyx_L1_error:; + Py_XDECREF(__pyx_2); + Py_XDECREF(__pyx_3); + __Pyx_AddTraceback("sphinx.pycode.pgen2.parse.Parser.setup"); + __pyx_r = NULL; + __pyx_L0:; + Py_DECREF(__pyx_v_newnode); + Py_DECREF(__pyx_v_stackentry); + Py_DECREF(__pyx_v_start); + return __pyx_r; +} + +/* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":58 + * self.used_names = set() # Aliased to self.rootnode.used_names in pop() + * + * def addtoken(self, type, value, context): # <<<<<<<<<<<<<< + * """Add a token; return True iff this is the end of the program.""" + * cdef int ilabel, i, t, state, newstate + */ + +static PyObject *__pyx_pf_6sphinx_6pycode_5pgen2_5parse_6Parser_addtoken(PyObject *__pyx_v_self, PyObject *__pyx_args, PyObject *__pyx_kwds); /*proto*/ +static char __pyx_doc_6sphinx_6pycode_5pgen2_5parse_6Parser_addtoken[] = "Add a token; return True iff this is the end of the program."; +static PyObject *__pyx_pf_6sphinx_6pycode_5pgen2_5parse_6Parser_addtoken(PyObject *__pyx_v_self, PyObject *__pyx_args, PyObject *__pyx_kwds) { + PyObject *__pyx_v_type = 0; + PyObject *__pyx_v_value = 0; + PyObject *__pyx_v_context = 0; + int __pyx_v_ilabel; + int __pyx_v_i; + int __pyx_v_t; + int __pyx_v_state; + int __pyx_v_newstate; + PyObject *__pyx_v_dfa; + PyObject *__pyx_v_node; + PyObject *__pyx_v_states; + PyObject *__pyx_v_first; + PyObject *__pyx_v_arcs; + PyObject *__pyx_v_v; + PyObject *__pyx_v_itsdfa; + PyObject *__pyx_v_itsstates; + PyObject *__pyx_v_itsfirst; + PyObject *__pyx_r; + int __pyx_1; + PyObject *__pyx_2 = 0; + PyObject *__pyx_3 = 0; + PyObject *__pyx_4 = 0; + int __pyx_5; + Py_ssize_t __pyx_6 = 0; + PyObject *__pyx_7 = 0; + int __pyx_8; + static char *__pyx_argnames[] = {"type","value","context",0}; + if (likely(!__pyx_kwds) && likely(PyTuple_GET_SIZE(__pyx_args) == 3)) { + __pyx_v_type = PyTuple_GET_ITEM(__pyx_args, 0); + __pyx_v_value = PyTuple_GET_ITEM(__pyx_args, 1); + __pyx_v_context = PyTuple_GET_ITEM(__pyx_args, 2); + } + else { + if (unlikely(!PyArg_ParseTupleAndKeywords(__pyx_args, __pyx_kwds, "OOO", __pyx_argnames, &__pyx_v_type, &__pyx_v_value, &__pyx_v_context))) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 58; __pyx_clineno = __LINE__; goto __pyx_L3_error;} + } + goto __pyx_L4; + __pyx_L3_error:; + __Pyx_AddTraceback("sphinx.pycode.pgen2.parse.Parser.addtoken"); + return NULL; + __pyx_L4:; + __pyx_v_dfa = Py_None; Py_INCREF(Py_None); + __pyx_v_node = Py_None; Py_INCREF(Py_None); + __pyx_v_states = Py_None; Py_INCREF(Py_None); + __pyx_v_first = Py_None; Py_INCREF(Py_None); + __pyx_v_arcs = Py_None; Py_INCREF(Py_None); + __pyx_v_v = Py_None; Py_INCREF(Py_None); + __pyx_v_itsdfa = Py_None; Py_INCREF(Py_None); + __pyx_v_itsstates = Py_None; Py_INCREF(Py_None); + __pyx_v_itsfirst = Py_None; Py_INCREF(Py_None); + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":62 + * cdef int ilabel, i, t, state, newstate + * # Map from token to label + * ilabel = self.classify(type, value, context) # <<<<<<<<<<<<<< + * # Loop until the token is shifted; may raise exceptions + * while True: + */ + __pyx_v_ilabel = ((struct __pyx_vtabstruct_6sphinx_6pycode_5pgen2_5parse_Parser *)((struct __pyx_obj_6sphinx_6pycode_5pgen2_5parse_Parser *)__pyx_v_self)->__pyx_vtab)->classify(((struct __pyx_obj_6sphinx_6pycode_5pgen2_5parse_Parser *)__pyx_v_self), __pyx_v_type, __pyx_v_value, __pyx_v_context); + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":64 + * ilabel = self.classify(type, value, context) + * # Loop until the token is shifted; may raise exceptions + * while True: # <<<<<<<<<<<<<< + * dfa, state, node = self.stack[-1] + * states, first = dfa + */ + while (1) { + __pyx_1 = 1; + if (!__pyx_1) break; + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":65 + * # Loop until the token is shifted; may raise exceptions + * while True: + * dfa, state, node = self.stack[-1] # <<<<<<<<<<<<<< + * states, first = dfa + * arcs = states[state] + */ + __pyx_2 = __Pyx_GetItemInt(((struct __pyx_obj_6sphinx_6pycode_5pgen2_5parse_Parser *)__pyx_v_self)->stack, -1, 0); if (!__pyx_2) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 65; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + if (PyTuple_CheckExact(__pyx_2) && PyTuple_GET_SIZE(__pyx_2) == 3) { + PyObject* tuple = __pyx_2; + __pyx_4 = PyTuple_GET_ITEM(tuple, 0); + Py_INCREF(__pyx_4); + Py_DECREF(__pyx_v_dfa); + __pyx_v_dfa = __pyx_4; + __pyx_4 = 0; + __pyx_4 = PyTuple_GET_ITEM(tuple, 1); + Py_INCREF(__pyx_4); + __pyx_5 = __pyx_PyInt_int(__pyx_4); if (unlikely((__pyx_5 == (int)-1) && PyErr_Occurred())) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 65; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_4); __pyx_4 = 0; + __pyx_v_state = __pyx_5; + __pyx_4 = PyTuple_GET_ITEM(tuple, 2); + Py_INCREF(__pyx_4); + Py_DECREF(__pyx_v_node); + __pyx_v_node = __pyx_4; + __pyx_4 = 0; + Py_DECREF(__pyx_2); __pyx_2 = 0; + } + else { + __pyx_3 = PyObject_GetIter(__pyx_2); if (unlikely(!__pyx_3)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 65; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_2); __pyx_2 = 0; + __pyx_4 = __Pyx_UnpackItem(__pyx_3, 0); if (unlikely(!__pyx_4)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 65; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_v_dfa); + __pyx_v_dfa = __pyx_4; + __pyx_4 = 0; + __pyx_4 = __Pyx_UnpackItem(__pyx_3, 1); if (unlikely(!__pyx_4)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 65; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + __pyx_5 = __pyx_PyInt_int(__pyx_4); if (unlikely((__pyx_5 == (int)-1) && PyErr_Occurred())) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 65; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_4); __pyx_4 = 0; + __pyx_v_state = __pyx_5; + __pyx_4 = __Pyx_UnpackItem(__pyx_3, 2); if (unlikely(!__pyx_4)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 65; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_v_node); + __pyx_v_node = __pyx_4; + __pyx_4 = 0; + if (__Pyx_EndUnpack(__pyx_3) < 0) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 65; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_3); __pyx_3 = 0; + } + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":66 + * while True: + * dfa, state, node = self.stack[-1] + * states, first = dfa # <<<<<<<<<<<<<< + * arcs = states[state] + * # Look for a state with this label + */ + if (PyTuple_CheckExact(__pyx_v_dfa) && PyTuple_GET_SIZE(__pyx_v_dfa) == 2) { + PyObject* tuple = __pyx_v_dfa; + __pyx_2 = PyTuple_GET_ITEM(tuple, 0); + Py_INCREF(__pyx_2); + Py_DECREF(__pyx_v_states); + __pyx_v_states = __pyx_2; + __pyx_2 = 0; + __pyx_3 = PyTuple_GET_ITEM(tuple, 1); + Py_INCREF(__pyx_3); + Py_DECREF(__pyx_v_first); + __pyx_v_first = __pyx_3; + __pyx_3 = 0; + } + else { + __pyx_4 = PyObject_GetIter(__pyx_v_dfa); if (unlikely(!__pyx_4)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 66; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + __pyx_2 = __Pyx_UnpackItem(__pyx_4, 0); if (unlikely(!__pyx_2)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 66; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_v_states); + __pyx_v_states = __pyx_2; + __pyx_2 = 0; + __pyx_3 = __Pyx_UnpackItem(__pyx_4, 1); if (unlikely(!__pyx_3)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 66; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_v_first); + __pyx_v_first = __pyx_3; + __pyx_3 = 0; + if (__Pyx_EndUnpack(__pyx_4) < 0) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 66; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_4); __pyx_4 = 0; + } + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":67 + * dfa, state, node = self.stack[-1] + * states, first = dfa + * arcs = states[state] # <<<<<<<<<<<<<< + * # Look for a state with this label + * for i, newstate in arcs: + */ + __pyx_2 = __Pyx_GetItemInt(__pyx_v_states, __pyx_v_state, 0); if (!__pyx_2) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 67; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_v_arcs); + __pyx_v_arcs = __pyx_2; + __pyx_2 = 0; + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":69 + * arcs = states[state] + * # Look for a state with this label + * for i, newstate in arcs: # <<<<<<<<<<<<<< + * t, v = self._grammar_labels[i] + * if ilabel == i: + */ + if (PyList_CheckExact(__pyx_v_arcs) || PyTuple_CheckExact(__pyx_v_arcs)) { + __pyx_6 = 0; __pyx_3 = __pyx_v_arcs; Py_INCREF(__pyx_3); + } else { + __pyx_6 = -1; __pyx_3 = PyObject_GetIter(__pyx_v_arcs); if (unlikely(!__pyx_3)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 69; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + } + for (;;) { + if (likely(PyList_CheckExact(__pyx_3))) { + if (__pyx_6 >= PyList_GET_SIZE(__pyx_3)) break; + __pyx_4 = PyList_GET_ITEM(__pyx_3, __pyx_6); Py_INCREF(__pyx_4); __pyx_6++; + } else if (likely(PyTuple_CheckExact(__pyx_3))) { + if (__pyx_6 >= PyTuple_GET_SIZE(__pyx_3)) break; + __pyx_4 = PyTuple_GET_ITEM(__pyx_3, __pyx_6); Py_INCREF(__pyx_4); __pyx_6++; + } else { + __pyx_4 = PyIter_Next(__pyx_3); + if (!__pyx_4) { + if (unlikely(PyErr_Occurred())) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 69; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + break; + } + } + if (PyTuple_CheckExact(__pyx_4) && PyTuple_GET_SIZE(__pyx_4) == 2) { + PyObject* tuple = __pyx_4; + __pyx_7 = PyTuple_GET_ITEM(tuple, 0); + Py_INCREF(__pyx_7); + __pyx_5 = __pyx_PyInt_int(__pyx_7); if (unlikely((__pyx_5 == (int)-1) && PyErr_Occurred())) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 69; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_7); __pyx_7 = 0; + __pyx_v_i = __pyx_5; + __pyx_7 = PyTuple_GET_ITEM(tuple, 1); + Py_INCREF(__pyx_7); + __pyx_5 = __pyx_PyInt_int(__pyx_7); if (unlikely((__pyx_5 == (int)-1) && PyErr_Occurred())) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 69; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_7); __pyx_7 = 0; + __pyx_v_newstate = __pyx_5; + Py_DECREF(__pyx_4); __pyx_4 = 0; + } + else { + __pyx_2 = PyObject_GetIter(__pyx_4); if (unlikely(!__pyx_2)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 69; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_4); __pyx_4 = 0; + __pyx_7 = __Pyx_UnpackItem(__pyx_2, 0); if (unlikely(!__pyx_7)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 69; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + __pyx_5 = __pyx_PyInt_int(__pyx_7); if (unlikely((__pyx_5 == (int)-1) && PyErr_Occurred())) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 69; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_7); __pyx_7 = 0; + __pyx_v_i = __pyx_5; + __pyx_7 = __Pyx_UnpackItem(__pyx_2, 1); if (unlikely(!__pyx_7)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 69; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + __pyx_5 = __pyx_PyInt_int(__pyx_7); if (unlikely((__pyx_5 == (int)-1) && PyErr_Occurred())) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 69; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_7); __pyx_7 = 0; + __pyx_v_newstate = __pyx_5; + if (__Pyx_EndUnpack(__pyx_2) < 0) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 69; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_2); __pyx_2 = 0; + } + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":70 + * # Look for a state with this label + * for i, newstate in arcs: + * t, v = self._grammar_labels[i] # <<<<<<<<<<<<<< + * if ilabel == i: + * # Look it up in the list of labels + */ + __pyx_7 = __Pyx_GetItemInt(((struct __pyx_obj_6sphinx_6pycode_5pgen2_5parse_Parser *)__pyx_v_self)->_grammar_labels, __pyx_v_i, 0); if (!__pyx_7) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 70; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + if (PyTuple_CheckExact(__pyx_7) && PyTuple_GET_SIZE(__pyx_7) == 2) { + PyObject* tuple = __pyx_7; + __pyx_2 = PyTuple_GET_ITEM(tuple, 0); + Py_INCREF(__pyx_2); + __pyx_5 = __pyx_PyInt_int(__pyx_2); if (unlikely((__pyx_5 == (int)-1) && PyErr_Occurred())) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 70; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_2); __pyx_2 = 0; + __pyx_v_t = __pyx_5; + __pyx_2 = PyTuple_GET_ITEM(tuple, 1); + Py_INCREF(__pyx_2); + Py_DECREF(__pyx_v_v); + __pyx_v_v = __pyx_2; + __pyx_2 = 0; + Py_DECREF(__pyx_7); __pyx_7 = 0; + } + else { + __pyx_4 = PyObject_GetIter(__pyx_7); if (unlikely(!__pyx_4)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 70; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_7); __pyx_7 = 0; + __pyx_2 = __Pyx_UnpackItem(__pyx_4, 0); if (unlikely(!__pyx_2)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 70; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + __pyx_5 = __pyx_PyInt_int(__pyx_2); if (unlikely((__pyx_5 == (int)-1) && PyErr_Occurred())) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 70; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_2); __pyx_2 = 0; + __pyx_v_t = __pyx_5; + __pyx_2 = __Pyx_UnpackItem(__pyx_4, 1); if (unlikely(!__pyx_2)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 70; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_v_v); + __pyx_v_v = __pyx_2; + __pyx_2 = 0; + if (__Pyx_EndUnpack(__pyx_4) < 0) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 70; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_4); __pyx_4 = 0; + } + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":71 + * for i, newstate in arcs: + * t, v = self._grammar_labels[i] + * if ilabel == i: # <<<<<<<<<<<<<< + * # Look it up in the list of labels + * ## assert t < 256 + */ + __pyx_1 = (__pyx_v_ilabel == __pyx_v_i); + if (__pyx_1) { + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":75 + * ## assert t < 256 + * # Shift a token; we're done with it + * self.shift(type, value, newstate, context) # <<<<<<<<<<<<<< + * # Pop while we are in an accept-only state + * state = newstate + */ + __pyx_2 = PyInt_FromLong(__pyx_v_newstate); if (unlikely(!__pyx_2)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 75; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + ((struct __pyx_vtabstruct_6sphinx_6pycode_5pgen2_5parse_Parser *)((struct __pyx_obj_6sphinx_6pycode_5pgen2_5parse_Parser *)__pyx_v_self)->__pyx_vtab)->shift(((struct __pyx_obj_6sphinx_6pycode_5pgen2_5parse_Parser *)__pyx_v_self), __pyx_v_type, __pyx_v_value, __pyx_2, __pyx_v_context); + Py_DECREF(__pyx_2); __pyx_2 = 0; + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":77 + * self.shift(type, value, newstate, context) + * # Pop while we are in an accept-only state + * state = newstate # <<<<<<<<<<<<<< + * while states[state] == [(0, state)]: + * self.pop() + */ + __pyx_v_state = __pyx_v_newstate; + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":78 + * # Pop while we are in an accept-only state + * state = newstate + * while states[state] == [(0, state)]: # <<<<<<<<<<<<<< + * self.pop() + * if not self.stack: + */ + while (1) { + __pyx_7 = __Pyx_GetItemInt(__pyx_v_states, __pyx_v_state, 0); if (!__pyx_7) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 78; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + __pyx_4 = PyInt_FromLong(__pyx_v_state); if (unlikely(!__pyx_4)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 78; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + __pyx_2 = PyTuple_New(2); if (unlikely(!__pyx_2)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 78; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_INCREF(__pyx_int_0); + PyTuple_SET_ITEM(__pyx_2, 0, __pyx_int_0); + PyTuple_SET_ITEM(__pyx_2, 1, __pyx_4); + __pyx_4 = 0; + __pyx_4 = PyList_New(1); if (unlikely(!__pyx_4)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 78; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + PyList_SET_ITEM(__pyx_4, 0, ((PyObject *)__pyx_2)); + __pyx_2 = 0; + __pyx_2 = PyObject_RichCompare(__pyx_7, ((PyObject *)__pyx_4), Py_EQ); if (unlikely(!__pyx_2)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 78; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_7); __pyx_7 = 0; + Py_DECREF(((PyObject *)__pyx_4)); __pyx_4 = 0; + __pyx_1 = __Pyx_PyObject_IsTrue(__pyx_2); if (unlikely(__pyx_1 < 0)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 78; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_2); __pyx_2 = 0; + if (!__pyx_1) break; + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":79 + * state = newstate + * while states[state] == [(0, state)]: + * self.pop() # <<<<<<<<<<<<<< + * if not self.stack: + * # Done parsing! + */ + ((struct __pyx_vtabstruct_6sphinx_6pycode_5pgen2_5parse_Parser *)((struct __pyx_obj_6sphinx_6pycode_5pgen2_5parse_Parser *)__pyx_v_self)->__pyx_vtab)->pop(((struct __pyx_obj_6sphinx_6pycode_5pgen2_5parse_Parser *)__pyx_v_self)); + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":80 + * while states[state] == [(0, state)]: + * self.pop() + * if not self.stack: # <<<<<<<<<<<<<< + * # Done parsing! + * return True + */ + __pyx_1 = __Pyx_PyObject_IsTrue(((struct __pyx_obj_6sphinx_6pycode_5pgen2_5parse_Parser *)__pyx_v_self)->stack); if (unlikely(__pyx_1 < 0)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 80; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + __pyx_8 = (!__pyx_1); + if (__pyx_8) { + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":82 + * if not self.stack: + * # Done parsing! + * return True # <<<<<<<<<<<<<< + * dfa, state, node = self.stack[-1] + * states, first = dfa + */ + __pyx_7 = __Pyx_PyBool_FromLong(1); if (unlikely(!__pyx_7)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 82; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + __pyx_r = __pyx_7; + __pyx_7 = 0; + Py_DECREF(__pyx_3); __pyx_3 = 0; + goto __pyx_L0; + goto __pyx_L12; + } + __pyx_L12:; + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":83 + * # Done parsing! + * return True + * dfa, state, node = self.stack[-1] # <<<<<<<<<<<<<< + * states, first = dfa + * # Done with this token + */ + __pyx_4 = __Pyx_GetItemInt(((struct __pyx_obj_6sphinx_6pycode_5pgen2_5parse_Parser *)__pyx_v_self)->stack, -1, 0); if (!__pyx_4) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 83; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + if (PyTuple_CheckExact(__pyx_4) && PyTuple_GET_SIZE(__pyx_4) == 3) { + PyObject* tuple = __pyx_4; + __pyx_7 = PyTuple_GET_ITEM(tuple, 0); + Py_INCREF(__pyx_7); + Py_DECREF(__pyx_v_dfa); + __pyx_v_dfa = __pyx_7; + __pyx_7 = 0; + __pyx_7 = PyTuple_GET_ITEM(tuple, 1); + Py_INCREF(__pyx_7); + __pyx_5 = __pyx_PyInt_int(__pyx_7); if (unlikely((__pyx_5 == (int)-1) && PyErr_Occurred())) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 83; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_7); __pyx_7 = 0; + __pyx_v_state = __pyx_5; + __pyx_7 = PyTuple_GET_ITEM(tuple, 2); + Py_INCREF(__pyx_7); + Py_DECREF(__pyx_v_node); + __pyx_v_node = __pyx_7; + __pyx_7 = 0; + Py_DECREF(__pyx_4); __pyx_4 = 0; + } + else { + __pyx_2 = PyObject_GetIter(__pyx_4); if (unlikely(!__pyx_2)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 83; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_4); __pyx_4 = 0; + __pyx_7 = __Pyx_UnpackItem(__pyx_2, 0); if (unlikely(!__pyx_7)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 83; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_v_dfa); + __pyx_v_dfa = __pyx_7; + __pyx_7 = 0; + __pyx_7 = __Pyx_UnpackItem(__pyx_2, 1); if (unlikely(!__pyx_7)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 83; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + __pyx_5 = __pyx_PyInt_int(__pyx_7); if (unlikely((__pyx_5 == (int)-1) && PyErr_Occurred())) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 83; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_7); __pyx_7 = 0; + __pyx_v_state = __pyx_5; + __pyx_7 = __Pyx_UnpackItem(__pyx_2, 2); if (unlikely(!__pyx_7)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 83; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_v_node); + __pyx_v_node = __pyx_7; + __pyx_7 = 0; + if (__Pyx_EndUnpack(__pyx_2) < 0) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 83; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_2); __pyx_2 = 0; + } + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":84 + * return True + * dfa, state, node = self.stack[-1] + * states, first = dfa # <<<<<<<<<<<<<< + * # Done with this token + * return False + */ + if (PyTuple_CheckExact(__pyx_v_dfa) && PyTuple_GET_SIZE(__pyx_v_dfa) == 2) { + PyObject* tuple = __pyx_v_dfa; + __pyx_4 = PyTuple_GET_ITEM(tuple, 0); + Py_INCREF(__pyx_4); + Py_DECREF(__pyx_v_states); + __pyx_v_states = __pyx_4; + __pyx_4 = 0; + __pyx_2 = PyTuple_GET_ITEM(tuple, 1); + Py_INCREF(__pyx_2); + Py_DECREF(__pyx_v_first); + __pyx_v_first = __pyx_2; + __pyx_2 = 0; + } + else { + __pyx_7 = PyObject_GetIter(__pyx_v_dfa); if (unlikely(!__pyx_7)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 84; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + __pyx_4 = __Pyx_UnpackItem(__pyx_7, 0); if (unlikely(!__pyx_4)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 84; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_v_states); + __pyx_v_states = __pyx_4; + __pyx_4 = 0; + __pyx_2 = __Pyx_UnpackItem(__pyx_7, 1); if (unlikely(!__pyx_2)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 84; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_v_first); + __pyx_v_first = __pyx_2; + __pyx_2 = 0; + if (__Pyx_EndUnpack(__pyx_7) < 0) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 84; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_7); __pyx_7 = 0; + } + } + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":86 + * states, first = dfa + * # Done with this token + * return False # <<<<<<<<<<<<<< + * elif t >= 256: + * # See if it's a symbol and if we're in its first set + */ + __pyx_4 = __Pyx_PyBool_FromLong(0); if (unlikely(!__pyx_4)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 86; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + __pyx_r = __pyx_4; + __pyx_4 = 0; + Py_DECREF(__pyx_3); __pyx_3 = 0; + goto __pyx_L0; + goto __pyx_L9; + } + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":87 + * # Done with this token + * return False + * elif t >= 256: # <<<<<<<<<<<<<< + * # See if it's a symbol and if we're in its first set + * itsdfa = self._grammar_dfas[t] + */ + __pyx_1 = (__pyx_v_t >= 256); + if (__pyx_1) { + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":89 + * elif t >= 256: + * # See if it's a symbol and if we're in its first set + * itsdfa = self._grammar_dfas[t] # <<<<<<<<<<<<<< + * itsstates, itsfirst = itsdfa + * if ilabel in itsfirst: + */ + __pyx_2 = __Pyx_GetItemInt(((struct __pyx_obj_6sphinx_6pycode_5pgen2_5parse_Parser *)__pyx_v_self)->_grammar_dfas, __pyx_v_t, 0); if (!__pyx_2) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 89; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_v_itsdfa); + __pyx_v_itsdfa = __pyx_2; + __pyx_2 = 0; + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":90 + * # See if it's a symbol and if we're in its first set + * itsdfa = self._grammar_dfas[t] + * itsstates, itsfirst = itsdfa # <<<<<<<<<<<<<< + * if ilabel in itsfirst: + * # Push a symbol + */ + if (PyTuple_CheckExact(__pyx_v_itsdfa) && PyTuple_GET_SIZE(__pyx_v_itsdfa) == 2) { + PyObject* tuple = __pyx_v_itsdfa; + __pyx_4 = PyTuple_GET_ITEM(tuple, 0); + Py_INCREF(__pyx_4); + Py_DECREF(__pyx_v_itsstates); + __pyx_v_itsstates = __pyx_4; + __pyx_4 = 0; + __pyx_2 = PyTuple_GET_ITEM(tuple, 1); + Py_INCREF(__pyx_2); + Py_DECREF(__pyx_v_itsfirst); + __pyx_v_itsfirst = __pyx_2; + __pyx_2 = 0; + } + else { + __pyx_7 = PyObject_GetIter(__pyx_v_itsdfa); if (unlikely(!__pyx_7)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 90; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + __pyx_4 = __Pyx_UnpackItem(__pyx_7, 0); if (unlikely(!__pyx_4)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 90; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_v_itsstates); + __pyx_v_itsstates = __pyx_4; + __pyx_4 = 0; + __pyx_2 = __Pyx_UnpackItem(__pyx_7, 1); if (unlikely(!__pyx_2)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 90; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_v_itsfirst); + __pyx_v_itsfirst = __pyx_2; + __pyx_2 = 0; + if (__Pyx_EndUnpack(__pyx_7) < 0) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 90; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_7); __pyx_7 = 0; + } + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":91 + * itsdfa = self._grammar_dfas[t] + * itsstates, itsfirst = itsdfa + * if ilabel in itsfirst: # <<<<<<<<<<<<<< + * # Push a symbol + * self.push(t, itsdfa, newstate, context) + */ + __pyx_4 = PyInt_FromLong(__pyx_v_ilabel); if (unlikely(!__pyx_4)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 91; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + __pyx_8 = (PySequence_Contains(__pyx_v_itsfirst, __pyx_4)); if (unlikely(__pyx_8 < 0)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 91; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_4); __pyx_4 = 0; + if (__pyx_8) { + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":93 + * if ilabel in itsfirst: + * # Push a symbol + * self.push(t, itsdfa, newstate, context) # <<<<<<<<<<<<<< + * break # To continue the outer while loop + * else: + */ + __pyx_2 = PyInt_FromLong(__pyx_v_t); if (unlikely(!__pyx_2)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 93; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + __pyx_7 = PyInt_FromLong(__pyx_v_newstate); if (unlikely(!__pyx_7)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 93; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + ((struct __pyx_vtabstruct_6sphinx_6pycode_5pgen2_5parse_Parser *)((struct __pyx_obj_6sphinx_6pycode_5pgen2_5parse_Parser *)__pyx_v_self)->__pyx_vtab)->push(((struct __pyx_obj_6sphinx_6pycode_5pgen2_5parse_Parser *)__pyx_v_self), __pyx_2, __pyx_v_itsdfa, __pyx_7, __pyx_v_context); + Py_DECREF(__pyx_2); __pyx_2 = 0; + Py_DECREF(__pyx_7); __pyx_7 = 0; + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":94 + * # Push a symbol + * self.push(t, itsdfa, newstate, context) + * break # To continue the outer while loop # <<<<<<<<<<<<<< + * else: + * if (0, state) in arcs: + */ + goto __pyx_L8; + goto __pyx_L13; + } + __pyx_L13:; + goto __pyx_L9; + } + __pyx_L9:; + } + /*else*/ { + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":96 + * break # To continue the outer while loop + * else: + * if (0, state) in arcs: # <<<<<<<<<<<<<< + * # An accepting state, pop it and try something else + * self.pop() + */ + __pyx_4 = PyInt_FromLong(__pyx_v_state); if (unlikely(!__pyx_4)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 96; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + __pyx_2 = PyTuple_New(2); if (unlikely(!__pyx_2)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 96; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_INCREF(__pyx_int_0); + PyTuple_SET_ITEM(__pyx_2, 0, __pyx_int_0); + PyTuple_SET_ITEM(__pyx_2, 1, __pyx_4); + __pyx_4 = 0; + __pyx_1 = (PySequence_Contains(__pyx_v_arcs, ((PyObject *)__pyx_2))); if (unlikely(__pyx_1 < 0)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 96; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(((PyObject *)__pyx_2)); __pyx_2 = 0; + if (__pyx_1) { + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":98 + * if (0, state) in arcs: + * # An accepting state, pop it and try something else + * self.pop() # <<<<<<<<<<<<<< + * if not self.stack: + * # Done parsing, but another token is input + */ + ((struct __pyx_vtabstruct_6sphinx_6pycode_5pgen2_5parse_Parser *)((struct __pyx_obj_6sphinx_6pycode_5pgen2_5parse_Parser *)__pyx_v_self)->__pyx_vtab)->pop(((struct __pyx_obj_6sphinx_6pycode_5pgen2_5parse_Parser *)__pyx_v_self)); + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":99 + * # An accepting state, pop it and try something else + * self.pop() + * if not self.stack: # <<<<<<<<<<<<<< + * # Done parsing, but another token is input + * raise ParseError("too much input", + */ + __pyx_8 = __Pyx_PyObject_IsTrue(((struct __pyx_obj_6sphinx_6pycode_5pgen2_5parse_Parser *)__pyx_v_self)->stack); if (unlikely(__pyx_8 < 0)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 99; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + __pyx_1 = (!__pyx_8); + if (__pyx_1) { + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":101 + * if not self.stack: + * # Done parsing, but another token is input + * raise ParseError("too much input", # <<<<<<<<<<<<<< + * type, value, context) + * else: + */ + __pyx_7 = __Pyx_GetName(__pyx_m, __pyx_kp_ParseError); if (unlikely(!__pyx_7)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 101; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":102 + * # Done parsing, but another token is input + * raise ParseError("too much input", + * type, value, context) # <<<<<<<<<<<<<< + * else: + * # No success finding a transition + */ + __pyx_4 = PyTuple_New(4); if (unlikely(!__pyx_4)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 101; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_INCREF(__pyx_kp_5); + PyTuple_SET_ITEM(__pyx_4, 0, __pyx_kp_5); + Py_INCREF(__pyx_v_type); + PyTuple_SET_ITEM(__pyx_4, 1, __pyx_v_type); + Py_INCREF(__pyx_v_value); + PyTuple_SET_ITEM(__pyx_4, 2, __pyx_v_value); + Py_INCREF(__pyx_v_context); + PyTuple_SET_ITEM(__pyx_4, 3, __pyx_v_context); + __pyx_2 = PyObject_Call(__pyx_7, ((PyObject *)__pyx_4), NULL); if (unlikely(!__pyx_2)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 101; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_7); __pyx_7 = 0; + Py_DECREF(((PyObject *)__pyx_4)); __pyx_4 = 0; + __Pyx_Raise(__pyx_2, 0, 0); + Py_DECREF(__pyx_2); __pyx_2 = 0; + {__pyx_filename = __pyx_f[0]; __pyx_lineno = 101; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + goto __pyx_L15; + } + __pyx_L15:; + goto __pyx_L14; + } + /*else*/ { + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":105 + * else: + * # No success finding a transition + * raise ParseError("bad input", type, value, context) # <<<<<<<<<<<<<< + * + * cdef int classify(self, type, value, context): + */ + __pyx_7 = __Pyx_GetName(__pyx_m, __pyx_kp_ParseError); if (unlikely(!__pyx_7)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 105; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + __pyx_4 = PyTuple_New(4); if (unlikely(!__pyx_4)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 105; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_INCREF(__pyx_kp_6); + PyTuple_SET_ITEM(__pyx_4, 0, __pyx_kp_6); + Py_INCREF(__pyx_v_type); + PyTuple_SET_ITEM(__pyx_4, 1, __pyx_v_type); + Py_INCREF(__pyx_v_value); + PyTuple_SET_ITEM(__pyx_4, 2, __pyx_v_value); + Py_INCREF(__pyx_v_context); + PyTuple_SET_ITEM(__pyx_4, 3, __pyx_v_context); + __pyx_2 = PyObject_Call(__pyx_7, ((PyObject *)__pyx_4), NULL); if (unlikely(!__pyx_2)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 105; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_7); __pyx_7 = 0; + Py_DECREF(((PyObject *)__pyx_4)); __pyx_4 = 0; + __Pyx_Raise(__pyx_2, 0, 0); + Py_DECREF(__pyx_2); __pyx_2 = 0; + {__pyx_filename = __pyx_f[0]; __pyx_lineno = 105; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + } + __pyx_L14:; + } + __pyx_L8:; + Py_DECREF(__pyx_3); __pyx_3 = 0; + } + + __pyx_r = Py_None; Py_INCREF(Py_None); + goto __pyx_L0; + __pyx_L1_error:; + Py_XDECREF(__pyx_2); + Py_XDECREF(__pyx_3); + Py_XDECREF(__pyx_4); + Py_XDECREF(__pyx_7); + __Pyx_AddTraceback("sphinx.pycode.pgen2.parse.Parser.addtoken"); + __pyx_r = NULL; + __pyx_L0:; + Py_DECREF(__pyx_v_dfa); + Py_DECREF(__pyx_v_node); + Py_DECREF(__pyx_v_states); + Py_DECREF(__pyx_v_first); + Py_DECREF(__pyx_v_arcs); + Py_DECREF(__pyx_v_v); + Py_DECREF(__pyx_v_itsdfa); + Py_DECREF(__pyx_v_itsstates); + Py_DECREF(__pyx_v_itsfirst); + return __pyx_r; +} + +/* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":107 + * raise ParseError("bad input", type, value, context) + * + * cdef int classify(self, type, value, context): # <<<<<<<<<<<<<< + * """Turn a token into a label. (Internal)""" + * if type == NAME: + */ + +static int __pyx_f_6sphinx_6pycode_5pgen2_5parse_6Parser_classify(struct __pyx_obj_6sphinx_6pycode_5pgen2_5parse_Parser *__pyx_v_self, PyObject *__pyx_v_type, PyObject *__pyx_v_value, PyObject *__pyx_v_context) { + PyObject *__pyx_v_ilabel; + int __pyx_r; + PyObject *__pyx_1 = 0; + int __pyx_2; + PyObject *__pyx_3 = 0; + PyObject *__pyx_4 = 0; + int __pyx_5; + __pyx_v_ilabel = Py_None; Py_INCREF(Py_None); + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":109 + * cdef int classify(self, type, value, context): + * """Turn a token into a label. (Internal)""" + * if type == NAME: # <<<<<<<<<<<<<< + * # Keep a listing of all used names + * self.used_names.add(value) + */ + __pyx_1 = PyObject_RichCompare(__pyx_v_type, __pyx_int_1, Py_EQ); if (unlikely(!__pyx_1)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 109; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + __pyx_2 = __Pyx_PyObject_IsTrue(__pyx_1); if (unlikely(__pyx_2 < 0)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 109; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_1); __pyx_1 = 0; + if (__pyx_2) { + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":111 + * if type == NAME: + * # Keep a listing of all used names + * self.used_names.add(value) # <<<<<<<<<<<<<< + * # Check for reserved words + * ilabel = self._grammar_keywords.get(value) + */ + __pyx_1 = PyObject_GetAttr(__pyx_v_self->used_names, __pyx_kp_add); if (unlikely(!__pyx_1)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 111; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + __pyx_3 = PyTuple_New(1); if (unlikely(!__pyx_3)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 111; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_INCREF(__pyx_v_value); + PyTuple_SET_ITEM(__pyx_3, 0, __pyx_v_value); + __pyx_4 = PyObject_Call(__pyx_1, ((PyObject *)__pyx_3), NULL); if (unlikely(!__pyx_4)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 111; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_1); __pyx_1 = 0; + Py_DECREF(((PyObject *)__pyx_3)); __pyx_3 = 0; + Py_DECREF(__pyx_4); __pyx_4 = 0; + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":113 + * self.used_names.add(value) + * # Check for reserved words + * ilabel = self._grammar_keywords.get(value) # <<<<<<<<<<<<<< + * if ilabel is not None: + * return ilabel + */ + __pyx_1 = PyObject_GetAttr(__pyx_v_self->_grammar_keywords, __pyx_kp_get); if (unlikely(!__pyx_1)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 113; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + __pyx_3 = PyTuple_New(1); if (unlikely(!__pyx_3)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 113; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_INCREF(__pyx_v_value); + PyTuple_SET_ITEM(__pyx_3, 0, __pyx_v_value); + __pyx_4 = PyObject_Call(__pyx_1, ((PyObject *)__pyx_3), NULL); if (unlikely(!__pyx_4)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 113; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_1); __pyx_1 = 0; + Py_DECREF(((PyObject *)__pyx_3)); __pyx_3 = 0; + Py_DECREF(__pyx_v_ilabel); + __pyx_v_ilabel = __pyx_4; + __pyx_4 = 0; + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":114 + * # Check for reserved words + * ilabel = self._grammar_keywords.get(value) + * if ilabel is not None: # <<<<<<<<<<<<<< + * return ilabel + * ilabel = self._grammar_tokens.get(type) + */ + __pyx_2 = (__pyx_v_ilabel != Py_None); + if (__pyx_2) { + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":115 + * ilabel = self._grammar_keywords.get(value) + * if ilabel is not None: + * return ilabel # <<<<<<<<<<<<<< + * ilabel = self._grammar_tokens.get(type) + * if ilabel is None: + */ + __pyx_5 = __pyx_PyInt_int(__pyx_v_ilabel); if (unlikely((__pyx_5 == (int)-1) && PyErr_Occurred())) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 115; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + __pyx_r = __pyx_5; + goto __pyx_L0; + goto __pyx_L4; + } + __pyx_L4:; + goto __pyx_L3; + } + __pyx_L3:; + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":116 + * if ilabel is not None: + * return ilabel + * ilabel = self._grammar_tokens.get(type) # <<<<<<<<<<<<<< + * if ilabel is None: + * raise ParseError("bad token", type, value, context) + */ + __pyx_1 = PyObject_GetAttr(__pyx_v_self->_grammar_tokens, __pyx_kp_get); if (unlikely(!__pyx_1)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 116; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + __pyx_3 = PyTuple_New(1); if (unlikely(!__pyx_3)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 116; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_INCREF(__pyx_v_type); + PyTuple_SET_ITEM(__pyx_3, 0, __pyx_v_type); + __pyx_4 = PyObject_Call(__pyx_1, ((PyObject *)__pyx_3), NULL); if (unlikely(!__pyx_4)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 116; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_1); __pyx_1 = 0; + Py_DECREF(((PyObject *)__pyx_3)); __pyx_3 = 0; + Py_DECREF(__pyx_v_ilabel); + __pyx_v_ilabel = __pyx_4; + __pyx_4 = 0; + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":117 + * return ilabel + * ilabel = self._grammar_tokens.get(type) + * if ilabel is None: # <<<<<<<<<<<<<< + * raise ParseError("bad token", type, value, context) + * return ilabel + */ + __pyx_2 = (__pyx_v_ilabel == Py_None); + if (__pyx_2) { + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":118 + * ilabel = self._grammar_tokens.get(type) + * if ilabel is None: + * raise ParseError("bad token", type, value, context) # <<<<<<<<<<<<<< + * return ilabel + * + */ + __pyx_1 = __Pyx_GetName(__pyx_m, __pyx_kp_ParseError); if (unlikely(!__pyx_1)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 118; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + __pyx_3 = PyTuple_New(4); if (unlikely(!__pyx_3)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 118; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_INCREF(__pyx_kp_7); + PyTuple_SET_ITEM(__pyx_3, 0, __pyx_kp_7); + Py_INCREF(__pyx_v_type); + PyTuple_SET_ITEM(__pyx_3, 1, __pyx_v_type); + Py_INCREF(__pyx_v_value); + PyTuple_SET_ITEM(__pyx_3, 2, __pyx_v_value); + Py_INCREF(__pyx_v_context); + PyTuple_SET_ITEM(__pyx_3, 3, __pyx_v_context); + __pyx_4 = PyObject_Call(__pyx_1, ((PyObject *)__pyx_3), NULL); if (unlikely(!__pyx_4)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 118; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_1); __pyx_1 = 0; + Py_DECREF(((PyObject *)__pyx_3)); __pyx_3 = 0; + __Pyx_Raise(__pyx_4, 0, 0); + Py_DECREF(__pyx_4); __pyx_4 = 0; + {__pyx_filename = __pyx_f[0]; __pyx_lineno = 118; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + goto __pyx_L5; + } + __pyx_L5:; + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":119 + * if ilabel is None: + * raise ParseError("bad token", type, value, context) + * return ilabel # <<<<<<<<<<<<<< + * + * cdef void shift(self, type, value, newstate, context): + */ + __pyx_5 = __pyx_PyInt_int(__pyx_v_ilabel); if (unlikely((__pyx_5 == (int)-1) && PyErr_Occurred())) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 119; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + __pyx_r = __pyx_5; + goto __pyx_L0; + + __pyx_r = 0; + goto __pyx_L0; + __pyx_L1_error:; + Py_XDECREF(__pyx_1); + Py_XDECREF(__pyx_3); + Py_XDECREF(__pyx_4); + __Pyx_WriteUnraisable("sphinx.pycode.pgen2.parse.Parser.classify"); + __pyx_r = 0; + __pyx_L0:; + Py_DECREF(__pyx_v_ilabel); + return __pyx_r; +} + +/* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":121 + * return ilabel + * + * cdef void shift(self, type, value, newstate, context): # <<<<<<<<<<<<<< + * """Shift a token. (Internal)""" + * dfa, state, node = self.stack[-1] + */ + +static void __pyx_f_6sphinx_6pycode_5pgen2_5parse_6Parser_shift(struct __pyx_obj_6sphinx_6pycode_5pgen2_5parse_Parser *__pyx_v_self, PyObject *__pyx_v_type, PyObject *__pyx_v_value, PyObject *__pyx_v_newstate, PyObject *__pyx_v_context) { + PyObject *__pyx_v_dfa; + PyObject *__pyx_v_state; + PyObject *__pyx_v_node; + PyObject *__pyx_v_newnode; + PyObject *__pyx_1 = 0; + PyObject *__pyx_2 = 0; + PyObject *__pyx_3 = 0; + int __pyx_4; + __pyx_v_dfa = Py_None; Py_INCREF(Py_None); + __pyx_v_state = Py_None; Py_INCREF(Py_None); + __pyx_v_node = Py_None; Py_INCREF(Py_None); + __pyx_v_newnode = Py_None; Py_INCREF(Py_None); + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":123 + * cdef void shift(self, type, value, newstate, context): + * """Shift a token. (Internal)""" + * dfa, state, node = self.stack[-1] # <<<<<<<<<<<<<< + * newnode = (type, value, context, None) + * newnode = self.convert(newnode) + */ + __pyx_1 = __Pyx_GetItemInt(__pyx_v_self->stack, -1, 0); if (!__pyx_1) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 123; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + if (PyTuple_CheckExact(__pyx_1) && PyTuple_GET_SIZE(__pyx_1) == 3) { + PyObject* tuple = __pyx_1; + __pyx_3 = PyTuple_GET_ITEM(tuple, 0); + Py_INCREF(__pyx_3); + Py_DECREF(__pyx_v_dfa); + __pyx_v_dfa = __pyx_3; + __pyx_3 = 0; + __pyx_3 = PyTuple_GET_ITEM(tuple, 1); + Py_INCREF(__pyx_3); + Py_DECREF(__pyx_v_state); + __pyx_v_state = __pyx_3; + __pyx_3 = 0; + __pyx_3 = PyTuple_GET_ITEM(tuple, 2); + Py_INCREF(__pyx_3); + Py_DECREF(__pyx_v_node); + __pyx_v_node = __pyx_3; + __pyx_3 = 0; + Py_DECREF(__pyx_1); __pyx_1 = 0; + } + else { + __pyx_2 = PyObject_GetIter(__pyx_1); if (unlikely(!__pyx_2)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 123; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_1); __pyx_1 = 0; + __pyx_3 = __Pyx_UnpackItem(__pyx_2, 0); if (unlikely(!__pyx_3)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 123; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_v_dfa); + __pyx_v_dfa = __pyx_3; + __pyx_3 = 0; + __pyx_3 = __Pyx_UnpackItem(__pyx_2, 1); if (unlikely(!__pyx_3)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 123; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_v_state); + __pyx_v_state = __pyx_3; + __pyx_3 = 0; + __pyx_3 = __Pyx_UnpackItem(__pyx_2, 2); if (unlikely(!__pyx_3)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 123; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_v_node); + __pyx_v_node = __pyx_3; + __pyx_3 = 0; + if (__Pyx_EndUnpack(__pyx_2) < 0) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 123; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_2); __pyx_2 = 0; + } + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":124 + * """Shift a token. (Internal)""" + * dfa, state, node = self.stack[-1] + * newnode = (type, value, context, None) # <<<<<<<<<<<<<< + * newnode = self.convert(newnode) + * if newnode is not None: + */ + __pyx_3 = PyTuple_New(4); if (unlikely(!__pyx_3)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 124; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_INCREF(__pyx_v_type); + PyTuple_SET_ITEM(__pyx_3, 0, __pyx_v_type); + Py_INCREF(__pyx_v_value); + PyTuple_SET_ITEM(__pyx_3, 1, __pyx_v_value); + Py_INCREF(__pyx_v_context); + PyTuple_SET_ITEM(__pyx_3, 2, __pyx_v_context); + Py_INCREF(Py_None); + PyTuple_SET_ITEM(__pyx_3, 3, Py_None); + Py_DECREF(__pyx_v_newnode); + __pyx_v_newnode = ((PyObject *)__pyx_3); + __pyx_3 = 0; + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":125 + * dfa, state, node = self.stack[-1] + * newnode = (type, value, context, None) + * newnode = self.convert(newnode) # <<<<<<<<<<<<<< + * if newnode is not None: + * node[-1].append(newnode) + */ + __pyx_1 = ((struct __pyx_vtabstruct_6sphinx_6pycode_5pgen2_5parse_Parser *)__pyx_v_self->__pyx_vtab)->convert(__pyx_v_self, __pyx_v_newnode); if (unlikely(!__pyx_1)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 125; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_v_newnode); + __pyx_v_newnode = __pyx_1; + __pyx_1 = 0; + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":126 + * newnode = (type, value, context, None) + * newnode = self.convert(newnode) + * if newnode is not None: # <<<<<<<<<<<<<< + * node[-1].append(newnode) + * self.stack[-1] = (dfa, newstate, node) + */ + __pyx_4 = (__pyx_v_newnode != Py_None); + if (__pyx_4) { + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":127 + * newnode = self.convert(newnode) + * if newnode is not None: + * node[-1].append(newnode) # <<<<<<<<<<<<<< + * self.stack[-1] = (dfa, newstate, node) + * + */ + __pyx_2 = __Pyx_GetItemInt(__pyx_v_node, -1, 0); if (!__pyx_2) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 127; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + __pyx_3 = __Pyx_PyObject_Append(__pyx_2, __pyx_v_newnode); if (unlikely(!__pyx_3)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 127; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_2); __pyx_2 = 0; + Py_DECREF(__pyx_3); __pyx_3 = 0; + goto __pyx_L3; + } + __pyx_L3:; + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":128 + * if newnode is not None: + * node[-1].append(newnode) + * self.stack[-1] = (dfa, newstate, node) # <<<<<<<<<<<<<< + * + * cdef void push(self, type, newdfa, newstate, context): + */ + __pyx_1 = PyTuple_New(3); if (unlikely(!__pyx_1)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 128; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_INCREF(__pyx_v_dfa); + PyTuple_SET_ITEM(__pyx_1, 0, __pyx_v_dfa); + Py_INCREF(__pyx_v_newstate); + PyTuple_SET_ITEM(__pyx_1, 1, __pyx_v_newstate); + Py_INCREF(__pyx_v_node); + PyTuple_SET_ITEM(__pyx_1, 2, __pyx_v_node); + if (__Pyx_SetItemInt(__pyx_v_self->stack, -1, ((PyObject *)__pyx_1), 0) < 0) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 128; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(((PyObject *)__pyx_1)); __pyx_1 = 0; + + goto __pyx_L0; + __pyx_L1_error:; + Py_XDECREF(__pyx_1); + Py_XDECREF(__pyx_2); + Py_XDECREF(__pyx_3); + __Pyx_WriteUnraisable("sphinx.pycode.pgen2.parse.Parser.shift"); + __pyx_L0:; + Py_DECREF(__pyx_v_dfa); + Py_DECREF(__pyx_v_state); + Py_DECREF(__pyx_v_node); + Py_DECREF(__pyx_v_newnode); +} + +/* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":130 + * self.stack[-1] = (dfa, newstate, node) + * + * cdef void push(self, type, newdfa, newstate, context): # <<<<<<<<<<<<<< + * """Push a nonterminal. (Internal)""" + * dfa, state, node = self.stack[-1] + */ + +static void __pyx_f_6sphinx_6pycode_5pgen2_5parse_6Parser_push(struct __pyx_obj_6sphinx_6pycode_5pgen2_5parse_Parser *__pyx_v_self, PyObject *__pyx_v_type, PyObject *__pyx_v_newdfa, PyObject *__pyx_v_newstate, PyObject *__pyx_v_context) { + PyObject *__pyx_v_dfa; + PyObject *__pyx_v_state; + PyObject *__pyx_v_node; + PyObject *__pyx_v_newnode; + PyObject *__pyx_1 = 0; + PyObject *__pyx_2 = 0; + PyObject *__pyx_3 = 0; + __pyx_v_dfa = Py_None; Py_INCREF(Py_None); + __pyx_v_state = Py_None; Py_INCREF(Py_None); + __pyx_v_node = Py_None; Py_INCREF(Py_None); + __pyx_v_newnode = Py_None; Py_INCREF(Py_None); + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":132 + * cdef void push(self, type, newdfa, newstate, context): + * """Push a nonterminal. (Internal)""" + * dfa, state, node = self.stack[-1] # <<<<<<<<<<<<<< + * newnode = (type, None, context, []) + * self.stack[-1] = (dfa, newstate, node) + */ + __pyx_1 = __Pyx_GetItemInt(__pyx_v_self->stack, -1, 0); if (!__pyx_1) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 132; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + if (PyTuple_CheckExact(__pyx_1) && PyTuple_GET_SIZE(__pyx_1) == 3) { + PyObject* tuple = __pyx_1; + __pyx_3 = PyTuple_GET_ITEM(tuple, 0); + Py_INCREF(__pyx_3); + Py_DECREF(__pyx_v_dfa); + __pyx_v_dfa = __pyx_3; + __pyx_3 = 0; + __pyx_3 = PyTuple_GET_ITEM(tuple, 1); + Py_INCREF(__pyx_3); + Py_DECREF(__pyx_v_state); + __pyx_v_state = __pyx_3; + __pyx_3 = 0; + __pyx_3 = PyTuple_GET_ITEM(tuple, 2); + Py_INCREF(__pyx_3); + Py_DECREF(__pyx_v_node); + __pyx_v_node = __pyx_3; + __pyx_3 = 0; + Py_DECREF(__pyx_1); __pyx_1 = 0; + } + else { + __pyx_2 = PyObject_GetIter(__pyx_1); if (unlikely(!__pyx_2)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 132; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_1); __pyx_1 = 0; + __pyx_3 = __Pyx_UnpackItem(__pyx_2, 0); if (unlikely(!__pyx_3)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 132; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_v_dfa); + __pyx_v_dfa = __pyx_3; + __pyx_3 = 0; + __pyx_3 = __Pyx_UnpackItem(__pyx_2, 1); if (unlikely(!__pyx_3)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 132; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_v_state); + __pyx_v_state = __pyx_3; + __pyx_3 = 0; + __pyx_3 = __Pyx_UnpackItem(__pyx_2, 2); if (unlikely(!__pyx_3)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 132; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_v_node); + __pyx_v_node = __pyx_3; + __pyx_3 = 0; + if (__Pyx_EndUnpack(__pyx_2) < 0) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 132; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_2); __pyx_2 = 0; + } + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":133 + * """Push a nonterminal. (Internal)""" + * dfa, state, node = self.stack[-1] + * newnode = (type, None, context, []) # <<<<<<<<<<<<<< + * self.stack[-1] = (dfa, newstate, node) + * self.stack.append((newdfa, 0, newnode)) + */ + __pyx_3 = PyList_New(0); if (unlikely(!__pyx_3)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 133; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + __pyx_1 = PyTuple_New(4); if (unlikely(!__pyx_1)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 133; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_INCREF(__pyx_v_type); + PyTuple_SET_ITEM(__pyx_1, 0, __pyx_v_type); + Py_INCREF(Py_None); + PyTuple_SET_ITEM(__pyx_1, 1, Py_None); + Py_INCREF(__pyx_v_context); + PyTuple_SET_ITEM(__pyx_1, 2, __pyx_v_context); + PyTuple_SET_ITEM(__pyx_1, 3, ((PyObject *)__pyx_3)); + __pyx_3 = 0; + Py_DECREF(__pyx_v_newnode); + __pyx_v_newnode = ((PyObject *)__pyx_1); + __pyx_1 = 0; + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":134 + * dfa, state, node = self.stack[-1] + * newnode = (type, None, context, []) + * self.stack[-1] = (dfa, newstate, node) # <<<<<<<<<<<<<< + * self.stack.append((newdfa, 0, newnode)) + * + */ + __pyx_2 = PyTuple_New(3); if (unlikely(!__pyx_2)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 134; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_INCREF(__pyx_v_dfa); + PyTuple_SET_ITEM(__pyx_2, 0, __pyx_v_dfa); + Py_INCREF(__pyx_v_newstate); + PyTuple_SET_ITEM(__pyx_2, 1, __pyx_v_newstate); + Py_INCREF(__pyx_v_node); + PyTuple_SET_ITEM(__pyx_2, 2, __pyx_v_node); + if (__Pyx_SetItemInt(__pyx_v_self->stack, -1, ((PyObject *)__pyx_2), 0) < 0) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 134; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(((PyObject *)__pyx_2)); __pyx_2 = 0; + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":135 + * newnode = (type, None, context, []) + * self.stack[-1] = (dfa, newstate, node) + * self.stack.append((newdfa, 0, newnode)) # <<<<<<<<<<<<<< + * + * cdef void pop(self): + */ + __pyx_3 = PyTuple_New(3); if (unlikely(!__pyx_3)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 135; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_INCREF(__pyx_v_newdfa); + PyTuple_SET_ITEM(__pyx_3, 0, __pyx_v_newdfa); + Py_INCREF(__pyx_int_0); + PyTuple_SET_ITEM(__pyx_3, 1, __pyx_int_0); + Py_INCREF(__pyx_v_newnode); + PyTuple_SET_ITEM(__pyx_3, 2, __pyx_v_newnode); + __pyx_1 = __Pyx_PyObject_Append(__pyx_v_self->stack, ((PyObject *)__pyx_3)); if (unlikely(!__pyx_1)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 135; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(((PyObject *)__pyx_3)); __pyx_3 = 0; + Py_DECREF(__pyx_1); __pyx_1 = 0; + + goto __pyx_L0; + __pyx_L1_error:; + Py_XDECREF(__pyx_1); + Py_XDECREF(__pyx_2); + Py_XDECREF(__pyx_3); + __Pyx_WriteUnraisable("sphinx.pycode.pgen2.parse.Parser.push"); + __pyx_L0:; + Py_DECREF(__pyx_v_dfa); + Py_DECREF(__pyx_v_state); + Py_DECREF(__pyx_v_node); + Py_DECREF(__pyx_v_newnode); +} + +/* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":137 + * self.stack.append((newdfa, 0, newnode)) + * + * cdef void pop(self): # <<<<<<<<<<<<<< + * """Pop a nonterminal. (Internal)""" + * popdfa, popstate, popnode = self.stack.pop() + */ + +static void __pyx_f_6sphinx_6pycode_5pgen2_5parse_6Parser_pop(struct __pyx_obj_6sphinx_6pycode_5pgen2_5parse_Parser *__pyx_v_self) { + PyObject *__pyx_v_popdfa; + PyObject *__pyx_v_popstate; + PyObject *__pyx_v_popnode; + PyObject *__pyx_v_newnode; + PyObject *__pyx_v_dfa; + PyObject *__pyx_v_state; + PyObject *__pyx_v_node; + PyObject *__pyx_1 = 0; + PyObject *__pyx_2 = 0; + PyObject *__pyx_3 = 0; + int __pyx_4; + __pyx_v_popdfa = Py_None; Py_INCREF(Py_None); + __pyx_v_popstate = Py_None; Py_INCREF(Py_None); + __pyx_v_popnode = Py_None; Py_INCREF(Py_None); + __pyx_v_newnode = Py_None; Py_INCREF(Py_None); + __pyx_v_dfa = Py_None; Py_INCREF(Py_None); + __pyx_v_state = Py_None; Py_INCREF(Py_None); + __pyx_v_node = Py_None; Py_INCREF(Py_None); + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":139 + * cdef void pop(self): + * """Pop a nonterminal. (Internal)""" + * popdfa, popstate, popnode = self.stack.pop() # <<<<<<<<<<<<<< + * newnode = self.convert(popnode) + * if newnode is not None: + */ + __pyx_1 = PyObject_GetAttr(__pyx_v_self->stack, __pyx_kp_pop); if (unlikely(!__pyx_1)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 139; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + __pyx_2 = PyObject_Call(__pyx_1, ((PyObject *)__pyx_empty_tuple), NULL); if (unlikely(!__pyx_2)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 139; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_1); __pyx_1 = 0; + if (PyTuple_CheckExact(__pyx_2) && PyTuple_GET_SIZE(__pyx_2) == 3) { + PyObject* tuple = __pyx_2; + __pyx_3 = PyTuple_GET_ITEM(tuple, 0); + Py_INCREF(__pyx_3); + Py_DECREF(__pyx_v_popdfa); + __pyx_v_popdfa = __pyx_3; + __pyx_3 = 0; + __pyx_3 = PyTuple_GET_ITEM(tuple, 1); + Py_INCREF(__pyx_3); + Py_DECREF(__pyx_v_popstate); + __pyx_v_popstate = __pyx_3; + __pyx_3 = 0; + __pyx_3 = PyTuple_GET_ITEM(tuple, 2); + Py_INCREF(__pyx_3); + Py_DECREF(__pyx_v_popnode); + __pyx_v_popnode = __pyx_3; + __pyx_3 = 0; + Py_DECREF(__pyx_2); __pyx_2 = 0; + } + else { + __pyx_1 = PyObject_GetIter(__pyx_2); if (unlikely(!__pyx_1)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 139; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_2); __pyx_2 = 0; + __pyx_3 = __Pyx_UnpackItem(__pyx_1, 0); if (unlikely(!__pyx_3)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 139; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_v_popdfa); + __pyx_v_popdfa = __pyx_3; + __pyx_3 = 0; + __pyx_3 = __Pyx_UnpackItem(__pyx_1, 1); if (unlikely(!__pyx_3)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 139; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_v_popstate); + __pyx_v_popstate = __pyx_3; + __pyx_3 = 0; + __pyx_3 = __Pyx_UnpackItem(__pyx_1, 2); if (unlikely(!__pyx_3)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 139; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_v_popnode); + __pyx_v_popnode = __pyx_3; + __pyx_3 = 0; + if (__Pyx_EndUnpack(__pyx_1) < 0) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 139; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_1); __pyx_1 = 0; + } + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":140 + * """Pop a nonterminal. (Internal)""" + * popdfa, popstate, popnode = self.stack.pop() + * newnode = self.convert(popnode) # <<<<<<<<<<<<<< + * if newnode is not None: + * if self.stack: + */ + __pyx_3 = ((struct __pyx_vtabstruct_6sphinx_6pycode_5pgen2_5parse_Parser *)__pyx_v_self->__pyx_vtab)->convert(__pyx_v_self, __pyx_v_popnode); if (unlikely(!__pyx_3)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 140; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_v_newnode); + __pyx_v_newnode = __pyx_3; + __pyx_3 = 0; + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":141 + * popdfa, popstate, popnode = self.stack.pop() + * newnode = self.convert(popnode) + * if newnode is not None: # <<<<<<<<<<<<<< + * if self.stack: + * dfa, state, node = self.stack[-1] + */ + __pyx_4 = (__pyx_v_newnode != Py_None); + if (__pyx_4) { + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":142 + * newnode = self.convert(popnode) + * if newnode is not None: + * if self.stack: # <<<<<<<<<<<<<< + * dfa, state, node = self.stack[-1] + * node[-1].append(newnode) + */ + __pyx_4 = __Pyx_PyObject_IsTrue(__pyx_v_self->stack); if (unlikely(__pyx_4 < 0)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 142; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + if (__pyx_4) { + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":143 + * if newnode is not None: + * if self.stack: + * dfa, state, node = self.stack[-1] # <<<<<<<<<<<<<< + * node[-1].append(newnode) + * else: + */ + __pyx_2 = __Pyx_GetItemInt(__pyx_v_self->stack, -1, 0); if (!__pyx_2) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 143; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + if (PyTuple_CheckExact(__pyx_2) && PyTuple_GET_SIZE(__pyx_2) == 3) { + PyObject* tuple = __pyx_2; + __pyx_3 = PyTuple_GET_ITEM(tuple, 0); + Py_INCREF(__pyx_3); + Py_DECREF(__pyx_v_dfa); + __pyx_v_dfa = __pyx_3; + __pyx_3 = 0; + __pyx_3 = PyTuple_GET_ITEM(tuple, 1); + Py_INCREF(__pyx_3); + Py_DECREF(__pyx_v_state); + __pyx_v_state = __pyx_3; + __pyx_3 = 0; + __pyx_3 = PyTuple_GET_ITEM(tuple, 2); + Py_INCREF(__pyx_3); + Py_DECREF(__pyx_v_node); + __pyx_v_node = __pyx_3; + __pyx_3 = 0; + Py_DECREF(__pyx_2); __pyx_2 = 0; + } + else { + __pyx_1 = PyObject_GetIter(__pyx_2); if (unlikely(!__pyx_1)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 143; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_2); __pyx_2 = 0; + __pyx_3 = __Pyx_UnpackItem(__pyx_1, 0); if (unlikely(!__pyx_3)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 143; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_v_dfa); + __pyx_v_dfa = __pyx_3; + __pyx_3 = 0; + __pyx_3 = __Pyx_UnpackItem(__pyx_1, 1); if (unlikely(!__pyx_3)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 143; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_v_state); + __pyx_v_state = __pyx_3; + __pyx_3 = 0; + __pyx_3 = __Pyx_UnpackItem(__pyx_1, 2); if (unlikely(!__pyx_3)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 143; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_v_node); + __pyx_v_node = __pyx_3; + __pyx_3 = 0; + if (__Pyx_EndUnpack(__pyx_1) < 0) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 143; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_1); __pyx_1 = 0; + } + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":144 + * if self.stack: + * dfa, state, node = self.stack[-1] + * node[-1].append(newnode) # <<<<<<<<<<<<<< + * else: + * self.rootnode = newnode + */ + __pyx_3 = __Pyx_GetItemInt(__pyx_v_node, -1, 0); if (!__pyx_3) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 144; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + __pyx_2 = __Pyx_PyObject_Append(__pyx_3, __pyx_v_newnode); if (unlikely(!__pyx_2)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 144; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_3); __pyx_3 = 0; + Py_DECREF(__pyx_2); __pyx_2 = 0; + goto __pyx_L4; + } + /*else*/ { + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":146 + * node[-1].append(newnode) + * else: + * self.rootnode = newnode # <<<<<<<<<<<<<< + * self.rootnode.used_names = self.used_names + * + */ + Py_INCREF(__pyx_v_newnode); + Py_DECREF(__pyx_v_self->rootnode); + __pyx_v_self->rootnode = __pyx_v_newnode; + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":147 + * else: + * self.rootnode = newnode + * self.rootnode.used_names = self.used_names # <<<<<<<<<<<<<< + * + * cdef convert(self, raw_node): + */ + if (PyObject_SetAttr(__pyx_v_self->rootnode, __pyx_kp_used_names, __pyx_v_self->used_names) < 0) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 147; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + } + __pyx_L4:; + goto __pyx_L3; + } + __pyx_L3:; + + goto __pyx_L0; + __pyx_L1_error:; + Py_XDECREF(__pyx_1); + Py_XDECREF(__pyx_2); + Py_XDECREF(__pyx_3); + __Pyx_WriteUnraisable("sphinx.pycode.pgen2.parse.Parser.pop"); + __pyx_L0:; + Py_DECREF(__pyx_v_popdfa); + Py_DECREF(__pyx_v_popstate); + Py_DECREF(__pyx_v_popnode); + Py_DECREF(__pyx_v_newnode); + Py_DECREF(__pyx_v_dfa); + Py_DECREF(__pyx_v_state); + Py_DECREF(__pyx_v_node); +} + +/* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":149 + * self.rootnode.used_names = self.used_names + * + * cdef convert(self, raw_node): # <<<<<<<<<<<<<< + * type, value, context, children = raw_node + * if children or type in self._grammar_number2symbol: + */ + +static PyObject *__pyx_f_6sphinx_6pycode_5pgen2_5parse_6Parser_convert(struct __pyx_obj_6sphinx_6pycode_5pgen2_5parse_Parser *__pyx_v_self, PyObject *__pyx_v_raw_node) { + PyObject *__pyx_v_type; + PyObject *__pyx_v_value; + PyObject *__pyx_v_context; + PyObject *__pyx_v_children; + PyObject *__pyx_r; + PyObject *__pyx_1 = 0; + PyObject *__pyx_2 = 0; + int __pyx_3; + Py_ssize_t __pyx_4 = 0; + PyObject *__pyx_5 = 0; + PyObject *__pyx_6 = 0; + __pyx_v_type = Py_None; Py_INCREF(Py_None); + __pyx_v_value = Py_None; Py_INCREF(Py_None); + __pyx_v_context = Py_None; Py_INCREF(Py_None); + __pyx_v_children = Py_None; Py_INCREF(Py_None); + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":150 + * + * cdef convert(self, raw_node): + * type, value, context, children = raw_node # <<<<<<<<<<<<<< + * if children or type in self._grammar_number2symbol: + * # If there's exactly one child, return that child instead of + */ + if (PyTuple_CheckExact(__pyx_v_raw_node) && PyTuple_GET_SIZE(__pyx_v_raw_node) == 4) { + PyObject* tuple = __pyx_v_raw_node; + __pyx_2 = PyTuple_GET_ITEM(tuple, 0); + Py_INCREF(__pyx_2); + Py_DECREF(__pyx_v_type); + __pyx_v_type = __pyx_2; + __pyx_2 = 0; + __pyx_2 = PyTuple_GET_ITEM(tuple, 1); + Py_INCREF(__pyx_2); + Py_DECREF(__pyx_v_value); + __pyx_v_value = __pyx_2; + __pyx_2 = 0; + __pyx_2 = PyTuple_GET_ITEM(tuple, 2); + Py_INCREF(__pyx_2); + Py_DECREF(__pyx_v_context); + __pyx_v_context = __pyx_2; + __pyx_2 = 0; + __pyx_2 = PyTuple_GET_ITEM(tuple, 3); + Py_INCREF(__pyx_2); + Py_DECREF(__pyx_v_children); + __pyx_v_children = __pyx_2; + __pyx_2 = 0; + } + else { + __pyx_1 = PyObject_GetIter(__pyx_v_raw_node); if (unlikely(!__pyx_1)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 150; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + __pyx_2 = __Pyx_UnpackItem(__pyx_1, 0); if (unlikely(!__pyx_2)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 150; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_v_type); + __pyx_v_type = __pyx_2; + __pyx_2 = 0; + __pyx_2 = __Pyx_UnpackItem(__pyx_1, 1); if (unlikely(!__pyx_2)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 150; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_v_value); + __pyx_v_value = __pyx_2; + __pyx_2 = 0; + __pyx_2 = __Pyx_UnpackItem(__pyx_1, 2); if (unlikely(!__pyx_2)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 150; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_v_context); + __pyx_v_context = __pyx_2; + __pyx_2 = 0; + __pyx_2 = __Pyx_UnpackItem(__pyx_1, 3); if (unlikely(!__pyx_2)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 150; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_v_children); + __pyx_v_children = __pyx_2; + __pyx_2 = 0; + if (__Pyx_EndUnpack(__pyx_1) < 0) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 150; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_1); __pyx_1 = 0; + } + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":151 + * cdef convert(self, raw_node): + * type, value, context, children = raw_node + * if children or type in self._grammar_number2symbol: # <<<<<<<<<<<<<< + * # If there's exactly one child, return that child instead of + * # creating a new node. + */ + __pyx_2 = __pyx_v_children; + Py_INCREF(__pyx_2); + __pyx_3 = __Pyx_PyObject_IsTrue(__pyx_2); if (unlikely(__pyx_3 < 0)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 151; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + if (!__pyx_3) { + Py_DECREF(__pyx_2); __pyx_2 = 0; + __pyx_3 = (PySequence_Contains(__pyx_v_self->_grammar_number2symbol, __pyx_v_type)); if (unlikely(__pyx_3 < 0)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 151; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + __pyx_2 = __Pyx_PyBool_FromLong(__pyx_3); if (unlikely(!__pyx_2)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 151; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + } + __pyx_3 = __Pyx_PyObject_IsTrue(__pyx_2); if (unlikely(__pyx_3 < 0)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 151; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_2); __pyx_2 = 0; + if (__pyx_3) { + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":154 + * # If there's exactly one child, return that child instead of + * # creating a new node. + * if len(children) == 1: # <<<<<<<<<<<<<< + * return children[0] + * return Node(type, children, context=context) + */ + __pyx_4 = PyObject_Length(__pyx_v_children); if (unlikely(__pyx_4 == -1)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 154; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + __pyx_3 = (__pyx_4 == 1); + if (__pyx_3) { + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":155 + * # creating a new node. + * if len(children) == 1: + * return children[0] # <<<<<<<<<<<<<< + * return Node(type, children, context=context) + * else: + */ + __pyx_1 = __Pyx_GetItemInt(__pyx_v_children, 0, 0); if (!__pyx_1) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 155; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + __pyx_r = __pyx_1; + __pyx_1 = 0; + goto __pyx_L0; + goto __pyx_L4; + } + __pyx_L4:; + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":156 + * if len(children) == 1: + * return children[0] + * return Node(type, children, context=context) # <<<<<<<<<<<<<< + * else: + * return Leaf(type, value, context=context) + */ + __pyx_2 = __Pyx_GetName(__pyx_m, __pyx_kp_Node); if (unlikely(!__pyx_2)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 156; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + __pyx_1 = PyTuple_New(2); if (unlikely(!__pyx_1)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 156; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_INCREF(__pyx_v_type); + PyTuple_SET_ITEM(__pyx_1, 0, __pyx_v_type); + Py_INCREF(__pyx_v_children); + PyTuple_SET_ITEM(__pyx_1, 1, __pyx_v_children); + __pyx_5 = PyDict_New(); if (unlikely(!__pyx_5)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 156; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + if (PyDict_SetItem(__pyx_5, __pyx_kp_context, __pyx_v_context) < 0) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 156; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + __pyx_6 = PyEval_CallObjectWithKeywords(__pyx_2, ((PyObject *)__pyx_1), ((PyObject *)__pyx_5)); if (unlikely(!__pyx_6)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 156; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_2); __pyx_2 = 0; + Py_DECREF(((PyObject *)__pyx_1)); __pyx_1 = 0; + Py_DECREF(((PyObject *)__pyx_5)); __pyx_5 = 0; + __pyx_r = __pyx_6; + __pyx_6 = 0; + goto __pyx_L0; + goto __pyx_L3; + } + /*else*/ { + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":158 + * return Node(type, children, context=context) + * else: + * return Leaf(type, value, context=context) # <<<<<<<<<<<<<< + */ + __pyx_2 = __Pyx_GetName(__pyx_m, __pyx_kp_Leaf); if (unlikely(!__pyx_2)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 158; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + __pyx_1 = PyTuple_New(2); if (unlikely(!__pyx_1)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 158; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_INCREF(__pyx_v_type); + PyTuple_SET_ITEM(__pyx_1, 0, __pyx_v_type); + Py_INCREF(__pyx_v_value); + PyTuple_SET_ITEM(__pyx_1, 1, __pyx_v_value); + __pyx_5 = PyDict_New(); if (unlikely(!__pyx_5)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 158; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + if (PyDict_SetItem(__pyx_5, __pyx_kp_context, __pyx_v_context) < 0) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 158; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + __pyx_6 = PyEval_CallObjectWithKeywords(__pyx_2, ((PyObject *)__pyx_1), ((PyObject *)__pyx_5)); if (unlikely(!__pyx_6)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 158; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_2); __pyx_2 = 0; + Py_DECREF(((PyObject *)__pyx_1)); __pyx_1 = 0; + Py_DECREF(((PyObject *)__pyx_5)); __pyx_5 = 0; + __pyx_r = __pyx_6; + __pyx_6 = 0; + goto __pyx_L0; + } + __pyx_L3:; + + __pyx_r = Py_None; Py_INCREF(Py_None); + goto __pyx_L0; + __pyx_L1_error:; + Py_XDECREF(__pyx_1); + Py_XDECREF(__pyx_2); + Py_XDECREF(__pyx_5); + Py_XDECREF(__pyx_6); + __Pyx_AddTraceback("sphinx.pycode.pgen2.parse.Parser.convert"); + __pyx_r = 0; + __pyx_L0:; + Py_DECREF(__pyx_v_type); + Py_DECREF(__pyx_v_value); + Py_DECREF(__pyx_v_context); + Py_DECREF(__pyx_v_children); + return __pyx_r; +} +static struct __pyx_vtabstruct_6sphinx_6pycode_5pgen2_5parse_Parser __pyx_vtable_6sphinx_6pycode_5pgen2_5parse_Parser; + +static PyObject *__pyx_tp_new_6sphinx_6pycode_5pgen2_5parse_Parser(PyTypeObject *t, PyObject *a, PyObject *k) { + struct __pyx_obj_6sphinx_6pycode_5pgen2_5parse_Parser *p; + PyObject *o = (*t->tp_alloc)(t, 0); + if (!o) return 0; + p = ((struct __pyx_obj_6sphinx_6pycode_5pgen2_5parse_Parser *)o); + p->__pyx_vtab = __pyx_vtabptr_6sphinx_6pycode_5pgen2_5parse_Parser; + p->grammar = Py_None; Py_INCREF(Py_None); + p->stack = Py_None; Py_INCREF(Py_None); + p->rootnode = Py_None; Py_INCREF(Py_None); + p->used_names = Py_None; Py_INCREF(Py_None); + p->_grammar_dfas = Py_None; Py_INCREF(Py_None); + p->_grammar_labels = Py_None; Py_INCREF(Py_None); + p->_grammar_keywords = Py_None; Py_INCREF(Py_None); + p->_grammar_tokens = Py_None; Py_INCREF(Py_None); + p->_grammar_number2symbol = Py_None; Py_INCREF(Py_None); + return o; +} + +static void __pyx_tp_dealloc_6sphinx_6pycode_5pgen2_5parse_Parser(PyObject *o) { + struct __pyx_obj_6sphinx_6pycode_5pgen2_5parse_Parser *p = (struct __pyx_obj_6sphinx_6pycode_5pgen2_5parse_Parser *)o; + Py_XDECREF(p->grammar); + Py_XDECREF(p->stack); + Py_XDECREF(p->rootnode); + Py_XDECREF(p->used_names); + Py_XDECREF(p->_grammar_dfas); + Py_XDECREF(p->_grammar_labels); + Py_XDECREF(p->_grammar_keywords); + Py_XDECREF(p->_grammar_tokens); + Py_XDECREF(p->_grammar_number2symbol); + (*Py_TYPE(o)->tp_free)(o); +} + +static int __pyx_tp_traverse_6sphinx_6pycode_5pgen2_5parse_Parser(PyObject *o, visitproc v, void *a) { + int e; + struct __pyx_obj_6sphinx_6pycode_5pgen2_5parse_Parser *p = (struct __pyx_obj_6sphinx_6pycode_5pgen2_5parse_Parser *)o; + if (p->grammar) { + e = (*v)(p->grammar, a); if (e) return e; + } + if (p->stack) { + e = (*v)(p->stack, a); if (e) return e; + } + if (p->rootnode) { + e = (*v)(p->rootnode, a); if (e) return e; + } + if (p->used_names) { + e = (*v)(p->used_names, a); if (e) return e; + } + if (p->_grammar_dfas) { + e = (*v)(p->_grammar_dfas, a); if (e) return e; + } + if (p->_grammar_labels) { + e = (*v)(p->_grammar_labels, a); if (e) return e; + } + if (p->_grammar_keywords) { + e = (*v)(p->_grammar_keywords, a); if (e) return e; + } + if (p->_grammar_tokens) { + e = (*v)(p->_grammar_tokens, a); if (e) return e; + } + if (p->_grammar_number2symbol) { + e = (*v)(p->_grammar_number2symbol, a); if (e) return e; + } + return 0; +} + +static int __pyx_tp_clear_6sphinx_6pycode_5pgen2_5parse_Parser(PyObject *o) { + struct __pyx_obj_6sphinx_6pycode_5pgen2_5parse_Parser *p = (struct __pyx_obj_6sphinx_6pycode_5pgen2_5parse_Parser *)o; + PyObject* tmp; + tmp = ((PyObject*)p->grammar); + p->grammar = Py_None; Py_INCREF(Py_None); + Py_XDECREF(tmp); + tmp = ((PyObject*)p->stack); + p->stack = Py_None; Py_INCREF(Py_None); + Py_XDECREF(tmp); + tmp = ((PyObject*)p->rootnode); + p->rootnode = Py_None; Py_INCREF(Py_None); + Py_XDECREF(tmp); + tmp = ((PyObject*)p->used_names); + p->used_names = Py_None; Py_INCREF(Py_None); + Py_XDECREF(tmp); + tmp = ((PyObject*)p->_grammar_dfas); + p->_grammar_dfas = Py_None; Py_INCREF(Py_None); + Py_XDECREF(tmp); + tmp = ((PyObject*)p->_grammar_labels); + p->_grammar_labels = Py_None; Py_INCREF(Py_None); + Py_XDECREF(tmp); + tmp = ((PyObject*)p->_grammar_keywords); + p->_grammar_keywords = Py_None; Py_INCREF(Py_None); + Py_XDECREF(tmp); + tmp = ((PyObject*)p->_grammar_tokens); + p->_grammar_tokens = Py_None; Py_INCREF(Py_None); + Py_XDECREF(tmp); + tmp = ((PyObject*)p->_grammar_number2symbol); + p->_grammar_number2symbol = Py_None; Py_INCREF(Py_None); + Py_XDECREF(tmp); + return 0; +} + +static struct PyMethodDef __pyx_methods_6sphinx_6pycode_5pgen2_5parse_Parser[] = { + {"setup", (PyCFunction)__pyx_pf_6sphinx_6pycode_5pgen2_5parse_6Parser_setup, METH_VARARGS|METH_KEYWORDS, 0}, + {"addtoken", (PyCFunction)__pyx_pf_6sphinx_6pycode_5pgen2_5parse_6Parser_addtoken, METH_VARARGS|METH_KEYWORDS, __pyx_doc_6sphinx_6pycode_5pgen2_5parse_6Parser_addtoken}, + {0, 0, 0, 0} +}; + +static struct PyMemberDef __pyx_members_6sphinx_6pycode_5pgen2_5parse_Parser[] = { + {"grammar", T_OBJECT, offsetof(struct __pyx_obj_6sphinx_6pycode_5pgen2_5parse_Parser, grammar), 0, 0}, + {"stack", T_OBJECT, offsetof(struct __pyx_obj_6sphinx_6pycode_5pgen2_5parse_Parser, stack), 0, 0}, + {"rootnode", T_OBJECT, offsetof(struct __pyx_obj_6sphinx_6pycode_5pgen2_5parse_Parser, rootnode), 0, 0}, + {"used_names", T_OBJECT, offsetof(struct __pyx_obj_6sphinx_6pycode_5pgen2_5parse_Parser, used_names), 0, 0}, + {0, 0, 0, 0, 0} +}; + +static PyNumberMethods __pyx_tp_as_number_Parser = { + 0, /*nb_add*/ + 0, /*nb_subtract*/ + 0, /*nb_multiply*/ + #if PY_MAJOR_VERSION < 3 + 0, /*nb_divide*/ + #endif + 0, /*nb_remainder*/ + 0, /*nb_divmod*/ + 0, /*nb_power*/ + 0, /*nb_negative*/ + 0, /*nb_positive*/ + 0, /*nb_absolute*/ + 0, /*nb_nonzero*/ + 0, /*nb_invert*/ + 0, /*nb_lshift*/ + 0, /*nb_rshift*/ + 0, /*nb_and*/ + 0, /*nb_xor*/ + 0, /*nb_or*/ + #if PY_MAJOR_VERSION < 3 + 0, /*nb_coerce*/ + #endif + 0, /*nb_int*/ + 0, /*nb_long*/ + 0, /*nb_float*/ + #if PY_MAJOR_VERSION < 3 + 0, /*nb_oct*/ + #endif + #if PY_MAJOR_VERSION < 3 + 0, /*nb_hex*/ + #endif + 0, /*nb_inplace_add*/ + 0, /*nb_inplace_subtract*/ + 0, /*nb_inplace_multiply*/ + #if PY_MAJOR_VERSION < 3 + 0, /*nb_inplace_divide*/ + #endif + 0, /*nb_inplace_remainder*/ + 0, /*nb_inplace_power*/ + 0, /*nb_inplace_lshift*/ + 0, /*nb_inplace_rshift*/ + 0, /*nb_inplace_and*/ + 0, /*nb_inplace_xor*/ + 0, /*nb_inplace_or*/ + 0, /*nb_floor_divide*/ + 0, /*nb_true_divide*/ + 0, /*nb_inplace_floor_divide*/ + 0, /*nb_inplace_true_divide*/ + #if (PY_MAJOR_VERSION >= 3) || (Py_TPFLAGS_DEFAULT & Py_TPFLAGS_HAVE_INDEX) + 0, /*nb_index*/ + #endif +}; + +static PySequenceMethods __pyx_tp_as_sequence_Parser = { + 0, /*sq_length*/ + 0, /*sq_concat*/ + 0, /*sq_repeat*/ + 0, /*sq_item*/ + 0, /*sq_slice*/ + 0, /*sq_ass_item*/ + 0, /*sq_ass_slice*/ + 0, /*sq_contains*/ + 0, /*sq_inplace_concat*/ + 0, /*sq_inplace_repeat*/ +}; + +static PyMappingMethods __pyx_tp_as_mapping_Parser = { + 0, /*mp_length*/ + 0, /*mp_subscript*/ + 0, /*mp_ass_subscript*/ +}; + +static PyBufferProcs __pyx_tp_as_buffer_Parser = { + #if PY_MAJOR_VERSION < 3 + 0, /*bf_getreadbuffer*/ + #endif + #if PY_MAJOR_VERSION < 3 + 0, /*bf_getwritebuffer*/ + #endif + #if PY_MAJOR_VERSION < 3 + 0, /*bf_getsegcount*/ + #endif + #if PY_MAJOR_VERSION < 3 + 0, /*bf_getcharbuffer*/ + #endif + #if (PY_MAJOR_VERSION >= 3) || (Py_TPFLAGS_DEFAULT & Py_TPFLAGS_HAVE_NEWBUFFER) + 0, /*bf_getbuffer*/ + #endif + #if (PY_MAJOR_VERSION >= 3) || (Py_TPFLAGS_DEFAULT & Py_TPFLAGS_HAVE_NEWBUFFER) + 0, /*bf_releasebuffer*/ + #endif +}; + +PyTypeObject __pyx_type_6sphinx_6pycode_5pgen2_5parse_Parser = { + PyVarObject_HEAD_INIT(0, 0) + "sphinx.pycode.pgen2.parse.Parser", /*tp_name*/ + sizeof(struct __pyx_obj_6sphinx_6pycode_5pgen2_5parse_Parser), /*tp_basicsize*/ + 0, /*tp_itemsize*/ + __pyx_tp_dealloc_6sphinx_6pycode_5pgen2_5parse_Parser, /*tp_dealloc*/ + 0, /*tp_print*/ + 0, /*tp_getattr*/ + 0, /*tp_setattr*/ + 0, /*tp_compare*/ + 0, /*tp_repr*/ + &__pyx_tp_as_number_Parser, /*tp_as_number*/ + &__pyx_tp_as_sequence_Parser, /*tp_as_sequence*/ + &__pyx_tp_as_mapping_Parser, /*tp_as_mapping*/ + 0, /*tp_hash*/ + 0, /*tp_call*/ + 0, /*tp_str*/ + 0, /*tp_getattro*/ + 0, /*tp_setattro*/ + &__pyx_tp_as_buffer_Parser, /*tp_as_buffer*/ + Py_TPFLAGS_DEFAULT|Py_TPFLAGS_CHECKTYPES|Py_TPFLAGS_BASETYPE|Py_TPFLAGS_HAVE_GC, /*tp_flags*/ + 0, /*tp_doc*/ + __pyx_tp_traverse_6sphinx_6pycode_5pgen2_5parse_Parser, /*tp_traverse*/ + __pyx_tp_clear_6sphinx_6pycode_5pgen2_5parse_Parser, /*tp_clear*/ + 0, /*tp_richcompare*/ + 0, /*tp_weaklistoffset*/ + 0, /*tp_iter*/ + 0, /*tp_iternext*/ + __pyx_methods_6sphinx_6pycode_5pgen2_5parse_Parser, /*tp_methods*/ + __pyx_members_6sphinx_6pycode_5pgen2_5parse_Parser, /*tp_members*/ + 0, /*tp_getset*/ + 0, /*tp_base*/ + 0, /*tp_dict*/ + 0, /*tp_descr_get*/ + 0, /*tp_descr_set*/ + 0, /*tp_dictoffset*/ + __pyx_pf_6sphinx_6pycode_5pgen2_5parse_6Parser___init__, /*tp_init*/ + 0, /*tp_alloc*/ + __pyx_tp_new_6sphinx_6pycode_5pgen2_5parse_Parser, /*tp_new*/ + 0, /*tp_free*/ + 0, /*tp_is_gc*/ + 0, /*tp_bases*/ + 0, /*tp_mro*/ + 0, /*tp_cache*/ + 0, /*tp_subclasses*/ + 0, /*tp_weaklist*/ +}; + +static struct PyMethodDef __pyx_methods[] = { + {0, 0, 0, 0} +}; + +static void __pyx_init_filenames(void); /*proto*/ + +#if PY_MAJOR_VERSION >= 3 +static struct PyModuleDef __pyx_moduledef = { + PyModuleDef_HEAD_INIT, + "parse", + 0, /* m_doc */ + -1, /* m_size */ + __pyx_methods /* m_methods */, + NULL, /* m_reload */ + NULL, /* m_traverse */ + NULL, /* m_clear */ + NULL /* m_free */ +}; +#endif + +static __Pyx_StringTabEntry __pyx_string_tab[] = { + {&__pyx_kp___init__, __pyx_k___init__, sizeof(__pyx_k___init__), 0, 1, 1}, + {&__pyx_kp_setup, __pyx_k_setup, sizeof(__pyx_k_setup), 0, 1, 1}, + {&__pyx_kp_addtoken, __pyx_k_addtoken, sizeof(__pyx_k_addtoken), 0, 1, 1}, + {&__pyx_kp_1, __pyx_k_1, sizeof(__pyx_k_1), 1, 1, 1}, + {&__pyx_kp_Node, __pyx_k_Node, sizeof(__pyx_k_Node), 1, 1, 1}, + {&__pyx_kp_Leaf, __pyx_k_Leaf, sizeof(__pyx_k_Leaf), 1, 1, 1}, + {&__pyx_kp_ParseError, __pyx_k_ParseError, sizeof(__pyx_k_ParseError), 0, 1, 1}, + {&__pyx_kp_Exception, __pyx_k_Exception, sizeof(__pyx_k_Exception), 1, 1, 1}, + {&__pyx_kp_msg, __pyx_k_msg, sizeof(__pyx_k_msg), 1, 1, 1}, + {&__pyx_kp_type, __pyx_k_type, sizeof(__pyx_k_type), 1, 1, 1}, + {&__pyx_kp_value, __pyx_k_value, sizeof(__pyx_k_value), 1, 1, 1}, + {&__pyx_kp_context, __pyx_k_context, sizeof(__pyx_k_context), 1, 1, 1}, + {&__pyx_kp_dfas, __pyx_k_dfas, sizeof(__pyx_k_dfas), 1, 1, 1}, + {&__pyx_kp_labels, __pyx_k_labels, sizeof(__pyx_k_labels), 1, 1, 1}, + {&__pyx_kp_keywords, __pyx_k_keywords, sizeof(__pyx_k_keywords), 1, 1, 1}, + {&__pyx_kp_tokens, __pyx_k_tokens, sizeof(__pyx_k_tokens), 1, 1, 1}, + {&__pyx_kp_4, __pyx_k_4, sizeof(__pyx_k_4), 1, 1, 1}, + {&__pyx_kp_start, __pyx_k_start, sizeof(__pyx_k_start), 1, 1, 1}, + {&__pyx_kp_add, __pyx_k_add, sizeof(__pyx_k_add), 1, 1, 1}, + {&__pyx_kp_get, __pyx_k_get, sizeof(__pyx_k_get), 1, 1, 1}, + {&__pyx_kp_append, __pyx_k_append, sizeof(__pyx_k_append), 1, 1, 1}, + {&__pyx_kp_pop, __pyx_k_pop, sizeof(__pyx_k_pop), 1, 1, 1}, + {&__pyx_kp_used_names, __pyx_k_used_names, sizeof(__pyx_k_used_names), 1, 1, 1}, + {&__pyx_kp_2, __pyx_k_2, sizeof(__pyx_k_2), 0, 0, 0}, + {&__pyx_kp_3, __pyx_k_3, sizeof(__pyx_k_3), 0, 0, 0}, + {&__pyx_kp_5, __pyx_k_5, sizeof(__pyx_k_5), 0, 0, 0}, + {&__pyx_kp_6, __pyx_k_6, sizeof(__pyx_k_6), 0, 0, 0}, + {&__pyx_kp_7, __pyx_k_7, sizeof(__pyx_k_7), 0, 0, 0}, + {0, 0, 0, 0, 0, 0} +}; +static int __Pyx_InitCachedBuiltins(void) { + __pyx_builtin_Exception = __Pyx_GetName(__pyx_b, __pyx_kp_Exception); if (!__pyx_builtin_Exception) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 19; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + return 0; + __pyx_L1_error:; + return -1; +} + +static int __Pyx_InitGlobals(void) { + __pyx_int_0 = PyInt_FromLong(0); if (unlikely(!__pyx_int_0)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 1; __pyx_clineno = __LINE__; goto __pyx_L1_error;}; + __pyx_int_1 = PyInt_FromLong(1); if (unlikely(!__pyx_int_1)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 1; __pyx_clineno = __LINE__; goto __pyx_L1_error;}; + if (__Pyx_InitStrings(__pyx_string_tab) < 0) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 1; __pyx_clineno = __LINE__; goto __pyx_L1_error;}; + return 0; + __pyx_L1_error:; + return -1; +} + +#if PY_MAJOR_VERSION < 3 +PyMODINIT_FUNC initparse(void); /*proto*/ +PyMODINIT_FUNC initparse(void) +#else +PyMODINIT_FUNC PyInit_parse(void); /*proto*/ +PyMODINIT_FUNC PyInit_parse(void) +#endif +{ + PyObject *__pyx_1 = 0; + PyObject *__pyx_2 = 0; + PyObject *__pyx_3 = 0; + PyObject *__pyx_4 = 0; + __pyx_empty_tuple = PyTuple_New(0); if (unlikely(!__pyx_empty_tuple)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 1; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + /*--- Libary function declarations ---*/ + __pyx_init_filenames(); + /*--- Initialize various global constants etc. ---*/ + if (unlikely(__Pyx_InitGlobals() < 0)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 1; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + /*--- Module creation code ---*/ + #if PY_MAJOR_VERSION < 3 + __pyx_m = Py_InitModule4("parse", __pyx_methods, 0, 0, PYTHON_API_VERSION); + #else + __pyx_m = PyModule_Create(&__pyx_moduledef); + #endif + if (!__pyx_m) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 1; __pyx_clineno = __LINE__; goto __pyx_L1_error;}; + #if PY_MAJOR_VERSION < 3 + Py_INCREF(__pyx_m); + #endif + __pyx_b = PyImport_AddModule(__Pyx_BUILTIN_MODULE_NAME); + if (!__pyx_b) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 1; __pyx_clineno = __LINE__; goto __pyx_L1_error;}; + if (PyObject_SetAttrString(__pyx_m, "__builtins__", __pyx_b) < 0) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 1; __pyx_clineno = __LINE__; goto __pyx_L1_error;}; + /*--- Builtin init code ---*/ + if (unlikely(__Pyx_InitCachedBuiltins() < 0)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 1; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + __pyx_skip_dispatch = 0; + /*--- Global init code ---*/ + /*--- Function export code ---*/ + /*--- Type init code ---*/ + __pyx_vtabptr_6sphinx_6pycode_5pgen2_5parse_Parser = &__pyx_vtable_6sphinx_6pycode_5pgen2_5parse_Parser; + *(void(**)(void))&__pyx_vtable_6sphinx_6pycode_5pgen2_5parse_Parser.classify = (void(*)(void))__pyx_f_6sphinx_6pycode_5pgen2_5parse_6Parser_classify; + *(void(**)(void))&__pyx_vtable_6sphinx_6pycode_5pgen2_5parse_Parser.shift = (void(*)(void))__pyx_f_6sphinx_6pycode_5pgen2_5parse_6Parser_shift; + *(void(**)(void))&__pyx_vtable_6sphinx_6pycode_5pgen2_5parse_Parser.push = (void(*)(void))__pyx_f_6sphinx_6pycode_5pgen2_5parse_6Parser_push; + *(void(**)(void))&__pyx_vtable_6sphinx_6pycode_5pgen2_5parse_Parser.pop = (void(*)(void))__pyx_f_6sphinx_6pycode_5pgen2_5parse_6Parser_pop; + *(void(**)(void))&__pyx_vtable_6sphinx_6pycode_5pgen2_5parse_Parser.convert = (void(*)(void))__pyx_f_6sphinx_6pycode_5pgen2_5parse_6Parser_convert; + if (PyType_Ready(&__pyx_type_6sphinx_6pycode_5pgen2_5parse_Parser) < 0) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 31; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + if (__Pyx_SetVtable(__pyx_type_6sphinx_6pycode_5pgen2_5parse_Parser.tp_dict, __pyx_vtabptr_6sphinx_6pycode_5pgen2_5parse_Parser) < 0) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 31; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + if (PyObject_SetAttrString(__pyx_m, "Parser", (PyObject *)&__pyx_type_6sphinx_6pycode_5pgen2_5parse_Parser) < 0) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 31; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + __pyx_ptype_6sphinx_6pycode_5pgen2_5parse_Parser = &__pyx_type_6sphinx_6pycode_5pgen2_5parse_Parser; + /*--- Type import code ---*/ + /*--- Function import code ---*/ + /*--- Execution code ---*/ + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":15 + * """ + * + * from sphinx.pycode.nodes import Node, Leaf # <<<<<<<<<<<<<< + * + * DEF NAME = 1 + */ + __pyx_1 = PyList_New(2); if (unlikely(!__pyx_1)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 15; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_INCREF(__pyx_kp_Node); + PyList_SET_ITEM(__pyx_1, 0, __pyx_kp_Node); + Py_INCREF(__pyx_kp_Leaf); + PyList_SET_ITEM(__pyx_1, 1, __pyx_kp_Leaf); + __pyx_2 = __Pyx_Import(__pyx_kp_1, ((PyObject *)__pyx_1)); if (unlikely(!__pyx_2)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 15; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(((PyObject *)__pyx_1)); __pyx_1 = 0; + __pyx_1 = PyObject_GetAttr(__pyx_2, __pyx_kp_Node); if (unlikely(!__pyx_1)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 15; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + if (PyObject_SetAttr(__pyx_m, __pyx_kp_Node, __pyx_1) < 0) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 15; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_1); __pyx_1 = 0; + __pyx_1 = PyObject_GetAttr(__pyx_2, __pyx_kp_Leaf); if (unlikely(!__pyx_1)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 15; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + if (PyObject_SetAttr(__pyx_m, __pyx_kp_Leaf, __pyx_1) < 0) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 15; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_1); __pyx_1 = 0; + Py_DECREF(__pyx_2); __pyx_2 = 0; + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":19 + * DEF NAME = 1 + * + * class ParseError(Exception): # <<<<<<<<<<<<<< + * """Exception to signal the parser is stuck.""" + * + */ + __pyx_2 = PyDict_New(); if (unlikely(!__pyx_2)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 19; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + __pyx_1 = PyTuple_New(1); if (unlikely(!__pyx_1)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 19; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_INCREF(__pyx_builtin_Exception); + PyTuple_SET_ITEM(__pyx_1, 0, __pyx_builtin_Exception); + if (PyDict_SetItemString(((PyObject *)__pyx_2), "__doc__", __pyx_kp_2) < 0) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 19; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + __pyx_3 = __Pyx_CreateClass(((PyObject *)__pyx_1), ((PyObject *)__pyx_2), __pyx_kp_ParseError, "sphinx.pycode.pgen2.parse"); if (unlikely(!__pyx_3)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 19; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(((PyObject *)__pyx_1)); __pyx_1 = 0; + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":22 + * """Exception to signal the parser is stuck.""" + * + * def __init__(self, msg, type, value, context): # <<<<<<<<<<<<<< + * Exception.__init__(self, "%s: type=%r, value=%r, context=%r" % + * (msg, type, value, context)) + */ + __pyx_1 = PyCFunction_New(&__pyx_mdef_6sphinx_6pycode_5pgen2_5parse_10ParseError___init__, 0); if (unlikely(!__pyx_1)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 22; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + __pyx_4 = PyMethod_New(__pyx_1, 0, __pyx_3); if (unlikely(!__pyx_4)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 22; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_1); __pyx_1 = 0; + if (PyObject_SetAttr(__pyx_3, __pyx_kp___init__, __pyx_4) < 0) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 22; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_4); __pyx_4 = 0; + if (PyObject_SetAttr(__pyx_m, __pyx_kp_ParseError, __pyx_3) < 0) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 19; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_3); __pyx_3 = 0; + Py_DECREF(((PyObject *)__pyx_2)); __pyx_2 = 0; + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":149 + * self.rootnode.used_names = self.used_names + * + * cdef convert(self, raw_node): # <<<<<<<<<<<<<< + * type, value, context, children = raw_node + * if children or type in self._grammar_number2symbol: + */ + #if PY_MAJOR_VERSION < 3 + return; + #else + return __pyx_m; + #endif + __pyx_L1_error:; + Py_XDECREF(__pyx_1); + Py_XDECREF(__pyx_2); + Py_XDECREF(__pyx_3); + Py_XDECREF(__pyx_4); + __Pyx_AddTraceback("sphinx.pycode.pgen2.parse"); + #if PY_MAJOR_VERSION >= 3 + return NULL; + #endif +} + +static const char *__pyx_filenames[] = { + "parse.pyx", +}; + +/* Runtime support code */ + +static void __pyx_init_filenames(void) { + __pyx_f = __pyx_filenames; +} + +static INLINE void __Pyx_RaiseArgtupleTooLong( + Py_ssize_t num_expected, + Py_ssize_t num_found) +{ + const char* error_message = + #if PY_VERSION_HEX < 0x02050000 + "function takes at most %d positional arguments (%d given)"; + #else + "function takes at most %zd positional arguments (%zd given)"; + #endif + PyErr_Format(PyExc_TypeError, error_message, num_expected, num_found); +} + +static PyObject *__Pyx_Import(PyObject *name, PyObject *from_list) { + PyObject *__import__ = 0; + PyObject *empty_list = 0; + PyObject *module = 0; + PyObject *global_dict = 0; + PyObject *empty_dict = 0; + PyObject *list; + __import__ = PyObject_GetAttrString(__pyx_b, "__import__"); + if (!__import__) + goto bad; + if (from_list) + list = from_list; + else { + empty_list = PyList_New(0); + if (!empty_list) + goto bad; + list = empty_list; + } + global_dict = PyModule_GetDict(__pyx_m); + if (!global_dict) + goto bad; + empty_dict = PyDict_New(); + if (!empty_dict) + goto bad; + module = PyObject_CallFunction(__import__, "OOOO", + name, global_dict, empty_dict, list); +bad: + Py_XDECREF(empty_list); + Py_XDECREF(__import__); + Py_XDECREF(empty_dict); + return module; +} + +static PyObject *__Pyx_GetName(PyObject *dict, PyObject *name) { + PyObject *result; + result = PyObject_GetAttr(dict, name); + if (!result) + PyErr_SetObject(PyExc_NameError, name); + return result; +} + +static PyObject *__Pyx_CreateClass( + PyObject *bases, PyObject *dict, PyObject *name, char *modname) +{ + PyObject *py_modname; + PyObject *result = 0; + + #if PY_MAJOR_VERSION < 3 + py_modname = PyString_FromString(modname); + #else + py_modname = PyUnicode_FromString(modname); + #endif + if (!py_modname) + goto bad; + if (PyDict_SetItemString(dict, "__module__", py_modname) < 0) + goto bad; + #if PY_MAJOR_VERSION < 3 + result = PyClass_New(bases, dict, name); + #else + result = PyObject_CallFunctionObjArgs((PyObject *)&PyType_Type, name, bases, dict, NULL); + #endif +bad: + Py_XDECREF(py_modname); + return result; +} + + +static PyObject *__Pyx_UnpackItem(PyObject *iter, Py_ssize_t index) { + PyObject *item; + if (!(item = PyIter_Next(iter))) { + if (!PyErr_Occurred()) { + PyErr_Format(PyExc_ValueError, + #if PY_VERSION_HEX < 0x02050000 + "need more than %d values to unpack", (int)index); + #else + "need more than %zd values to unpack", index); + #endif + } + } + return item; +} + +static int __Pyx_EndUnpack(PyObject *iter) { + PyObject *item; + if ((item = PyIter_Next(iter))) { + Py_DECREF(item); + PyErr_SetString(PyExc_ValueError, "too many values to unpack"); + return -1; + } + else if (!PyErr_Occurred()) + return 0; + else + return -1; +} + +static void __Pyx_Raise(PyObject *type, PyObject *value, PyObject *tb) { + Py_XINCREF(type); + Py_XINCREF(value); + Py_XINCREF(tb); + /* First, check the traceback argument, replacing None with NULL. */ + if (tb == Py_None) { + Py_DECREF(tb); + tb = 0; + } + else if (tb != NULL && !PyTraceBack_Check(tb)) { + PyErr_SetString(PyExc_TypeError, + "raise: arg 3 must be a traceback or None"); + goto raise_error; + } + /* Next, replace a missing value with None */ + if (value == NULL) { + value = Py_None; + Py_INCREF(value); + } + #if PY_VERSION_HEX < 0x02050000 + if (!PyClass_Check(type)) + #else + if (!PyType_Check(type)) + #endif + { + /* Raising an instance. The value should be a dummy. */ + if (value != Py_None) { + PyErr_SetString(PyExc_TypeError, + "instance exception may not have a separate value"); + goto raise_error; + } + /* Normalize to raise <class>, <instance> */ + Py_DECREF(value); + value = type; + #if PY_VERSION_HEX < 0x02050000 + if (PyInstance_Check(type)) { + type = (PyObject*) ((PyInstanceObject*)type)->in_class; + Py_INCREF(type); + } + else { + type = 0; + PyErr_SetString(PyExc_TypeError, + "raise: exception must be an old-style class or instance"); + goto raise_error; + } + #else + type = (PyObject*) Py_TYPE(type); + Py_INCREF(type); + if (!PyType_IsSubtype((PyTypeObject *)type, (PyTypeObject *)PyExc_BaseException)) { + PyErr_SetString(PyExc_TypeError, + "raise: exception class must be a subclass of BaseException"); + goto raise_error; + } + #endif + } + PyErr_Restore(type, value, tb); + return; +raise_error: + Py_XDECREF(value); + Py_XDECREF(type); + Py_XDECREF(tb); + return; +} + + +static void __Pyx_WriteUnraisable(const char *name) { + PyObject *old_exc, *old_val, *old_tb; + PyObject *ctx; + PyErr_Fetch(&old_exc, &old_val, &old_tb); + #if PY_MAJOR_VERSION < 3 + ctx = PyString_FromString(name); + #else + ctx = PyUnicode_FromString(name); + #endif + PyErr_Restore(old_exc, old_val, old_tb); + if (!ctx) + ctx = Py_None; + PyErr_WriteUnraisable(ctx); +} + +static int __Pyx_SetVtable(PyObject *dict, void *vtable) { + PyObject *pycobj = 0; + int result; + + pycobj = PyCObject_FromVoidPtr(vtable, 0); + if (!pycobj) + goto bad; + if (PyDict_SetItemString(dict, "__pyx_vtable__", pycobj) < 0) + goto bad; + result = 0; + goto done; + +bad: + result = -1; +done: + Py_XDECREF(pycobj); + return result; +} + +#include "compile.h" +#include "frameobject.h" +#include "traceback.h" + +static void __Pyx_AddTraceback(const char *funcname) { + PyObject *py_srcfile = 0; + PyObject *py_funcname = 0; + PyObject *py_globals = 0; + PyObject *empty_string = 0; + PyCodeObject *py_code = 0; + PyFrameObject *py_frame = 0; + + #if PY_MAJOR_VERSION < 3 + py_srcfile = PyString_FromString(__pyx_filename); + #else + py_srcfile = PyUnicode_FromString(__pyx_filename); + #endif + if (!py_srcfile) goto bad; + if (__pyx_clineno) { + #if PY_MAJOR_VERSION < 3 + py_funcname = PyString_FromFormat( "%s (%s:%d)", funcname, __pyx_cfilenm, __pyx_clineno); + #else + py_funcname = PyUnicode_FromFormat( "%s (%s:%d)", funcname, __pyx_cfilenm, __pyx_clineno); + #endif + } + else { + #if PY_MAJOR_VERSION < 3 + py_funcname = PyString_FromString(funcname); + #else + py_funcname = PyUnicode_FromString(funcname); + #endif + } + if (!py_funcname) goto bad; + py_globals = PyModule_GetDict(__pyx_m); + if (!py_globals) goto bad; + #if PY_MAJOR_VERSION < 3 + empty_string = PyString_FromStringAndSize("", 0); + #else + empty_string = PyBytes_FromStringAndSize("", 0); + #endif + if (!empty_string) goto bad; + py_code = PyCode_New( + 0, /*int argcount,*/ + #if PY_MAJOR_VERSION >= 3 + 0, /*int kwonlyargcount,*/ + #endif + 0, /*int nlocals,*/ + 0, /*int stacksize,*/ + 0, /*int flags,*/ + empty_string, /*PyObject *code,*/ + __pyx_empty_tuple, /*PyObject *consts,*/ + __pyx_empty_tuple, /*PyObject *names,*/ + __pyx_empty_tuple, /*PyObject *varnames,*/ + __pyx_empty_tuple, /*PyObject *freevars,*/ + __pyx_empty_tuple, /*PyObject *cellvars,*/ + py_srcfile, /*PyObject *filename,*/ + py_funcname, /*PyObject *name,*/ + __pyx_lineno, /*int firstlineno,*/ + empty_string /*PyObject *lnotab*/ + ); + if (!py_code) goto bad; + py_frame = PyFrame_New( + PyThreadState_Get(), /*PyThreadState *tstate,*/ + py_code, /*PyCodeObject *code,*/ + py_globals, /*PyObject *globals,*/ + 0 /*PyObject *locals*/ + ); + if (!py_frame) goto bad; + py_frame->f_lineno = __pyx_lineno; + PyTraceBack_Here(py_frame); +bad: + Py_XDECREF(py_srcfile); + Py_XDECREF(py_funcname); + Py_XDECREF(empty_string); + Py_XDECREF(py_code); + Py_XDECREF(py_frame); +} + +static int __Pyx_InitStrings(__Pyx_StringTabEntry *t) { + while (t->p) { + #if PY_MAJOR_VERSION < 3 + if (t->is_unicode && (!t->is_identifier)) { + *t->p = PyUnicode_DecodeUTF8(t->s, t->n - 1, NULL); + } else if (t->intern) { + *t->p = PyString_InternFromString(t->s); + } else { + *t->p = PyString_FromStringAndSize(t->s, t->n - 1); + } + #else /* Python 3+ has unicode identifiers */ + if (t->is_identifier || (t->is_unicode && t->intern)) { + *t->p = PyUnicode_InternFromString(t->s); + } else if (t->is_unicode) { + *t->p = PyUnicode_FromStringAndSize(t->s, t->n - 1); + } else { + *t->p = PyBytes_FromStringAndSize(t->s, t->n - 1); + } + #endif + if (!*t->p) + return -1; + ++t; + } + return 0; +} + +/* Type Conversion Functions */ + +static INLINE Py_ssize_t __pyx_PyIndex_AsSsize_t(PyObject* b) { + Py_ssize_t ival; + PyObject* x = PyNumber_Index(b); + if (!x) return -1; + ival = PyInt_AsSsize_t(x); + Py_DECREF(x); + return ival; +} + +static INLINE int __Pyx_PyObject_IsTrue(PyObject* x) { + if (x == Py_True) return 1; + else if (x == Py_False) return 0; + else return PyObject_IsTrue(x); +} + +static INLINE PY_LONG_LONG __pyx_PyInt_AsLongLong(PyObject* x) { + if (PyInt_CheckExact(x)) { + return PyInt_AS_LONG(x); + } + else if (PyLong_CheckExact(x)) { + return PyLong_AsLongLong(x); + } + else { + PY_LONG_LONG val; + PyObject* tmp = PyNumber_Int(x); if (!tmp) return (PY_LONG_LONG)-1; + val = __pyx_PyInt_AsLongLong(tmp); + Py_DECREF(tmp); + return val; + } +} + +static INLINE unsigned PY_LONG_LONG __pyx_PyInt_AsUnsignedLongLong(PyObject* x) { + if (PyInt_CheckExact(x)) { + long val = PyInt_AS_LONG(x); + if (unlikely(val < 0)) { + PyErr_SetString(PyExc_TypeError, "Negative assignment to unsigned type."); + return (unsigned PY_LONG_LONG)-1; + } + return val; + } + else if (PyLong_CheckExact(x)) { + return PyLong_AsUnsignedLongLong(x); + } + else { + PY_LONG_LONG val; + PyObject* tmp = PyNumber_Int(x); if (!tmp) return (PY_LONG_LONG)-1; + val = __pyx_PyInt_AsUnsignedLongLong(tmp); + Py_DECREF(tmp); + return val; + } +} + + +static INLINE unsigned char __pyx_PyInt_unsigned_char(PyObject* x) { + if (sizeof(unsigned char) < sizeof(long)) { + long long_val = __pyx_PyInt_AsLong(x); + unsigned char val = (unsigned char)long_val; + if (unlikely((val != long_val) || (long_val < 0))) { + PyErr_SetString(PyExc_OverflowError, "value too large to convert to unsigned char"); + return (unsigned char)-1; + } + return val; + } + else { + return __pyx_PyInt_AsLong(x); + } +} + +static INLINE unsigned short __pyx_PyInt_unsigned_short(PyObject* x) { + if (sizeof(unsigned short) < sizeof(long)) { + long long_val = __pyx_PyInt_AsLong(x); + unsigned short val = (unsigned short)long_val; + if (unlikely((val != long_val) || (long_val < 0))) { + PyErr_SetString(PyExc_OverflowError, "value too large to convert to unsigned short"); + return (unsigned short)-1; + } + return val; + } + else { + return __pyx_PyInt_AsLong(x); + } +} + +static INLINE char __pyx_PyInt_char(PyObject* x) { + if (sizeof(char) < sizeof(long)) { + long long_val = __pyx_PyInt_AsLong(x); + char val = (char)long_val; + if (unlikely((val != long_val) )) { + PyErr_SetString(PyExc_OverflowError, "value too large to convert to char"); + return (char)-1; + } + return val; + } + else { + return __pyx_PyInt_AsLong(x); + } +} + +static INLINE short __pyx_PyInt_short(PyObject* x) { + if (sizeof(short) < sizeof(long)) { + long long_val = __pyx_PyInt_AsLong(x); + short val = (short)long_val; + if (unlikely((val != long_val) )) { + PyErr_SetString(PyExc_OverflowError, "value too large to convert to short"); + return (short)-1; + } + return val; + } + else { + return __pyx_PyInt_AsLong(x); + } +} + +static INLINE int __pyx_PyInt_int(PyObject* x) { + if (sizeof(int) < sizeof(long)) { + long long_val = __pyx_PyInt_AsLong(x); + int val = (int)long_val; + if (unlikely((val != long_val) )) { + PyErr_SetString(PyExc_OverflowError, "value too large to convert to int"); + return (int)-1; + } + return val; + } + else { + return __pyx_PyInt_AsLong(x); + } +} + +static INLINE long __pyx_PyInt_long(PyObject* x) { + if (sizeof(long) < sizeof(long)) { + long long_val = __pyx_PyInt_AsLong(x); + long val = (long)long_val; + if (unlikely((val != long_val) )) { + PyErr_SetString(PyExc_OverflowError, "value too large to convert to long"); + return (long)-1; + } + return val; + } + else { + return __pyx_PyInt_AsLong(x); + } +} + +static INLINE signed char __pyx_PyInt_signed_char(PyObject* x) { + if (sizeof(signed char) < sizeof(long)) { + long long_val = __pyx_PyInt_AsLong(x); + signed char val = (signed char)long_val; + if (unlikely((val != long_val) )) { + PyErr_SetString(PyExc_OverflowError, "value too large to convert to signed char"); + return (signed char)-1; + } + return val; + } + else { + return __pyx_PyInt_AsLong(x); + } +} + +static INLINE signed short __pyx_PyInt_signed_short(PyObject* x) { + if (sizeof(signed short) < sizeof(long)) { + long long_val = __pyx_PyInt_AsLong(x); + signed short val = (signed short)long_val; + if (unlikely((val != long_val) )) { + PyErr_SetString(PyExc_OverflowError, "value too large to convert to signed short"); + return (signed short)-1; + } + return val; + } + else { + return __pyx_PyInt_AsLong(x); + } +} + +static INLINE signed int __pyx_PyInt_signed_int(PyObject* x) { + if (sizeof(signed int) < sizeof(long)) { + long long_val = __pyx_PyInt_AsLong(x); + signed int val = (signed int)long_val; + if (unlikely((val != long_val) )) { + PyErr_SetString(PyExc_OverflowError, "value too large to convert to signed int"); + return (signed int)-1; + } + return val; + } + else { + return __pyx_PyInt_AsLong(x); + } +} + +static INLINE signed long __pyx_PyInt_signed_long(PyObject* x) { + if (sizeof(signed long) < sizeof(long)) { + long long_val = __pyx_PyInt_AsLong(x); + signed long val = (signed long)long_val; + if (unlikely((val != long_val) )) { + PyErr_SetString(PyExc_OverflowError, "value too large to convert to signed long"); + return (signed long)-1; + } + return val; + } + else { + return __pyx_PyInt_AsLong(x); + } +} + +static INLINE long double __pyx_PyInt_long_double(PyObject* x) { + if (sizeof(long double) < sizeof(long)) { + long long_val = __pyx_PyInt_AsLong(x); + long double val = (long double)long_val; + if (unlikely((val != long_val) )) { + PyErr_SetString(PyExc_OverflowError, "value too large to convert to long double"); + return (long double)-1; + } + return val; + } + else { + return __pyx_PyInt_AsLong(x); + } +} + diff --git a/sphinx/pycode/pgen2/parse.py b/sphinx/pycode/pgen2/parse.py new file mode 100644 index 000000000..60eec05ea --- /dev/null +++ b/sphinx/pycode/pgen2/parse.py @@ -0,0 +1,201 @@ +# Copyright 2004-2005 Elemental Security, Inc. All Rights Reserved. +# Licensed to PSF under a Contributor Agreement. + +"""Parser engine for the grammar tables generated by pgen. + +The grammar table must be loaded first. + +See Parser/parser.c in the Python distribution for additional info on +how this parsing engine works. + +""" + +# Local imports +from sphinx.pycode.pgen2 import token + +class ParseError(Exception): + """Exception to signal the parser is stuck.""" + + def __init__(self, msg, type, value, context): + Exception.__init__(self, "%s: type=%r, value=%r, context=%r" % + (msg, type, value, context)) + self.msg = msg + self.type = type + self.value = value + self.context = context + +class Parser(object): + """Parser engine. + + The proper usage sequence is: + + p = Parser(grammar, [converter]) # create instance + p.setup([start]) # prepare for parsing + <for each input token>: + if p.addtoken(...): # parse a token; may raise ParseError + break + root = p.rootnode # root of abstract syntax tree + + A Parser instance may be reused by calling setup() repeatedly. + + A Parser instance contains state pertaining to the current token + sequence, and should not be used concurrently by different threads + to parse separate token sequences. + + See driver.py for how to get input tokens by tokenizing a file or + string. + + Parsing is complete when addtoken() returns True; the root of the + abstract syntax tree can then be retrieved from the rootnode + instance variable. When a syntax error occurs, addtoken() raises + the ParseError exception. There is no error recovery; the parser + cannot be used after a syntax error was reported (but it can be + reinitialized by calling setup()). + + """ + + def __init__(self, grammar, convert=None): + """Constructor. + + The grammar argument is a grammar.Grammar instance; see the + grammar module for more information. + + The parser is not ready yet for parsing; you must call the + setup() method to get it started. + + The optional convert argument is a function mapping concrete + syntax tree nodes to abstract syntax tree nodes. If not + given, no conversion is done and the syntax tree produced is + the concrete syntax tree. If given, it must be a function of + two arguments, the first being the grammar (a grammar.Grammar + instance), and the second being the concrete syntax tree node + to be converted. The syntax tree is converted from the bottom + up. + + A concrete syntax tree node is a (type, value, context, nodes) + tuple, where type is the node type (a token or symbol number), + value is None for symbols and a string for tokens, context is + None or an opaque value used for error reporting (typically a + (lineno, offset) pair), and nodes is a list of children for + symbols, and None for tokens. + + An abstract syntax tree node may be anything; this is entirely + up to the converter function. + + """ + self.grammar = grammar + self.convert = convert or (lambda grammar, node: node) + + def setup(self, start=None): + """Prepare for parsing. + + This *must* be called before starting to parse. + + The optional argument is an alternative start symbol; it + defaults to the grammar's start symbol. + + You can use a Parser instance to parse any number of programs; + each time you call setup() the parser is reset to an initial + state determined by the (implicit or explicit) start symbol. + + """ + if start is None: + start = self.grammar.start + # Each stack entry is a tuple: (dfa, state, node). + # A node is a tuple: (type, value, context, children), + # where children is a list of nodes or None, and context may be None. + newnode = (start, None, None, []) + stackentry = (self.grammar.dfas[start], 0, newnode) + self.stack = [stackentry] + self.rootnode = None + self.used_names = set() # Aliased to self.rootnode.used_names in pop() + + def addtoken(self, type, value, context): + """Add a token; return True iff this is the end of the program.""" + # Map from token to label + ilabel = self.classify(type, value, context) + # Loop until the token is shifted; may raise exceptions + while True: + dfa, state, node = self.stack[-1] + states, first = dfa + arcs = states[state] + # Look for a state with this label + for i, newstate in arcs: + t, v = self.grammar.labels[i] + if ilabel == i: + # Look it up in the list of labels + assert t < 256 + # Shift a token; we're done with it + self.shift(type, value, newstate, context) + # Pop while we are in an accept-only state + state = newstate + while states[state] == [(0, state)]: + self.pop() + if not self.stack: + # Done parsing! + return True + dfa, state, node = self.stack[-1] + states, first = dfa + # Done with this token + return False + elif t >= 256: + # See if it's a symbol and if we're in its first set + itsdfa = self.grammar.dfas[t] + itsstates, itsfirst = itsdfa + if ilabel in itsfirst: + # Push a symbol + self.push(t, self.grammar.dfas[t], newstate, context) + break # To continue the outer while loop + else: + if (0, state) in arcs: + # An accepting state, pop it and try something else + self.pop() + if not self.stack: + # Done parsing, but another token is input + raise ParseError("too much input", + type, value, context) + else: + # No success finding a transition + raise ParseError("bad input", type, value, context) + + def classify(self, type, value, context): + """Turn a token into a label. (Internal)""" + if type == token.NAME: + # Keep a listing of all used names + self.used_names.add(value) + # Check for reserved words + ilabel = self.grammar.keywords.get(value) + if ilabel is not None: + return ilabel + ilabel = self.grammar.tokens.get(type) + if ilabel is None: + raise ParseError("bad token", type, value, context) + return ilabel + + def shift(self, type, value, newstate, context): + """Shift a token. (Internal)""" + dfa, state, node = self.stack[-1] + newnode = (type, value, context, None) + newnode = self.convert(self.grammar, newnode) + if newnode is not None: + node[-1].append(newnode) + self.stack[-1] = (dfa, newstate, node) + + def push(self, type, newdfa, newstate, context): + """Push a nonterminal. (Internal)""" + dfa, state, node = self.stack[-1] + newnode = (type, None, context, []) + self.stack[-1] = (dfa, newstate, node) + self.stack.append((newdfa, 0, newnode)) + + def pop(self): + """Pop a nonterminal. (Internal)""" + popdfa, popstate, popnode = self.stack.pop() + newnode = self.convert(self.grammar, popnode) + if newnode is not None: + if self.stack: + dfa, state, node = self.stack[-1] + node[-1].append(newnode) + else: + self.rootnode = newnode + self.rootnode.used_names = self.used_names diff --git a/sphinx/pycode/pgen2/parse.pyx b/sphinx/pycode/pgen2/parse.pyx new file mode 100644 index 000000000..537d73936 --- /dev/null +++ b/sphinx/pycode/pgen2/parse.pyx @@ -0,0 +1,158 @@ +# Copyright 2004-2005 Elemental Security, Inc. All Rights Reserved. +# Licensed to PSF under a Contributor Agreement. + +# Adapted from parse.py to be compiled with Cython by Georg Brandl. + +"""Parser engine for the grammar tables generated by pgen. + +The grammar table must be loaded first. + +See Parser/parser.c in the Python distribution for additional info on +how this parsing engine works. + +""" + +from sphinx.pycode.nodes import Node, Leaf + +DEF NAME = 1 + +class ParseError(Exception): + """Exception to signal the parser is stuck.""" + + def __init__(self, msg, type, value, context): + Exception.__init__(self, "%s: type=%r, value=%r, context=%r" % + (msg, type, value, context)) + self.msg = msg + self.type = type + self.value = value + self.context = context + + +cdef class Parser: + cdef public grammar, stack, rootnode, used_names + cdef _grammar_dfas, _grammar_labels, _grammar_keywords, _grammar_tokens + cdef _grammar_number2symbol + + def __init__(self, grammar, convert=None): + self.grammar = grammar + #self.convert = convert or noconvert + + self._grammar_dfas = grammar.dfas + self._grammar_labels = grammar.labels + self._grammar_keywords = grammar.keywords + self._grammar_tokens = grammar.tokens + self._grammar_number2symbol = grammar.number2symbol + + def setup(self, start=None): + if start is None: + start = self.grammar.start + # Each stack entry is a tuple: (dfa, state, node). + # A node is a tuple: (type, value, context, children), + # where children is a list of nodes or None, and context may be None. + newnode = (start, None, None, []) + stackentry = (self._grammar_dfas[start], 0, newnode) + self.stack = [stackentry] + self.rootnode = None + self.used_names = set() # Aliased to self.rootnode.used_names in pop() + + def addtoken(self, type, value, context): + """Add a token; return True iff this is the end of the program.""" + cdef int ilabel, i, t, state, newstate + # Map from token to label + ilabel = self.classify(type, value, context) + # Loop until the token is shifted; may raise exceptions + while True: + dfa, state, node = self.stack[-1] + states, first = dfa + arcs = states[state] + # Look for a state with this label + for i, newstate in arcs: + t, v = self._grammar_labels[i] + if ilabel == i: + # Look it up in the list of labels + ## assert t < 256 + # Shift a token; we're done with it + self.shift(type, value, newstate, context) + # Pop while we are in an accept-only state + state = newstate + while states[state] == [(0, state)]: + self.pop() + if not self.stack: + # Done parsing! + return True + dfa, state, node = self.stack[-1] + states, first = dfa + # Done with this token + return False + elif t >= 256: + # See if it's a symbol and if we're in its first set + itsdfa = self._grammar_dfas[t] + itsstates, itsfirst = itsdfa + if ilabel in itsfirst: + # Push a symbol + self.push(t, itsdfa, newstate, context) + break # To continue the outer while loop + else: + if (0, state) in arcs: + # An accepting state, pop it and try something else + self.pop() + if not self.stack: + # Done parsing, but another token is input + raise ParseError("too much input", + type, value, context) + else: + # No success finding a transition + raise ParseError("bad input", type, value, context) + + cdef int classify(self, type, value, context): + """Turn a token into a label. (Internal)""" + if type == NAME: + # Keep a listing of all used names + self.used_names.add(value) + # Check for reserved words + ilabel = self._grammar_keywords.get(value) + if ilabel is not None: + return ilabel + ilabel = self._grammar_tokens.get(type) + if ilabel is None: + raise ParseError("bad token", type, value, context) + return ilabel + + cdef void shift(self, type, value, newstate, context): + """Shift a token. (Internal)""" + dfa, state, node = self.stack[-1] + newnode = (type, value, context, None) + newnode = self.convert(newnode) + if newnode is not None: + node[-1].append(newnode) + self.stack[-1] = (dfa, newstate, node) + + cdef void push(self, type, newdfa, newstate, context): + """Push a nonterminal. (Internal)""" + dfa, state, node = self.stack[-1] + newnode = (type, None, context, []) + self.stack[-1] = (dfa, newstate, node) + self.stack.append((newdfa, 0, newnode)) + + cdef void pop(self): + """Pop a nonterminal. (Internal)""" + popdfa, popstate, popnode = self.stack.pop() + newnode = self.convert(popnode) + if newnode is not None: + if self.stack: + dfa, state, node = self.stack[-1] + node[-1].append(newnode) + else: + self.rootnode = newnode + self.rootnode.used_names = self.used_names + + cdef convert(self, raw_node): + type, value, context, children = raw_node + if children or type in self._grammar_number2symbol: + # If there's exactly one child, return that child instead of + # creating a new node. + if len(children) == 1: + return children[0] + return Node(type, children, context=context) + else: + return Leaf(type, value, context=context) diff --git a/sphinx/pycode/pgen2/pgen.py b/sphinx/pycode/pgen2/pgen.py new file mode 100644 index 000000000..d6895eaef --- /dev/null +++ b/sphinx/pycode/pgen2/pgen.py @@ -0,0 +1,384 @@ +# Copyright 2004-2005 Elemental Security, Inc. All Rights Reserved. +# Licensed to PSF under a Contributor Agreement. + +# Pgen imports +from sphinx.pycode.pgen2 import grammar, token, tokenize + +class PgenGrammar(grammar.Grammar): + pass + +class ParserGenerator(object): + + def __init__(self, filename, stream=None): + close_stream = None + if stream is None: + stream = open(filename) + close_stream = stream.close + self.filename = filename + self.stream = stream + self.generator = tokenize.generate_tokens(stream.readline) + self.gettoken() # Initialize lookahead + self.dfas, self.startsymbol = self.parse() + if close_stream is not None: + close_stream() + self.first = {} # map from symbol name to set of tokens + self.addfirstsets() + + def make_grammar(self): + c = PgenGrammar() + names = self.dfas.keys() + names.sort() + names.remove(self.startsymbol) + names.insert(0, self.startsymbol) + for name in names: + i = 256 + len(c.symbol2number) + c.symbol2number[name] = i + c.number2symbol[i] = name + for name in names: + dfa = self.dfas[name] + states = [] + for state in dfa: + arcs = [] + for label, next in state.arcs.iteritems(): + arcs.append((self.make_label(c, label), dfa.index(next))) + if state.isfinal: + arcs.append((0, dfa.index(state))) + states.append(arcs) + c.states.append(states) + c.dfas[c.symbol2number[name]] = (states, self.make_first(c, name)) + c.start = c.symbol2number[self.startsymbol] + return c + + def make_first(self, c, name): + rawfirst = self.first[name] + first = {} + for label in rawfirst: + ilabel = self.make_label(c, label) + ##assert ilabel not in first # XXX failed on <> ... != + first[ilabel] = 1 + return first + + def make_label(self, c, label): + # XXX Maybe this should be a method on a subclass of converter? + ilabel = len(c.labels) + if label[0].isalpha(): + # Either a symbol name or a named token + if label in c.symbol2number: + # A symbol name (a non-terminal) + if label in c.symbol2label: + return c.symbol2label[label] + else: + c.labels.append((c.symbol2number[label], None)) + c.symbol2label[label] = ilabel + return ilabel + else: + # A named token (NAME, NUMBER, STRING) + itoken = getattr(token, label, None) + assert isinstance(itoken, int), label + assert itoken in token.tok_name, label + if itoken in c.tokens: + return c.tokens[itoken] + else: + c.labels.append((itoken, None)) + c.tokens[itoken] = ilabel + return ilabel + else: + # Either a keyword or an operator + assert label[0] in ('"', "'"), label + value = eval(label) + if value[0].isalpha(): + # A keyword + if value in c.keywords: + return c.keywords[value] + else: + c.labels.append((token.NAME, value)) + c.keywords[value] = ilabel + return ilabel + else: + # An operator (any non-numeric token) + itoken = grammar.opmap[value] # Fails if unknown token + if itoken in c.tokens: + return c.tokens[itoken] + else: + c.labels.append((itoken, None)) + c.tokens[itoken] = ilabel + return ilabel + + def addfirstsets(self): + names = self.dfas.keys() + names.sort() + for name in names: + if name not in self.first: + self.calcfirst(name) + #print name, self.first[name].keys() + + def calcfirst(self, name): + dfa = self.dfas[name] + self.first[name] = None # dummy to detect left recursion + state = dfa[0] + totalset = {} + overlapcheck = {} + for label, next in state.arcs.iteritems(): + if label in self.dfas: + if label in self.first: + fset = self.first[label] + if fset is None: + raise ValueError("recursion for rule %r" % name) + else: + self.calcfirst(label) + fset = self.first[label] + totalset.update(fset) + overlapcheck[label] = fset + else: + totalset[label] = 1 + overlapcheck[label] = {label: 1} + inverse = {} + for label, itsfirst in overlapcheck.iteritems(): + for symbol in itsfirst: + if symbol in inverse: + raise ValueError("rule %s is ambiguous; %s is in the" + " first sets of %s as well as %s" % + (name, symbol, label, inverse[symbol])) + inverse[symbol] = label + self.first[name] = totalset + + def parse(self): + dfas = {} + startsymbol = None + # MSTART: (NEWLINE | RULE)* ENDMARKER + while self.type != token.ENDMARKER: + while self.type == token.NEWLINE: + self.gettoken() + # RULE: NAME ':' RHS NEWLINE + name = self.expect(token.NAME) + self.expect(token.OP, ":") + a, z = self.parse_rhs() + self.expect(token.NEWLINE) + #self.dump_nfa(name, a, z) + dfa = self.make_dfa(a, z) + #self.dump_dfa(name, dfa) + oldlen = len(dfa) + self.simplify_dfa(dfa) + newlen = len(dfa) + dfas[name] = dfa + #print name, oldlen, newlen + if startsymbol is None: + startsymbol = name + return dfas, startsymbol + + def make_dfa(self, start, finish): + # To turn an NFA into a DFA, we define the states of the DFA + # to correspond to *sets* of states of the NFA. Then do some + # state reduction. Let's represent sets as dicts with 1 for + # values. + assert isinstance(start, NFAState) + assert isinstance(finish, NFAState) + def closure(state): + base = {} + addclosure(state, base) + return base + def addclosure(state, base): + assert isinstance(state, NFAState) + if state in base: + return + base[state] = 1 + for label, next in state.arcs: + if label is None: + addclosure(next, base) + states = [DFAState(closure(start), finish)] + for state in states: # NB states grows while we're iterating + arcs = {} + for nfastate in state.nfaset: + for label, next in nfastate.arcs: + if label is not None: + addclosure(next, arcs.setdefault(label, {})) + for label, nfaset in arcs.iteritems(): + for st in states: + if st.nfaset == nfaset: + break + else: + st = DFAState(nfaset, finish) + states.append(st) + state.addarc(st, label) + return states # List of DFAState instances; first one is start + + def dump_nfa(self, name, start, finish): + print "Dump of NFA for", name + todo = [start] + for i, state in enumerate(todo): + print " State", i, state is finish and "(final)" or "" + for label, next in state.arcs: + if next in todo: + j = todo.index(next) + else: + j = len(todo) + todo.append(next) + if label is None: + print " -> %d" % j + else: + print " %s -> %d" % (label, j) + + def dump_dfa(self, name, dfa): + print "Dump of DFA for", name + for i, state in enumerate(dfa): + print " State", i, state.isfinal and "(final)" or "" + for label, next in state.arcs.iteritems(): + print " %s -> %d" % (label, dfa.index(next)) + + def simplify_dfa(self, dfa): + # This is not theoretically optimal, but works well enough. + # Algorithm: repeatedly look for two states that have the same + # set of arcs (same labels pointing to the same nodes) and + # unify them, until things stop changing. + + # dfa is a list of DFAState instances + changes = True + while changes: + changes = False + for i, state_i in enumerate(dfa): + for j in range(i+1, len(dfa)): + state_j = dfa[j] + if state_i == state_j: + #print " unify", i, j + del dfa[j] + for state in dfa: + state.unifystate(state_j, state_i) + changes = True + break + + def parse_rhs(self): + # RHS: ALT ('|' ALT)* + a, z = self.parse_alt() + if self.value != "|": + return a, z + else: + aa = NFAState() + zz = NFAState() + aa.addarc(a) + z.addarc(zz) + while self.value == "|": + self.gettoken() + a, z = self.parse_alt() + aa.addarc(a) + z.addarc(zz) + return aa, zz + + def parse_alt(self): + # ALT: ITEM+ + a, b = self.parse_item() + while (self.value in ("(", "[") or + self.type in (token.NAME, token.STRING)): + c, d = self.parse_item() + b.addarc(c) + b = d + return a, b + + def parse_item(self): + # ITEM: '[' RHS ']' | ATOM ['+' | '*'] + if self.value == "[": + self.gettoken() + a, z = self.parse_rhs() + self.expect(token.OP, "]") + a.addarc(z) + return a, z + else: + a, z = self.parse_atom() + value = self.value + if value not in ("+", "*"): + return a, z + self.gettoken() + z.addarc(a) + if value == "+": + return a, z + else: + return a, a + + def parse_atom(self): + # ATOM: '(' RHS ')' | NAME | STRING + if self.value == "(": + self.gettoken() + a, z = self.parse_rhs() + self.expect(token.OP, ")") + return a, z + elif self.type in (token.NAME, token.STRING): + a = NFAState() + z = NFAState() + a.addarc(z, self.value) + self.gettoken() + return a, z + else: + self.raise_error("expected (...) or NAME or STRING, got %s/%s", + self.type, self.value) + + def expect(self, type, value=None): + if self.type != type or (value is not None and self.value != value): + self.raise_error("expected %s/%s, got %s/%s", + type, value, self.type, self.value) + value = self.value + self.gettoken() + return value + + def gettoken(self): + tup = self.generator.next() + while tup[0] in (tokenize.COMMENT, tokenize.NL): + tup = self.generator.next() + self.type, self.value, self.begin, self.end, self.line = tup + #print token.tok_name[self.type], repr(self.value) + + def raise_error(self, msg, *args): + if args: + try: + msg = msg % args + except: + msg = " ".join([msg] + map(str, args)) + raise SyntaxError(msg, (self.filename, self.end[0], + self.end[1], self.line)) + +class NFAState(object): + + def __init__(self): + self.arcs = [] # list of (label, NFAState) pairs + + def addarc(self, next, label=None): + assert label is None or isinstance(label, str) + assert isinstance(next, NFAState) + self.arcs.append((label, next)) + +class DFAState(object): + + def __init__(self, nfaset, final): + assert isinstance(nfaset, dict) + assert isinstance(iter(nfaset).next(), NFAState) + assert isinstance(final, NFAState) + self.nfaset = nfaset + self.isfinal = final in nfaset + self.arcs = {} # map from label to DFAState + + def addarc(self, next, label): + assert isinstance(label, str) + assert label not in self.arcs + assert isinstance(next, DFAState) + self.arcs[label] = next + + def unifystate(self, old, new): + for label, next in self.arcs.iteritems(): + if next is old: + self.arcs[label] = new + + def __eq__(self, other): + # Equality test -- ignore the nfaset instance variable + assert isinstance(other, DFAState) + if self.isfinal != other.isfinal: + return False + # Can't just return self.arcs == other.arcs, because that + # would invoke this method recursively, with cycles... + if len(self.arcs) != len(other.arcs): + return False + for label, next in self.arcs.iteritems(): + if next is not other.arcs.get(label): + return False + return True + +def generate_grammar(filename="Grammar.txt"): + p = ParserGenerator(filename) + return p.make_grammar() diff --git a/sphinx/pycode/pgen2/token.py b/sphinx/pycode/pgen2/token.py new file mode 100755 index 000000000..61468b313 --- /dev/null +++ b/sphinx/pycode/pgen2/token.py @@ -0,0 +1,82 @@ +#! /usr/bin/env python + +"""Token constants (from "token.h").""" + +# Taken from Python (r53757) and modified to include some tokens +# originally monkeypatched in by pgen2.tokenize + +#--start constants-- +ENDMARKER = 0 +NAME = 1 +NUMBER = 2 +STRING = 3 +NEWLINE = 4 +INDENT = 5 +DEDENT = 6 +LPAR = 7 +RPAR = 8 +LSQB = 9 +RSQB = 10 +COLON = 11 +COMMA = 12 +SEMI = 13 +PLUS = 14 +MINUS = 15 +STAR = 16 +SLASH = 17 +VBAR = 18 +AMPER = 19 +LESS = 20 +GREATER = 21 +EQUAL = 22 +DOT = 23 +PERCENT = 24 +BACKQUOTE = 25 +LBRACE = 26 +RBRACE = 27 +EQEQUAL = 28 +NOTEQUAL = 29 +LESSEQUAL = 30 +GREATEREQUAL = 31 +TILDE = 32 +CIRCUMFLEX = 33 +LEFTSHIFT = 34 +RIGHTSHIFT = 35 +DOUBLESTAR = 36 +PLUSEQUAL = 37 +MINEQUAL = 38 +STAREQUAL = 39 +SLASHEQUAL = 40 +PERCENTEQUAL = 41 +AMPEREQUAL = 42 +VBAREQUAL = 43 +CIRCUMFLEXEQUAL = 44 +LEFTSHIFTEQUAL = 45 +RIGHTSHIFTEQUAL = 46 +DOUBLESTAREQUAL = 47 +DOUBLESLASH = 48 +DOUBLESLASHEQUAL = 49 +AT = 50 +OP = 51 +COMMENT = 52 +NL = 53 +RARROW = 54 +ERRORTOKEN = 55 +N_TOKENS = 56 +NT_OFFSET = 256 +#--end constants-- + +tok_name = {} +for _name, _value in globals().items(): + if type(_value) is type(0): + tok_name[_value] = _name + + +def ISTERMINAL(x): + return x < NT_OFFSET + +def ISNONTERMINAL(x): + return x >= NT_OFFSET + +def ISEOF(x): + return x == ENDMARKER diff --git a/sphinx/pycode/pgen2/tokenize.py b/sphinx/pycode/pgen2/tokenize.py new file mode 100644 index 000000000..4489db898 --- /dev/null +++ b/sphinx/pycode/pgen2/tokenize.py @@ -0,0 +1,410 @@ +# Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006 Python Software Foundation. +# All rights reserved. + +"""Tokenization help for Python programs. + +generate_tokens(readline) is a generator that breaks a stream of +text into Python tokens. It accepts a readline-like method which is called +repeatedly to get the next line of input (or "" for EOF). It generates +5-tuples with these members: + + the token type (see token.py) + the token (a string) + the starting (row, column) indices of the token (a 2-tuple of ints) + the ending (row, column) indices of the token (a 2-tuple of ints) + the original line (string) + +It is designed to match the working of the Python tokenizer exactly, except +that it produces COMMENT tokens for comments and gives type OP for all +operators + +Older entry points + tokenize_loop(readline, tokeneater) + tokenize(readline, tokeneater=printtoken) +are the same, except instead of generating tokens, tokeneater is a callback +function to which the 5 fields described above are passed as 5 arguments, +each time a new token is found.""" + +__author__ = 'Ka-Ping Yee <ping@lfw.org>' +__credits__ = \ + 'GvR, ESR, Tim Peters, Thomas Wouters, Fred Drake, Skip Montanaro' + +import string, re +from sphinx.pycode.pgen2.token import * +from sphinx.pycode.pgen2 import token + +__all__ = [x for x in dir(token) if x[0] != '_'] + ["tokenize", + "generate_tokens", "untokenize"] +del token + +def group(*choices): return '(' + '|'.join(choices) + ')' +def any(*choices): return group(*choices) + '*' +def maybe(*choices): return group(*choices) + '?' + +Whitespace = r'[ \f\t]*' +Comment = r'#[^\r\n]*' +Ignore = Whitespace + any(r'\\\r?\n' + Whitespace) + maybe(Comment) +Name = r'[a-zA-Z_]\w*' + +Binnumber = r'0[bB][01]*' +Hexnumber = r'0[xX][\da-fA-F]*[lL]?' +Octnumber = r'0[oO]?[0-7]*[lL]?' +Decnumber = r'[1-9]\d*[lL]?' +Intnumber = group(Binnumber, Hexnumber, Octnumber, Decnumber) +Exponent = r'[eE][-+]?\d+' +Pointfloat = group(r'\d+\.\d*', r'\.\d+') + maybe(Exponent) +Expfloat = r'\d+' + Exponent +Floatnumber = group(Pointfloat, Expfloat) +Imagnumber = group(r'\d+[jJ]', Floatnumber + r'[jJ]') +Number = group(Imagnumber, Floatnumber, Intnumber) + +# Tail end of ' string. +Single = r"[^'\\]*(?:\\.[^'\\]*)*'" +# Tail end of " string. +Double = r'[^"\\]*(?:\\.[^"\\]*)*"' +# Tail end of ''' string. +Single3 = r"[^'\\]*(?:(?:\\.|'(?!''))[^'\\]*)*'''" +# Tail end of """ string. +Double3 = r'[^"\\]*(?:(?:\\.|"(?!""))[^"\\]*)*"""' +Triple = group("[ubUB]?[rR]?'''", '[ubUB]?[rR]?"""') +# Single-line ' or " string. +String = group(r"[uU]?[rR]?'[^\n'\\]*(?:\\.[^\n'\\]*)*'", + r'[uU]?[rR]?"[^\n"\\]*(?:\\.[^\n"\\]*)*"') + +# Because of leftmost-then-longest match semantics, be sure to put the +# longest operators first (e.g., if = came before ==, == would get +# recognized as two instances of =). +Operator = group(r"\*\*=?", r">>=?", r"<<=?", r"<>", r"!=", + r"//=?", r"->", + r"[+\-*/%&|^=<>]=?", + r"~") + +Bracket = '[][(){}]' +Special = group(r'\r?\n', r'[:;.,`@]') +Funny = group(Operator, Bracket, Special) + +PlainToken = group(Number, Funny, String, Name) +Token = Ignore + PlainToken + +# First (or only) line of ' or " string. +ContStr = group(r"[uUbB]?[rR]?'[^\n'\\]*(?:\\.[^\n'\\]*)*" + + group("'", r'\\\r?\n'), + r'[uUbB]?[rR]?"[^\n"\\]*(?:\\.[^\n"\\]*)*' + + group('"', r'\\\r?\n')) +PseudoExtras = group(r'\\\r?\n', Comment, Triple) +PseudoToken = Whitespace + group(PseudoExtras, Number, Funny, ContStr, Name) + +tokenprog, pseudoprog, single3prog, double3prog = map( + re.compile, (Token, PseudoToken, Single3, Double3)) +endprogs = {"'": re.compile(Single), '"': re.compile(Double), + "'''": single3prog, '"""': double3prog, + "r'''": single3prog, 'r"""': double3prog, + "u'''": single3prog, 'u"""': double3prog, + "b'''": single3prog, 'b"""': double3prog, + "ur'''": single3prog, 'ur"""': double3prog, + "br'''": single3prog, 'br"""': double3prog, + "R'''": single3prog, 'R"""': double3prog, + "U'''": single3prog, 'U"""': double3prog, + "B'''": single3prog, 'B"""': double3prog, + "uR'''": single3prog, 'uR"""': double3prog, + "Ur'''": single3prog, 'Ur"""': double3prog, + "UR'''": single3prog, 'UR"""': double3prog, + "bR'''": single3prog, 'bR"""': double3prog, + "Br'''": single3prog, 'Br"""': double3prog, + "BR'''": single3prog, 'BR"""': double3prog, + 'r': None, 'R': None, + 'u': None, 'U': None, + 'b': None, 'B': None} + +triple_quoted = {} +for t in ("'''", '"""', + "r'''", 'r"""', "R'''", 'R"""', + "u'''", 'u"""', "U'''", 'U"""', + "b'''", 'b"""', "B'''", 'B"""', + "ur'''", 'ur"""', "Ur'''", 'Ur"""', + "uR'''", 'uR"""', "UR'''", 'UR"""', + "br'''", 'br"""', "Br'''", 'Br"""', + "bR'''", 'bR"""', "BR'''", 'BR"""',): + triple_quoted[t] = t +single_quoted = {} +for t in ("'", '"', + "r'", 'r"', "R'", 'R"', + "u'", 'u"', "U'", 'U"', + "b'", 'b"', "B'", 'B"', + "ur'", 'ur"', "Ur'", 'Ur"', + "uR'", 'uR"', "UR'", 'UR"', + "br'", 'br"', "Br'", 'Br"', + "bR'", 'bR"', "BR'", 'BR"', ): + single_quoted[t] = t + +tabsize = 8 + +class TokenError(Exception): pass + +class StopTokenizing(Exception): pass + +def printtoken(type, token, (srow, scol), (erow, ecol), line): # for testing + print "%d,%d-%d,%d:\t%s\t%s" % \ + (srow, scol, erow, ecol, tok_name[type], repr(token)) + +def tokenize(readline, tokeneater=printtoken): + """ + The tokenize() function accepts two parameters: one representing the + input stream, and one providing an output mechanism for tokenize(). + + The first parameter, readline, must be a callable object which provides + the same interface as the readline() method of built-in file objects. + Each call to the function should return one line of input as a string. + + The second parameter, tokeneater, must also be a callable object. It is + called once for each token, with five arguments, corresponding to the + tuples generated by generate_tokens(). + """ + try: + tokenize_loop(readline, tokeneater) + except StopTokenizing: + pass + +# backwards compatible interface +def tokenize_loop(readline, tokeneater): + for token_info in generate_tokens(readline): + tokeneater(*token_info) + +class Untokenizer: + + def __init__(self): + self.tokens = [] + self.prev_row = 1 + self.prev_col = 0 + + def add_whitespace(self, start): + row, col = start + assert row <= self.prev_row + col_offset = col - self.prev_col + if col_offset: + self.tokens.append(" " * col_offset) + + def untokenize(self, iterable): + for t in iterable: + if len(t) == 2: + self.compat(t, iterable) + break + tok_type, token, start, end, line = t + self.add_whitespace(start) + self.tokens.append(token) + self.prev_row, self.prev_col = end + if tok_type in (NEWLINE, NL): + self.prev_row += 1 + self.prev_col = 0 + return "".join(self.tokens) + + def compat(self, token, iterable): + startline = False + indents = [] + toks_append = self.tokens.append + toknum, tokval = token + if toknum in (NAME, NUMBER): + tokval += ' ' + if toknum in (NEWLINE, NL): + startline = True + for tok in iterable: + toknum, tokval = tok[:2] + + if toknum in (NAME, NUMBER): + tokval += ' ' + + if toknum == INDENT: + indents.append(tokval) + continue + elif toknum == DEDENT: + indents.pop() + continue + elif toknum in (NEWLINE, NL): + startline = True + elif startline and indents: + toks_append(indents[-1]) + startline = False + toks_append(tokval) + +def untokenize(iterable): + """Transform tokens back into Python source code. + + Each element returned by the iterable must be a token sequence + with at least two elements, a token number and token value. If + only two tokens are passed, the resulting output is poor. + + Round-trip invariant for full input: + Untokenized source will match input source exactly + + Round-trip invariant for limited intput: + # Output text will tokenize the back to the input + t1 = [tok[:2] for tok in generate_tokens(f.readline)] + newcode = untokenize(t1) + readline = iter(newcode.splitlines(1)).next + t2 = [tok[:2] for tokin generate_tokens(readline)] + assert t1 == t2 + """ + ut = Untokenizer() + return ut.untokenize(iterable) + +def generate_tokens(readline): + """ + The generate_tokens() generator requires one argment, readline, which + must be a callable object which provides the same interface as the + readline() method of built-in file objects. Each call to the function + should return one line of input as a string. Alternately, readline + can be a callable function terminating with StopIteration: + readline = open(myfile).next # Example of alternate readline + + The generator produces 5-tuples with these members: the token type; the + token string; a 2-tuple (srow, scol) of ints specifying the row and + column where the token begins in the source; a 2-tuple (erow, ecol) of + ints specifying the row and column where the token ends in the source; + and the line on which the token was found. The line passed is the + logical line; continuation lines are included. + """ + lnum = parenlev = continued = 0 + namechars, numchars = string.ascii_letters + '_', '0123456789' + contstr, needcont = '', 0 + contline = None + indents = [0] + + while 1: # loop over lines in stream + try: + line = readline() + except StopIteration: + line = '' + # if we are not at the end of the file make sure the + # line ends with a newline because the parser depends + # on that. + if line: + line = line.rstrip() + '\n' + lnum = lnum + 1 + pos, max = 0, len(line) + + if contstr: # continued string + if not line: + raise TokenError("EOF in multi-line string", strstart) + endmatch = endprog.match(line) + if endmatch: + pos = end = endmatch.end(0) + yield (STRING, contstr + line[:end], + strstart, (lnum, end), contline + line) + contstr, needcont = '', 0 + contline = None + elif needcont and line[-2:] != '\\\n' and line[-3:] != '\\\r\n': + yield (ERRORTOKEN, contstr + line, + strstart, (lnum, len(line)), contline) + contstr = '' + contline = None + continue + else: + contstr = contstr + line + contline = contline + line + continue + + elif parenlev == 0 and not continued: # new statement + if not line: break + column = 0 + while pos < max: # measure leading whitespace + if line[pos] == ' ': column = column + 1 + elif line[pos] == '\t': column = (column/tabsize + 1)*tabsize + elif line[pos] == '\f': column = 0 + else: break + pos = pos + 1 + if pos == max: break + + if line[pos] in '#\r\n': # skip comments or blank lines + if line[pos] == '#': + comment_token = line[pos:].rstrip('\r\n') + nl_pos = pos + len(comment_token) + yield (COMMENT, comment_token, + (lnum, pos), (lnum, pos + len(comment_token)), line) + yield (NL, line[nl_pos:], + (lnum, nl_pos), (lnum, len(line)), line) + else: + yield ((NL, COMMENT)[line[pos] == '#'], line[pos:], + (lnum, pos), (lnum, len(line)), line) + continue + + if column > indents[-1]: # count indents or dedents + indents.append(column) + yield (INDENT, line[:pos], (lnum, 0), (lnum, pos), line) + while column < indents[-1]: + if column not in indents: + raise IndentationError( + "unindent does not match any outer indentation level", + ("<tokenize>", lnum, pos, line)) + indents = indents[:-1] + yield (DEDENT, '', (lnum, pos), (lnum, pos), line) + + else: # continued statement + if not line: + raise TokenError("EOF in multi-line statement", (lnum, 0)) + continued = 0 + + while pos < max: + pseudomatch = pseudoprog.match(line, pos) + if pseudomatch: # scan for tokens + start, end = pseudomatch.span(1) + spos, epos, pos = (lnum, start), (lnum, end), end + token, initial = line[start:end], line[start] + + if initial in numchars or \ + (initial == '.' and token != '.'): # ordinary number + yield (NUMBER, token, spos, epos, line) + elif initial in '\r\n': + newline = NEWLINE + if parenlev > 0: + newline = NL + yield (newline, token, spos, epos, line) + elif initial == '#': + assert not token.endswith("\n") + yield (COMMENT, token, spos, epos, line) + elif token in triple_quoted: + endprog = endprogs[token] + endmatch = endprog.match(line, pos) + if endmatch: # all on one line + pos = endmatch.end(0) + token = line[start:pos] + yield (STRING, token, spos, (lnum, pos), line) + else: + strstart = (lnum, start) # multiple lines + contstr = line[start:] + contline = line + break + elif initial in single_quoted or \ + token[:2] in single_quoted or \ + token[:3] in single_quoted: + if token[-1] == '\n': # continued string + strstart = (lnum, start) + endprog = (endprogs[initial] or endprogs[token[1]] or + endprogs[token[2]]) + contstr, needcont = line[start:], 1 + contline = line + break + else: # ordinary string + yield (STRING, token, spos, epos, line) + elif initial in namechars: # ordinary name + yield (NAME, token, spos, epos, line) + elif initial == '\\': # continued stmt + # This yield is new; needed for better idempotency: + yield (NL, token, spos, (lnum, pos), line) + continued = 1 + else: + if initial in '([{': parenlev = parenlev + 1 + elif initial in ')]}': parenlev = parenlev - 1 + yield (OP, token, spos, epos, line) + else: + yield (ERRORTOKEN, line[pos], + (lnum, pos), (lnum, pos+1), line) + pos = pos + 1 + + for indent in indents[1:]: # pop remaining indent levels + yield (DEDENT, '', (lnum, 0), (lnum, 0), '') + yield (ENDMARKER, '', (lnum, 0), (lnum, 0), '') + +if __name__ == '__main__': # testing + import sys + if len(sys.argv) > 1: tokenize(open(sys.argv[1]).readline) + else: tokenize(sys.stdin.readline) diff --git a/sphinx/quickstart.py b/sphinx/quickstart.py index 030245355..cfdb97e7f 100644 --- a/sphinx/quickstart.py +++ b/sphinx/quickstart.py @@ -5,8 +5,8 @@ Quickly setup documentation source to work with Sphinx. - :copyright: 2008 by Georg Brandl. - :license: BSD. + :copyright: Copyright 2007-2009 by the Sphinx team, see AUTHORS. + :license: BSD, see LICENSE for details. """ import sys, os, time @@ -15,8 +15,9 @@ from os import path TERM_ENCODING = getattr(sys.stdin, 'encoding', None) from sphinx.util import make_filename -from sphinx.util.console import purple, bold, red, turquoise, nocolor, color_terminal -from sphinx.util.texescape import tex_escape_map +from sphinx.util.console import purple, bold, red, turquoise, \ + nocolor, color_terminal +from sphinx.util import texescape PROMPT_PREFIX = '> ' @@ -29,21 +30,20 @@ QUICKSTART_CONF = '''\ # # This file is execfile()d with the current directory set to its containing dir. # -# The contents of this file are pickled, so don't put values in the namespace -# that aren't pickleable (module imports are okay, they're removed automatically). +# Note that not all possible configuration values are present in this +# autogenerated file. # # All configuration values have a default; values that are commented out # serve to show the default. import sys, os -# If your extensions are in another directory, add it here. If the directory -# is relative to the documentation root, use os.path.abspath to make it -# absolute, like shown here. +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. #sys.path.append(os.path.abspath('.')) -# General configuration -# --------------------- +# -- General configuration ----------------------------------------------------- # Add any Sphinx extension module names here, as strings. They can be extensions # coming with Sphinx (named 'sphinx.ext.*') or your custom ones. @@ -108,14 +108,23 @@ exclude_trees = [%(exclude_trees)s] # The name of the Pygments (syntax highlighting) style to use. pygments_style = 'sphinx' +# A list of ignored prefixes for module index sorting. +#modindex_common_prefix = [] -# Options for HTML output -# ----------------------- -# The style sheet to use for HTML and HTML Help pages. A file of that name -# must exist either in Sphinx' static/ path, or in one of the custom paths -# given in html_static_path. -html_style = 'default.css' +# -- Options for HTML output --------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. Major themes that come with +# Sphinx are currently 'default' and 'sphinxdoc'. +html_theme = 'default' + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +#html_theme_options = {} + +# Add any paths that contain custom themes here, relative to this directory. +#html_theme_path = [] # The name for this set of Sphinx documents. If None, it defaults to # "<project> v<release> documentation". @@ -162,8 +171,8 @@ html_static_path = ['%(dot)sstatic'] # If true, the index is split into individual pages for each letter. #html_split_index = False -# If true, the reST sources are included in the HTML build as _sources/<name>. -#html_copy_source = True +# If true, links to the reST sources are added to the pages. +#html_show_sourcelink = True # If true, an OpenSearch description file will be output, and all pages will # contain a <link> tag referring to it. The value of this option must be the @@ -177,8 +186,7 @@ html_static_path = ['%(dot)sstatic'] htmlhelp_basename = '%(project_fn)sdoc' -# Options for LaTeX output -# ------------------------ +# -- Options for LaTeX output -------------------------------------------------- # The paper size ('letter' or 'a4'). #latex_paper_size = 'letter' @@ -187,7 +195,7 @@ htmlhelp_basename = '%(project_fn)sdoc' #latex_font_size = '10pt' # Grouping the document tree into LaTeX files. List of tuples -# (source start file, target name, title, author, document class [howto/manual]). +# (source start file, target name, title, author, documentclass [howto/manual]). latex_documents = [ ('%(master)s', '%(project_fn)s.tex', ur'%(project_doc_texescaped)s', ur'%(author_texescaped)s', 'manual'), @@ -214,11 +222,12 @@ latex_documents = [ INTERSPHINX_CONFIG = ''' # Example configuration for intersphinx: refer to the Python standard library. -intersphinx_mapping = {'http://docs.python.org/dev': None} +intersphinx_mapping = {'http://docs.python.org/': None} ''' MASTER_FILE = '''\ -.. %(project)s documentation master file, created by sphinx-quickstart on %(now)s. +.. %(project)s documentation master file, created by + sphinx-quickstart on %(now)s. You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. @@ -254,50 +263,62 @@ PAPEROPT_letter = -D latex_paper_size=letter ALLSPHINXOPTS = -d %(rbuilddir)s/doctrees $(PAPEROPT_$(PAPER)) \ $(SPHINXOPTS) %(rsrcdir)s -.PHONY: help clean html web pickle htmlhelp latex changes linkcheck +.PHONY: help clean html dirhtml pickle json htmlhelp qthelp latex changes \ +linkcheck doctest help: \t@echo "Please use \\`make <target>' where <target> is one of" \t@echo " html to make standalone HTML files" +\t@echo " dirhtml to make HTML files named index.html in directories" \t@echo " pickle to make pickle files" \t@echo " json to make JSON files" \t@echo " htmlhelp to make HTML files and a HTML help project" +\t@echo " qthelp to make HTML files and a qthelp project" \t@echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" -\t@echo " changes to make an overview over all changed/added/deprecated items" +\t@echo " changes to make an overview of all changed/added/deprecated items" \t@echo " linkcheck to check all external links for integrity" +\t@echo " doctest to run all doctests embedded in the documentation \ +(if enabled)" clean: \t-rm -rf %(rbuilddir)s/* html: -\tmkdir -p %(rbuilddir)s/html %(rbuilddir)s/doctrees \t$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) %(rbuilddir)s/html \t@echo \t@echo "Build finished. The HTML pages are in %(rbuilddir)s/html." +dirhtml: +\t$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) %(rbuilddir)s/dirhtml +\t@echo +\t@echo "Build finished. The HTML pages are in %(rbuilddir)s/dirhtml." + pickle: -\tmkdir -p %(rbuilddir)s/pickle %(rbuilddir)s/doctrees \t$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) %(rbuilddir)s/pickle \t@echo \t@echo "Build finished; now you can process the pickle files." -web: pickle - json: -\tmkdir -p %(rbuilddir)s/json %(rbuilddir)s/doctrees \t$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) %(rbuilddir)s/json \t@echo \t@echo "Build finished; now you can process the JSON files." htmlhelp: -\tmkdir -p %(rbuilddir)s/htmlhelp %(rbuilddir)s/doctrees \t$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) %(rbuilddir)s/htmlhelp \t@echo \t@echo "Build finished; now you can run HTML Help Workshop with the" \\ \t ".hhp project file in %(rbuilddir)s/htmlhelp." +qthelp: +\t$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) %(rbuilddir)s/qthelp +\t@echo +\t@echo "Build finished; now you can run "qcollectiongenerator" with the" \\ +\t ".qhcp project file in %(rbuilddir)s/qthelp, like this:" +\t@echo "# qcollectiongenerator %(rbuilddir)s/qthelp/%(project)s.qhcp" +\t@echo "To view the help file:" +\t@echo "# assistant -collectionFile %(rbuilddir)s/qthelp/%(project)s.qhc" + latex: -\tmkdir -p %(rbuilddir)s/latex %(rbuilddir)s/doctrees \t$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) %(rbuilddir)s/latex \t@echo \t@echo "Build finished; the LaTeX files are in %(rbuilddir)s/latex." @@ -305,17 +326,135 @@ latex: \t "run these through (pdf)latex." changes: -\tmkdir -p %(rbuilddir)s/changes %(rbuilddir)s/doctrees \t$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) %(rbuilddir)s/changes \t@echo \t@echo "The overview file is in %(rbuilddir)s/changes." linkcheck: -\tmkdir -p %(rbuilddir)s/linkcheck %(rbuilddir)s/doctrees \t$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) %(rbuilddir)s/linkcheck \t@echo \t@echo "Link check complete; look for any errors in the above output " \\ \t "or in %(rbuilddir)s/linkcheck/output.txt." + +doctest: +\t$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) %(rbuilddir)s/doctest +\t@echo "Testing of doctests in the sources finished, look at the " \\ +\t "results in %(rbuilddir)s/doctest/output.txt." +''' + +BATCHFILE = '''\ +@ECHO OFF + +REM Command file for Sphinx documentation + +set SPHINXBUILD=sphinx-build +set ALLSPHINXOPTS=-d %(rbuilddir)s/doctrees %%SPHINXOPTS%% %(rsrcdir)s +if NOT "%%PAPER%%" == "" ( +\tset ALLSPHINXOPTS=-D latex_paper_size=%%PAPER%% %%ALLSPHINXOPTS%% +) + +if "%%1" == "" goto help + +if "%%1" == "help" ( +\t:help +\techo.Please use `make ^<target^>` where ^<target^> is one of +\techo. html to make standalone HTML files +\techo. dirhtml to make HTML files named index.html in directories +\techo. pickle to make pickle files +\techo. json to make JSON files +\techo. htmlhelp to make HTML files and a HTML help project +\techo. qthelp to make HTML files and a qthelp project +\techo. latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter +\techo. changes to make an overview over all changed/added/deprecated items +\techo. linkcheck to check all external links for integrity +\techo. doctest to run all doctests embedded in the documentation if enabled +\tgoto end +) + +if "%%1" == "clean" ( +\tfor /d %%%%i in (%(rbuilddir)s\*) do rmdir /q /s %%%%i +\tdel /q /s %(rbuilddir)s\* +\tgoto end +) + +if "%%1" == "html" ( +\t%%SPHINXBUILD%% -b html %%ALLSPHINXOPTS%% %(rbuilddir)s/html +\techo. +\techo.Build finished. The HTML pages are in %(rbuilddir)s/html. +\tgoto end +) + +if "%%1" == "dirhtml" ( +\t%%SPHINXBUILD%% -b dirhtml %%ALLSPHINXOPTS%% %(rbuilddir)s/dirhtml +\techo. +\techo.Build finished. The HTML pages are in %(rbuilddir)s/dirhtml. +\tgoto end +) + +if "%%1" == "pickle" ( +\t%%SPHINXBUILD%% -b pickle %%ALLSPHINXOPTS%% %(rbuilddir)s/pickle +\techo. +\techo.Build finished; now you can process the pickle files. +\tgoto end +) + +if "%%1" == "json" ( +\t%%SPHINXBUILD%% -b json %%ALLSPHINXOPTS%% %(rbuilddir)s/json +\techo. +\techo.Build finished; now you can process the JSON files. +\tgoto end +) + +if "%%1" == "htmlhelp" ( +\t%%SPHINXBUILD%% -b htmlhelp %%ALLSPHINXOPTS%% %(rbuilddir)s/htmlhelp +\techo. +\techo.Build finished; now you can run HTML Help Workshop with the ^ +.hhp project file in %(rbuilddir)s/htmlhelp. +\tgoto end +) + +if "%%1" == "qthelp" ( +\t%%SPHINXBUILD%% -b qthelp %%ALLSPHINXOPTS%% %(rbuilddir)s/qthelp +\techo. +\techo.Build finished; now you can run "qcollectiongenerator" with the ^ +.qhcp project file in %(rbuilddir)s/qthelp, like this: +\techo.^> qcollectiongenerator %(rbuilddir)s\\qthelp\\%(project)s.qhcp +\techo.To view the help file: +\techo.^> assistant -collectionFile %(rbuilddir)s\\qthelp\\%(project)s.ghc +\tgoto end +) + +if "%%1" == "latex" ( +\t%%SPHINXBUILD%% -b latex %%ALLSPHINXOPTS%% %(rbuilddir)s/latex +\techo. +\techo.Build finished; the LaTeX files are in %(rbuilddir)s/latex. +\tgoto end +) + +if "%%1" == "changes" ( +\t%%SPHINXBUILD%% -b changes %%ALLSPHINXOPTS%% %(rbuilddir)s/changes +\techo. +\techo.The overview file is in %(rbuilddir)s/changes. +\tgoto end +) + +if "%%1" == "linkcheck" ( +\t%%SPHINXBUILD%% -b linkcheck %%ALLSPHINXOPTS%% %(rbuilddir)s/linkcheck +\techo. +\techo.Link check complete; look for any errors in the above output ^ +or in %(rbuilddir)s/linkcheck/output.txt. +\tgoto end +) + +if "%%1" == "doctest" ( +\t%%SPHINXBUILD%% -b doctest %%ALLSPHINXOPTS%% %(rbuilddir)s/doctest +\techo. +\techo.Testing of doctests in the sources finished, look at the ^ +results in %(rbuilddir)s/doctest/output.txt. +\tgoto end +) + +:end ''' @@ -364,8 +503,9 @@ def do_prompt(d, key, text, default=None, validator=nonempty): if TERM_ENCODING: x = x.decode(TERM_ENCODING) else: - print turquoise('* Note: non-ASCII characters entered and terminal ' - 'encoding unknown -- assuming UTF-8 or Latin-1.') + print turquoise('* Note: non-ASCII characters entered ' + 'and terminal encoding unknown -- assuming ' + 'UTF-8 or Latin-1.') try: x = x.decode('utf-8') except UnicodeDecodeError: @@ -379,6 +519,7 @@ def do_prompt(d, key, text, default=None, validator=nonempty): def inner_main(args): d = {} + texescape.init() if not sys.stdout.isatty() or not color_terminal(): nocolor() @@ -399,23 +540,23 @@ Enter the root path for documentation.''' 'selected root path.') print 'sphinx-quickstart will not overwrite existing Sphinx projects.' print - do_prompt(d, 'path', 'Please enter a new root path (or just Enter to exit)', - '', is_path) + do_prompt(d, 'path', 'Please enter a new root path (or just Enter ' + 'to exit)', '', is_path) if not d['path']: sys.exit(1) print ''' You have two options for placing the build directory for Sphinx output. -Either, you use a directory ".build" within the root path, or you separate +Either, you use a directory "_build" within the root path, or you separate "source" and "build" directories within the root path.''' do_prompt(d, 'sep', 'Separate source and build directories (y/N)', 'n', boolean) + print ''' -Inside the root directory, two more directories will be created; ".templates" -for custom HTML templates and ".static" for custom stylesheets and other -static files. Since the leading dot may be inconvenient for Windows users, -you can enter another prefix (such as "_") to replace the dot.''' - do_prompt(d, 'dot', 'Name prefix for templates and static dir', '.', ok) +Inside the root directory, two more directories will be created; "_templates" +for custom HTML templates and "_static" for custom stylesheets and other static +files. You can enter another prefix (such as ".") to replace the underscore.''' + do_prompt(d, 'dot', 'Name prefix for templates and static dir', '_', ok) print ''' The project name will occur in several places in the built documentation.''' @@ -446,26 +587,43 @@ Please indicate if you want to use one of the following Sphinx extensions:''' 'from modules (y/N)', 'n', boolean) do_prompt(d, 'ext_doctest', 'doctest: automatically test code snippets ' 'in doctest blocks (y/N)', 'n', boolean) - do_prompt(d, 'ext_intersphinx', 'intersphinx: link between Sphinx documentation ' - 'of different projects (y/N)', 'n', boolean) + do_prompt(d, 'ext_intersphinx', 'intersphinx: link between Sphinx ' + 'documentation of different projects (y/N)', 'n', boolean) + do_prompt(d, 'ext_todo', 'todo: write "todo" entries ' + 'that can be shown or hidden on build (y/N)', 'n', boolean) + do_prompt(d, 'ext_coverage', 'coverage: checks for documentation ' + 'coverage (y/N)', 'n', boolean) + do_prompt(d, 'ext_pngmath', 'pngmath: include math, rendered ' + 'as PNG images (y/N)', 'n', boolean) + do_prompt(d, 'ext_jsmath', 'jsmath: include math, rendered in the ' + 'browser by JSMath (y/N)', 'n', boolean) + if d['ext_pngmath'] and d['ext_jsmath']: + print '''Note: pngmath and jsmath cannot be enabled at the same time. +pngmath has been deselected.''' + do_prompt(d, 'ext_ifconfig', 'ifconfig: conditional inclusion of ' + 'content based on config values (y/N)', 'n', boolean) print ''' -If you are under Unix, a Makefile can be generated for you so that you +A Makefile and a Windows command file can be generated for you so that you only have to run e.g. `make html' instead of invoking sphinx-build directly.''' - do_prompt(d, 'makefile', 'Create Makefile? (Y/n)', - os.name == 'posix' and 'y' or 'n', boolean) + do_prompt(d, 'makefile', 'Create Makefile? (Y/n)', 'y', boolean) + do_prompt(d, 'batchfile', 'Create Windows command file? (Y/n)', + 'y', boolean) d['project_fn'] = make_filename(d['project']) d['now'] = time.asctime() d['underline'] = len(d['project']) * '=' d['extensions'] = ', '.join( - repr('sphinx.ext.' + name) for name in ('autodoc', 'doctest', 'intersphinx') + repr('sphinx.ext.' + name) + for name in ('autodoc', 'doctest', 'intersphinx', 'todo', 'coverage', + 'pngmath', 'jsmath', 'ifconfig') if d['ext_' + name].upper() in ('Y', 'YES')) d['copyright'] = time.strftime('%Y') + ', ' + d['author'] - d['author_texescaped'] = unicode(d['author']).translate(tex_escape_map) + d['author_texescaped'] = unicode(d['author']).\ + translate(texescape.tex_escape_map) d['project_doc'] = d['project'] + ' Documentation' - d['project_doc_texescaped'] = \ - unicode(d['project'] + ' Documentation').translate(tex_escape_map) + d['project_doc_texescaped'] = unicode(d['project'] + ' Documentation').\ + translate(texescape.tex_escape_map) if not path.isdir(d['path']): mkdir_p(d['path']) @@ -505,16 +663,27 @@ directly.''' f.write((MAKEFILE % d).encode('utf-8')) f.close() + create_batch = d['batchfile'].upper() in ('Y', 'YES') + if create_batch: + d['rsrcdir'] = separate and 'source' or '.' + d['rbuilddir'] = separate and 'build' or d['dot'] + 'build' + f = open(path.join(d['path'], 'make.bat'), 'w') + f.write((BATCHFILE % d).encode('utf-8')) + f.close() + print print bold('Finished: An initial directory structure has been created.') print ''' You should now populate your master file %s and create other documentation -source files. Use the sphinx-build script to build the docs, like so: -''' % masterfile + (create_makefile and ''' - make <builder> -''' or ''' - sphinx-build -b <builder> %s %s -''' % (srcdir, builddir)) +source files. ''' % masterfile + ((create_makefile or create_batch) and '''\ +Use the Makefile to build the docs, like so: + make builder +''' or '''\ +Use the sphinx-build command to build the docs, like so: + sphinx-build -b builder %s %s +''' % (srcdir, builddir)) + '''\ +where "builder" is one of the supported builders, e.g. html, latex or linkcheck. +''' def main(argv=sys.argv): diff --git a/sphinx/roles.py b/sphinx/roles.py index e4a35c634..550deb3ee 100644 --- a/sphinx/roles.py +++ b/sphinx/roles.py @@ -5,8 +5,8 @@ Handlers for additional ReST roles. - :copyright: 2007-2008 by Georg Brandl. - :license: BSD. + :copyright: Copyright 2007-2009 by the Sphinx team, see AUTHORS. + :license: BSD, see LICENSE for details. """ import re @@ -15,9 +15,8 @@ from docutils import nodes, utils from docutils.parsers.rst import roles from sphinx import addnodes +from sphinx.util import ws_re, caption_ref_re -ws_re = re.compile(r'\s+') -caption_ref_re = re.compile(r'^([^<]+?)\s*<(.+)>$') generic_docroles = { 'command' : nodes.strong, @@ -25,7 +24,7 @@ generic_docroles = { 'guilabel' : nodes.strong, 'kbd' : nodes.literal, 'mailheader' : addnodes.literal_emphasis, - 'makevar' : nodes.Text, + 'makevar' : nodes.strong, 'manpage' : addnodes.literal_emphasis, 'mimetype' : addnodes.literal_emphasis, 'newsgroup' : addnodes.literal_emphasis, @@ -34,10 +33,12 @@ generic_docroles = { } for rolename, nodeclass in generic_docroles.iteritems(): - roles.register_generic_role(rolename, nodeclass) + role = roles.GenericRole(rolename, nodeclass) + roles.register_local_role(rolename, role) -def indexmarkup_role(typ, rawtext, etext, lineno, inliner, options={}, content=[]): +def indexmarkup_role(typ, rawtext, etext, lineno, inliner, + options={}, content=[]): env = inliner.document.settings.env if not typ: typ = env.config.default_role @@ -57,13 +58,14 @@ def indexmarkup_role(typ, rawtext, etext, lineno, inliner, options={}, content=[ options, content)[0] return [indexnode, targetnode] + xref_nodes, [] elif typ == 'pep': - indexnode['entries'] = [('single', - _('Python Enhancement Proposals!PEP %s') % text, - targetid, 'PEP %s' % text)] + indexnode['entries'] = [ + ('single', _('Python Enhancement Proposals!PEP %s') % text, + targetid, 'PEP %s' % text)] try: pepnum = int(text) except ValueError: - msg = inliner.reporter.error('invalid PEP number %s' % text, line=lineno) + msg = inliner.reporter.error('invalid PEP number %s' % text, + line=lineno) prb = inliner.problematic(rawtext, rawtext, msg) return [prb], [msg] ref = inliner.document.settings.pep_base_url + 'pep-%04d' % pepnum @@ -77,7 +79,8 @@ def indexmarkup_role(typ, rawtext, etext, lineno, inliner, options={}, content=[ try: rfcnum = int(text) except ValueError: - msg = inliner.reporter.error('invalid RFC number %s' % text, line=lineno) + msg = inliner.reporter.error('invalid RFC number %s' % text, + line=lineno) prb = inliner.problematic(rawtext, rawtext, msg) return [prb], [msg] ref = inliner.document.settings.rfc_base_url + inliner.rfc_url % rfcnum @@ -86,7 +89,7 @@ def indexmarkup_role(typ, rawtext, etext, lineno, inliner, options={}, content=[ rn += sn return [indexnode, targetnode, rn], [] -roles.register_canonical_role('envvar', indexmarkup_role) +roles.register_local_role('envvar', indexmarkup_role) roles.register_local_role('pep', indexmarkup_role) roles.register_local_role('rfc', indexmarkup_role) @@ -97,6 +100,7 @@ innernodetypes = { 'term': nodes.emphasis, 'token': nodes.strong, 'envvar': nodes.strong, + 'download': nodes.strong, 'option': addnodes.literal_emphasis, } @@ -123,11 +127,14 @@ def xfileref_role(typ, rawtext, text, lineno, inliner, options={}, content=[]): return [innernodetypes.get(typ, nodes.literal)( rawtext, text, classes=['xref'])], [] # we want a cross-reference, create the reference node - pnode = addnodes.pending_xref(rawtext, reftype=typ, refcaption=False, - modname=env.currmodule, classname=env.currclass) + nodeclass = (typ == 'download') and addnodes.download_reference or \ + addnodes.pending_xref + pnode = nodeclass(rawtext, reftype=typ, refcaption=False, + modname=env.currmodule, classname=env.currclass) # we may need the line number for warnings pnode.line = lineno - # the link title may differ from the target, but by default they are the same + # the link title may differ from the target, but by default + # they are the same title = target = text titleistarget = True # look if explicit title and target are given with `foo <bar>` syntax @@ -143,8 +150,9 @@ def xfileref_role(typ, rawtext, text, lineno, inliner, options={}, content=[]): # fallback: everything after '<' is the target target = text[brace+1:] title = text[:brace] - # special target for Python object cross-references - if typ in ('data', 'exc', 'func', 'class', 'const', 'attr', 'meth', 'mod', 'obj'): + # special target for Python object cross-references + if typ in ('data', 'exc', 'func', 'class', 'const', 'attr', + 'meth', 'mod', 'obj'): # fix-up parentheses in link title if titleistarget: title = title.lstrip('.') # only has a meaning for the target @@ -166,9 +174,18 @@ def xfileref_role(typ, rawtext, text, lineno, inliner, options={}, content=[]): target = target[1:] pnode['refspecific'] = True # some other special cases for the target - elif typ == 'option' and target[0] in '-/': - # strip option marker from target - target = target[1:] + elif typ == 'option': + program = env.currprogram + if titleistarget: + if ' ' in title and not (title.startswith('/') or + title.startswith('-')): + program, target = re.split(' (?=-|--|/)', title, 1) + program = ws_re.sub('-', program) + target = target.strip() + elif ' ' in target: + program, target = re.split(' (?=-|--|/)', target, 1) + program = ws_re.sub('-', program) + pnode['refprogram'] = program elif typ == 'term': # normalize whitespace in definition terms (if the term reference is # broken over a line, a newline will be in target) @@ -180,18 +197,21 @@ def xfileref_role(typ, rawtext, text, lineno, inliner, options={}, content=[]): # remove all whitespace to avoid referencing problems target = ws_re.sub('', target) pnode['reftarget'] = target - pnode += innernodetypes.get(typ, nodes.literal)(rawtext, title, classes=['xref']) + pnode += innernodetypes.get(typ, nodes.literal)(rawtext, title, + classes=['xref']) return [pnode], [] def menusel_role(typ, rawtext, text, lineno, inliner, options={}, content=[]): return [nodes.emphasis( - rawtext, utils.unescape(text).replace('-->', u'\N{TRIANGULAR BULLET}'))], [] + rawtext, + utils.unescape(text).replace('-->', u'\N{TRIANGULAR BULLET}'))], [] _litvar_re = re.compile('{([^}]+)}') -def emph_literal_role(typ, rawtext, text, lineno, inliner, options={}, content=[]): +def emph_literal_role(typ, rawtext, text, lineno, inliner, + options={}, content=[]): text = utils.unescape(text) pos = 0 retnode = nodes.literal(role=typ.lower()) @@ -206,6 +226,18 @@ def emph_literal_role(typ, rawtext, text, lineno, inliner, options={}, content=[ return [retnode], [] +_abbr_re = re.compile('\((.*)\)$') + +def abbr_role(typ, rawtext, text, lineno, inliner, options={}, content=[]): + text = utils.unescape(text) + m = _abbr_re.search(text) + if m is None: + return [addnodes.abbreviation(text, text)], [] + abbr = text[:m.start()].strip() + expl = m.group(1) + return [addnodes.abbreviation(abbr, abbr, explanation=expl)], [] + + specific_docroles = { 'data': xfileref_role, 'exc': xfileref_role, @@ -217,22 +249,25 @@ specific_docroles = { 'obj': xfileref_role, 'cfunc' : xfileref_role, 'cmember': xfileref_role, - 'cdata' : xfileref_role, - 'ctype' : xfileref_role, - 'cmacro' : xfileref_role, + 'cdata': xfileref_role, + 'ctype': xfileref_role, + 'cmacro': xfileref_role, - 'mod' : xfileref_role, + 'mod': xfileref_role, 'keyword': xfileref_role, 'ref': xfileref_role, - 'token' : xfileref_role, + 'token': xfileref_role, 'term': xfileref_role, 'option': xfileref_role, + 'doc': xfileref_role, + 'download': xfileref_role, - 'menuselection' : menusel_role, - 'file' : emph_literal_role, - 'samp' : emph_literal_role, + 'menuselection': menusel_role, + 'file': emph_literal_role, + 'samp': emph_literal_role, + 'abbr': abbr_role, } for rolename, func in specific_docroles.iteritems(): - roles.register_canonical_role(rolename, func) + roles.register_local_role(rolename, func) diff --git a/sphinx/search.py b/sphinx/search.py index 46ff986dd..fe20c24a5 100644 --- a/sphinx/search.py +++ b/sphinx/search.py @@ -5,8 +5,8 @@ Create a search index for offline search. - :copyright: 2007-2008 by Armin Ronacher. - :license: BSD. + :copyright: Copyright 2007-2009 by the Sphinx team, see AUTHORS. + :license: BSD, see LICENSE for details. """ import re import cPickle as pickle @@ -134,13 +134,16 @@ class IndexBuilder(object): def get_modules(self, fn2index): rv = {} for name, (doc, _, _, _) in self.env.modules.iteritems(): - rv[name] = fn2index[doc] + if doc in fn2index: + rv[name] = fn2index[doc] return rv def get_descrefs(self, fn2index): rv = {} dt = self._desctypes for fullname, (doc, desctype) in self.env.descrefs.iteritems(): + if doc not in fn2index: + continue prefix, name = rpartition(fullname, '.') pdict = rv.setdefault(prefix, {}) try: @@ -156,9 +159,10 @@ class IndexBuilder(object): for k, v in self._mapping.iteritems(): if len(v) == 1: fn, = v - rv[k] = fn2index[fn] + if fn in fn2index: + rv[k] = fn2index[fn] else: - rv[k] = [fn2index[fn] for fn in v] + rv[k] = [fn2index[fn] for fn in v if fn in fn2index] return rv def freeze(self): diff --git a/sphinx/setup_command.py b/sphinx/setup_command.py index 86e84196f..ac395f39b 100644 --- a/sphinx/setup_command.py +++ b/sphinx/setup_command.py @@ -8,8 +8,8 @@ :author: Sebastian Wiesner :contact: basti.wiesner@gmx.net - :copyright: 2008 by Sebastian Wiesner. - :license: MIT. + :copyright: Copyright 2007-2009 by the Sphinx team, see AUTHORS. + :license: BSD, see LICENSE for details. """ import sys @@ -84,6 +84,7 @@ class BuildDoc(Command): from docutils.utils import SystemMessage if isinstance(err, SystemMessage): sys.stderr, darkred('reST markup error:') - print >>sys.stderr, err.args[0].encode('ascii', 'backslashreplace') + print >>sys.stderr, err.args[0].encode('ascii', + 'backslashreplace') else: raise diff --git a/sphinx/static/default.css b/sphinx/static/default.css deleted file mode 100644 index b0b8247ae..000000000 --- a/sphinx/static/default.css +++ /dev/null @@ -1,848 +0,0 @@ -/** - * Sphinx Doc Design - */ - -body { - font-family: sans-serif; - font-size: 100%; - background-color: #11303d; - color: #000; - margin: 0; - padding: 0; -} - -/* :::: LAYOUT :::: */ - -div.document { - background-color: #1c4e63; -} - -div.documentwrapper { - float: left; - width: 100%; -} - -div.bodywrapper { - margin: 0 0 0 230px; -} - -div.body { - background-color: white; - padding: 0 20px 30px 20px; -} - -div.sphinxsidebarwrapper { - padding: 10px 5px 0 10px; -} - -div.sphinxsidebar { - float: left; - width: 230px; - margin-left: -100%; - font-size: 90%; -} - -div.clearer { - clear: both; -} - -div.footer { - color: #fff; - width: 100%; - padding: 9px 0 9px 0; - text-align: center; - font-size: 75%; -} - -div.footer a { - color: #fff; - text-decoration: underline; -} - -div.related { - background-color: #133f52; - color: #fff; - width: 100%; - line-height: 30px; - font-size: 90%; -} - -div.related h3 { - display: none; -} - -div.related ul { - margin: 0; - padding: 0 0 0 10px; - list-style: none; -} - -div.related li { - display: inline; -} - -div.related li.right { - float: right; - margin-right: 5px; -} - -div.related a { - color: white; -} - -/* ::: TOC :::: */ -div.sphinxsidebar h3 { - font-family: 'Trebuchet MS', sans-serif; - color: white; - font-size: 1.4em; - font-weight: normal; - margin: 0; - padding: 0; -} - -div.sphinxsidebar h3 a { - color: white; -} - -div.sphinxsidebar h4 { - font-family: 'Trebuchet MS', sans-serif; - color: white; - font-size: 1.3em; - font-weight: normal; - margin: 5px 0 0 0; - padding: 0; -} - -div.sphinxsidebar p { - color: white; -} - -div.sphinxsidebar p.topless { - margin: 5px 10px 10px 10px; -} - -div.sphinxsidebar ul { - margin: 10px; - padding: 0; - list-style: none; - color: white; -} - -div.sphinxsidebar ul ul, -div.sphinxsidebar ul.want-points { - margin-left: 20px; - list-style: square; -} - -div.sphinxsidebar ul ul { - margin-top: 0; - margin-bottom: 0; -} - -div.sphinxsidebar a { - color: #98dbcc; -} - -div.sphinxsidebar form { - margin-top: 10px; -} - -div.sphinxsidebar input { - border: 1px solid #98dbcc; - font-family: sans-serif; - font-size: 1em; -} - -/* :::: MODULE CLOUD :::: */ -div.modulecloud { - margin: -5px 10px 5px 10px; - padding: 10px; - line-height: 160%; - border: 1px solid #cbe7e5; - background-color: #f2fbfd; -} - -div.modulecloud a { - padding: 0 5px 0 5px; -} - -/* :::: SEARCH :::: */ -ul.search { - margin: 10px 0 0 20px; - padding: 0; -} - -ul.search li { - padding: 5px 0 5px 20px; - background-image: url(file.png); - background-repeat: no-repeat; - background-position: 0 7px; -} - -ul.search li a { - font-weight: bold; -} - -ul.search li div.context { - color: #888; - margin: 2px 0 0 30px; - text-align: left; -} - -ul.keywordmatches li.goodmatch a { - font-weight: bold; -} - -/* :::: COMMON FORM STYLES :::: */ - -div.actions { - padding: 5px 10px 5px 10px; - border-top: 1px solid #cbe7e5; - border-bottom: 1px solid #cbe7e5; - background-color: #e0f6f4; -} - -form dl { - color: #333; -} - -form dt { - clear: both; - float: left; - min-width: 110px; - margin-right: 10px; - padding-top: 2px; -} - -input#homepage { - display: none; -} - -div.error { - margin: 5px 20px 0 0; - padding: 5px; - border: 1px solid #d00; - font-weight: bold; -} - -/* :::: INLINE COMMENTS :::: */ - -div.inlinecomments { - position: absolute; - right: 20px; -} - -div.inlinecomments a.bubble { - display: block; - float: right; - background-image: url(style/comment.png); - background-repeat: no-repeat; - width: 25px; - height: 25px; - text-align: center; - padding-top: 3px; - font-size: 0.9em; - line-height: 14px; - font-weight: bold; - color: black; -} - -div.inlinecomments a.bubble span { - display: none; -} - -div.inlinecomments a.emptybubble { - background-image: url(style/nocomment.png); -} - -div.inlinecomments a.bubble:hover { - background-image: url(style/hovercomment.png); - text-decoration: none; - color: #3ca0a4; -} - -div.inlinecomments div.comments { - float: right; - margin: 25px 5px 0 0; - max-width: 50em; - min-width: 30em; - border: 1px solid #2eabb0; - background-color: #f2fbfd; - z-index: 150; -} - -div#comments { - border: 1px solid #2eabb0; - margin-top: 20px; -} - -div#comments div.nocomments { - padding: 10px; - font-weight: bold; -} - -div.inlinecomments div.comments h3, -div#comments h3 { - margin: 0; - padding: 0; - background-color: #2eabb0; - color: white; - border: none; - padding: 3px; -} - -div.inlinecomments div.comments div.actions { - padding: 4px; - margin: 0; - border-top: none; -} - -div#comments div.comment { - margin: 10px; - border: 1px solid #2eabb0; -} - -div.inlinecomments div.comment h4, -div.commentwindow div.comment h4, -div#comments div.comment h4 { - margin: 10px 0 0 0; - background-color: #2eabb0; - color: white; - border: none; - padding: 1px 4px 1px 4px; -} - -div#comments div.comment h4 { - margin: 0; -} - -div#comments div.comment h4 a { - color: #d5f4f4; -} - -div.inlinecomments div.comment div.text, -div.commentwindow div.comment div.text, -div#comments div.comment div.text { - margin: -5px 0 -5px 0; - padding: 0 10px 0 10px; -} - -div.inlinecomments div.comment div.meta, -div.commentwindow div.comment div.meta, -div#comments div.comment div.meta { - text-align: right; - padding: 2px 10px 2px 0; - font-size: 95%; - color: #538893; - border-top: 1px solid #cbe7e5; - background-color: #e0f6f4; -} - -div.commentwindow { - position: absolute; - width: 500px; - border: 1px solid #cbe7e5; - background-color: #f2fbfd; - display: none; - z-index: 130; -} - -div.commentwindow h3 { - margin: 0; - background-color: #2eabb0; - color: white; - border: none; - padding: 5px; - font-size: 1.5em; - cursor: pointer; -} - -div.commentwindow div.actions { - margin: 10px -10px 0 -10px; - padding: 4px 10px 4px 10px; - color: #538893; -} - -div.commentwindow div.actions input { - border: 1px solid #2eabb0; - background-color: white; - color: #135355; - cursor: pointer; -} - -div.commentwindow div.form { - padding: 0 10px 0 10px; -} - -div.commentwindow div.form input, -div.commentwindow div.form textarea { - border: 1px solid #3c9ea2; - background-color: white; - color: black; -} - -div.commentwindow div.error { - margin: 10px 5px 10px 5px; - background-color: #fbe5dc; - display: none; -} - -div.commentwindow div.form textarea { - width: 99%; -} - -div.commentwindow div.preview { - margin: 10px 0 10px 0; - background-color: #70d0d4; - padding: 0 1px 1px 25px; -} - -div.commentwindow div.preview h4 { - margin: 0 0 -5px -20px; - padding: 4px 0 0 4px; - color: white; - font-size: 1.3em; -} - -div.commentwindow div.preview div.comment { - background-color: #f2fbfd; -} - -div.commentwindow div.preview div.comment h4 { - margin: 10px 0 0 0!important; - padding: 1px 4px 1px 4px!important; - font-size: 1.2em; -} - -/* :::: SUGGEST CHANGES :::: */ -div#suggest-changes-box input, div#suggest-changes-box textarea { - border: 1px solid #ccc; - background-color: white; - color: black; -} - -div#suggest-changes-box textarea { - width: 99%; - height: 400px; -} - - -/* :::: PREVIEW :::: */ -div.preview { - background-image: url(style/preview.png); - padding: 0 20px 20px 20px; - margin-bottom: 30px; -} - - -/* :::: INDEX PAGE :::: */ - -table.contentstable { - width: 90%; -} - -table.contentstable p.biglink { - line-height: 150%; -} - -a.biglink { - font-size: 1.3em; -} - -span.linkdescr { - font-style: italic; - padding-top: 5px; - font-size: 90%; -} - -/* :::: INDEX STYLES :::: */ - -table.indextable td { - text-align: left; - vertical-align: top; -} - -table.indextable dl, table.indextable dd { - margin-top: 0; - margin-bottom: 0; -} - -table.indextable tr.pcap { - height: 10px; -} - -table.indextable tr.cap { - margin-top: 10px; - background-color: #f2f2f2; -} - -img.toggler { - margin-right: 3px; - margin-top: 3px; - cursor: pointer; -} - -form.pfform { - margin: 10px 0 20px 0; -} - -/* :::: GLOBAL STYLES :::: */ - -.docwarning { - background-color: #ffe4e4; - padding: 10px; - margin: 0 -20px 0 -20px; - border-bottom: 1px solid #f66; -} - -p.subhead { - font-weight: bold; - margin-top: 20px; -} - -a { - color: #355f7c; - text-decoration: none; -} - -a:hover { - text-decoration: underline; -} - -div.body h1, -div.body h2, -div.body h3, -div.body h4, -div.body h5, -div.body h6 { - font-family: 'Trebuchet MS', sans-serif; - background-color: #f2f2f2; - font-weight: normal; - color: #20435c; - border-bottom: 1px solid #ccc; - margin: 20px -20px 10px -20px; - padding: 3px 0 3px 10px; -} - -div.body h1 { margin-top: 0; font-size: 200%; } -div.body h2 { font-size: 160%; } -div.body h3 { font-size: 140%; } -div.body h4 { font-size: 120%; } -div.body h5 { font-size: 110%; } -div.body h6 { font-size: 100%; } - -a.headerlink { - color: #c60f0f; - font-size: 0.8em; - padding: 0 4px 0 4px; - text-decoration: none; - visibility: hidden; -} - -h1:hover > a.headerlink, -h2:hover > a.headerlink, -h3:hover > a.headerlink, -h4:hover > a.headerlink, -h5:hover > a.headerlink, -h6:hover > a.headerlink, -dt:hover > a.headerlink { - visibility: visible; -} - -a.headerlink:hover { - background-color: #c60f0f; - color: white; -} - -div.body p, div.body dd, div.body li { - text-align: justify; - line-height: 130%; -} - -div.body p.caption { - text-align: inherit; -} - -div.body td { - text-align: left; -} - -ul.fakelist { - list-style: none; - margin: 10px 0 10px 20px; - padding: 0; -} - -.field-list ul { - padding-left: 1em; -} - -.first { - margin-top: 0 !important; -} - -/* "Footnotes" heading */ -p.rubric { - margin-top: 30px; - font-weight: bold; -} - -/* "Topics" */ - -div.topic { - background-color: #eee; - border: 1px solid #ccc; - padding: 0 7px 0 7px; - margin: 10px 0 10px 0; -} - -p.topic-title { - font-size: 1.1em; - font-weight: bold; - margin-top: 10px; -} - -/* Admonitions */ - -div.admonition { - margin-top: 10px; - margin-bottom: 10px; - padding: 7px; -} - -div.admonition dt { - font-weight: bold; -} - -div.admonition dl { - margin-bottom: 0; -} - -div.admonition p { - display: inline; -} - -div.seealso { - background-color: #ffc; - border: 1px solid #ff6; -} - -div.warning { - background-color: #ffe4e4; - border: 1px solid #f66; -} - -div.note { - background-color: #eee; - border: 1px solid #ccc; -} - -p.admonition-title { - margin: 0px 10px 5px 0px; - font-weight: bold; - display: inline; -} - -p.admonition-title:after { - content: ":"; -} - -div.body p.centered { - text-align: center; - margin-top: 25px; -} - -table.docutils { - border: 0; -} - -table.docutils td, table.docutils th { - padding: 1px 8px 1px 0; - border-top: 0; - border-left: 0; - border-right: 0; - border-bottom: 1px solid #aaa; -} - -table.field-list td, table.field-list th { - border: 0 !important; -} - -table.footnote td, table.footnote th { - border: 0 !important; -} - -.field-list ul { - margin: 0; - padding-left: 1em; -} - -.field-list p { - margin: 0; -} - -dl { - margin-bottom: 15px; - clear: both; -} - -dd p { - margin-top: 0px; -} - -dd ul, dd table { - margin-bottom: 10px; -} - -dd { - margin-top: 3px; - margin-bottom: 10px; - margin-left: 30px; -} - -.refcount { - color: #060; -} - -dt:target, -.highlight { - background-color: #fbe54e; -} - -dl.glossary dt { - font-weight: bold; - font-size: 1.1em; -} - -th { - text-align: left; - padding-right: 5px; -} - -pre { - padding: 5px; - background-color: #efc; - color: #333; - border: 1px solid #ac9; - border-left: none; - border-right: none; - overflow: auto; -} - -td.linenos pre { - padding: 5px 0px; - border: 0; - background-color: transparent; - color: #aaa; -} - -table.highlighttable { - margin-left: 0.5em; -} - -table.highlighttable td { - padding: 0 0.5em 0 0.5em; -} - -tt { - background-color: #ecf0f3; - padding: 0 1px 0 1px; - font-size: 0.95em; -} - -tt.descname { - background-color: transparent; - font-weight: bold; - font-size: 1.2em; -} - -tt.descclassname { - background-color: transparent; -} - -tt.xref, a tt { - background-color: transparent; - font-weight: bold; -} - -.footnote:target { background-color: #ffa } - -h1 tt, h2 tt, h3 tt, h4 tt, h5 tt, h6 tt { - background-color: transparent; -} - -.optional { - font-size: 1.3em; -} - -.versionmodified { - font-style: italic; -} - -form.comment { - margin: 0; - padding: 10px 30px 10px 30px; - background-color: #eee; -} - -form.comment h3 { - background-color: #326591; - color: white; - margin: -10px -30px 10px -30px; - padding: 5px; - font-size: 1.4em; -} - -form.comment input, -form.comment textarea { - border: 1px solid #ccc; - padding: 2px; - font-family: sans-serif; - font-size: 100%; -} - -form.comment input[type="text"] { - width: 240px; -} - -form.comment textarea { - width: 100%; - height: 200px; - margin-bottom: 10px; -} - -.system-message { - background-color: #fda; - padding: 5px; - border: 3px solid red; -} - -div.math { - text-align: center; -} - -span.eqno { - float: right; -} - -img.logo { - border: 0; -} - -/* :::: PRINT :::: */ -@media print { - div.document, - div.documentwrapper, - div.bodywrapper { - margin: 0; - width : 100%; - } - - div.sphinxsidebar, - div.related, - div.footer, - div#comments div.new-comment-box, - #top-link { - display: none; - } -} diff --git a/sphinx/static/rightsidebar.css b/sphinx/static/rightsidebar.css deleted file mode 100644 index bc604a893..000000000 --- a/sphinx/static/rightsidebar.css +++ /dev/null @@ -1,16 +0,0 @@ -/** - * Sphinx Doc Design -- Right Side Bar Overrides - */ - - -div.sphinxsidebar { - float: right; -} - -div.bodywrapper { - margin: 0 230px 0 0; -} - -div.inlinecomments { - right: 250px; -} diff --git a/sphinx/static/stickysidebar.css b/sphinx/static/stickysidebar.css deleted file mode 100644 index dfc99c77a..000000000 --- a/sphinx/static/stickysidebar.css +++ /dev/null @@ -1,19 +0,0 @@ -/** - * Sphinx Doc Design -- Sticky sidebar Overrides - */ - -div.sphinxsidebar { - top: 30px; - left: 0px; - position: fixed; - margin: 0; - float: none; -} - -div.related { - position: fixed; -} - -div.documentwrapper { - margin-top: 30px; -} diff --git a/sphinx/templates/page.html b/sphinx/templates/page.html deleted file mode 100644 index 4de23b133..000000000 --- a/sphinx/templates/page.html +++ /dev/null @@ -1,12 +0,0 @@ -{% extends "layout.html" %} -{% set page_links = [ - (pathto('@rss/' + sourcename), 'application/rss+xml', 'Page Comments'), -] %} -{% block body %} - {% if oldurl %} - <div class="docwarning"> - {% trans %}<strong>Note:</strong> You requested an out-of-date URL from this server. We've tried to redirect you to the new location of this page, but it may not be the right one.{% endtrans %} - </div> - {% endif %} - {{ body }} -{% endblock %} diff --git a/sphinx/texinputs/sphinx.sty b/sphinx/texinputs/sphinx.sty index 209c35f9d..0ce6b8637 100644 --- a/sphinx/texinputs/sphinx.sty +++ b/sphinx/texinputs/sphinx.sty @@ -17,7 +17,15 @@ \RequirePackage{makeidx} \RequirePackage{framed} \RequirePackage{color} +% For highlighted code. \RequirePackage{fancyvrb} +% For table captions. +\RequirePackage{threeparttable} +% Handle footnotes in tables. +\RequirePackage{footnote} +\makesavenoteenv{tabulary} +% For floating figures in the text. +\RequirePackage{wrapfig} % Redefine these colors to your liking in the preamble. \definecolor{TitleColor}{rgb}{0.126,0.263,0.361} @@ -55,11 +63,10 @@ \fi\fi % XeLaTeX can do colors, too -\IfFileExists{ifxetex.sty}{\RequirePackage{ifxetex}}{} -\ifx\ifxetex\undefined\else\ifxetex +\ifx\XeTeXrevision\undefined\else \def\py@NormalColor{\color[rgb]{0.0,0.0,0.0}} \def\py@TitleColor{\color{TitleColor}} -\fi\fi +\fi % Increase printable page size (copied from fullpage.sty) \topmargin 0pt @@ -451,6 +458,20 @@ \fi }{\end{fulllineitems}} +% class method ---------------------------------------------------------- +% \begin{classmethoddesc}[classname]{methodname}{args} +\newcommand{\classmethodline}[3][\@undefined]{ + \py@sigline{class \bfcode{#2}}{#3}} +\newenvironment{classmethoddesc}[3][\@undefined]{ + \begin{fulllineitems} + \ifx\@undefined#1\relax + \classmethodline{#2}{#3} + \else + \def\py@thisclass{#1} + \classmethodline{#2}{#3} + \fi +}{\end{fulllineitems}} + % object data attribute -------------------------------------------------- % \begin{memberdesc}[classname]{membername} \newcommand{\memberline}[2][\py@classbadkey]{% diff --git a/sphinx/texinputs/tabulary.sty b/sphinx/texinputs/tabulary.sty index 2a96de971..ba83c0afb 100644 --- a/sphinx/texinputs/tabulary.sty +++ b/sphinx/texinputs/tabulary.sty @@ -109,6 +109,8 @@ Z \string\tymax: \the\tymax^^J}% \global\advance\TY@linewidth-#1\relax} \def\endtabulary{% \gdef\@halignto{}% + \let\TY@footnote\footnote% + \def\footnote{}% prevent footnotes from doing anything \expandafter\TY@tab\the\toks@ \crcr\omit {\xdef\TY@save@row{}% @@ -172,6 +174,7 @@ Z \message{> tymin}% \TY@checkmin \TY@count\z@ \let\TY@box\TY@box@v + \let\footnote\TY@footnote % restore footnotes {\expandafter\TY@final\the\toks@\endTY@final}% \count@\z@ \@tempswatrue diff --git a/sphinx/templates/changes/frameset.html b/sphinx/themes/basic/changes/frameset.html similarity index 64% rename from sphinx/templates/changes/frameset.html rename to sphinx/themes/basic/changes/frameset.html index 6d0535334..9d9af9eb5 100644 --- a/sphinx/templates/changes/frameset.html +++ b/sphinx/themes/basic/changes/frameset.html @@ -2,7 +2,7 @@ "http://www.w3.org/TR/html4/frameset.dtd"> <html> <head> - <title>{% trans version=version, docstitle=docstitle %}Changes in Version {{ version }} — {{ docstitle }}{% endtrans %} + {% trans version=version|e, docstitle=docstitle|e %}Changes in Version {{ version }} — {{ docstitle }}{% endtrans %} diff --git a/sphinx/templates/changes/rstsource.html b/sphinx/themes/basic/changes/rstsource.html similarity index 70% rename from sphinx/templates/changes/rstsource.html rename to sphinx/themes/basic/changes/rstsource.html index a4b3c53ce..abd12c1d0 100644 --- a/sphinx/templates/changes/rstsource.html +++ b/sphinx/themes/basic/changes/rstsource.html @@ -2,7 +2,7 @@ "http://www.w3.org/TR/html4/loose.dtd"> - {% trans filename=filename, docstitle=docstitle %}{{ filename }} — {{ docstitle }}{% endtrans %} + {% trans filename=filename, docstitle=docstitle|e %}{{ filename }} — {{ docstitle }}{% endtrans %} diff --git a/sphinx/templates/changes/versionchanges.html b/sphinx/themes/basic/changes/versionchanges.html similarity index 76% rename from sphinx/templates/changes/versionchanges.html rename to sphinx/themes/basic/changes/versionchanges.html index 5a58e22a4..09651bf1d 100644 --- a/sphinx/templates/changes/versionchanges.html +++ b/sphinx/themes/basic/changes/versionchanges.html @@ -1,4 +1,4 @@ -{% macro entries changes %} +{% macro entries(changes) %}
      {% for entry, docname, lineno in changes %}
    • {{ entry }}
      • {% endfor %}
    @@ -9,12 +9,12 @@ - {% trans version=version, docstitle=docstitle %}Changes in Version {{ version }} — {{ docstitle }}{% endtrans %} + {% trans version=version|e, docstitle=docstitle|e %}Changes in Version {{ version }} — {{ docstitle }}{% endtrans %}
    -

    {% trans version=version %}Automatically generated list of changes in version {{ version }}{% endtrans %}

    +

    {% trans version=version|e %}Automatically generated list of changes in version {{ version }}{% endtrans %}

    {{ _('Library changes') }}

    {% for modname, changes in libchanges %}

    {{ modname }}

    diff --git a/sphinx/templates/defindex.html b/sphinx/themes/basic/defindex.html similarity index 85% rename from sphinx/templates/defindex.html rename to sphinx/themes/basic/defindex.html index 78ac08016..40f4f4c90 100644 --- a/sphinx/templates/defindex.html +++ b/sphinx/themes/basic/defindex.html @@ -1,11 +1,11 @@ {% extends "layout.html" %} {% set title = _('Overview') %} {% block body %} -

    {{ docstitle }}

    +

    {{ docstitle|e }}

    Welcome! This is - {% block description %}the documentation for {{ project }} - {{ release }}{% if last_updated %}, last updated {{ last_updated }}{% endif %}{% endblock %}. + {% block description %}the documentation for {{ project|e }} + {{ release|e }}{% if last_updated %}, last updated {{ last_updated|e }}{% endif %}{% endblock %}.

    {% block tables %}

    {{ _('Indices and tables:') }}

    diff --git a/sphinx/templates/genindex-single.html b/sphinx/themes/basic/genindex-single.html similarity index 100% rename from sphinx/templates/genindex-single.html rename to sphinx/themes/basic/genindex-single.html diff --git a/sphinx/templates/genindex-split.html b/sphinx/themes/basic/genindex-split.html similarity index 100% rename from sphinx/templates/genindex-split.html rename to sphinx/themes/basic/genindex-split.html diff --git a/sphinx/templates/genindex.html b/sphinx/themes/basic/genindex.html similarity index 100% rename from sphinx/templates/genindex.html rename to sphinx/themes/basic/genindex.html diff --git a/sphinx/templates/layout.html b/sphinx/themes/basic/layout.html similarity index 58% rename from sphinx/templates/layout.html rename to sphinx/themes/basic/layout.html index 45826f803..dd2e2d511 100644 --- a/sphinx/templates/layout.html +++ b/sphinx/themes/basic/layout.html @@ -4,28 +4,30 @@ {%- endblock %} {%- set reldelim1 = reldelim1 is not defined and ' »' or reldelim1 %} {%- set reldelim2 = reldelim2 is not defined and ' |' or reldelim2 %} -{%- macro relbar %} + +{%- macro relbar() %}

    {{ _('Navigation') }}

      {%- for rellink in rellinks %}
    • {{ rellink[3] }} + {{ accesskey(rellink[2]) }}>{{ rellink[3] }} {%- if not loop.first %}{{ reldelim2 }}{% endif %}
      • {%- endfor %} {%- block rootrellink %} -
    • {{ shorttitle }}{{ reldelim1 }}
      • +
    • {{ shorttitle|e }}{{ reldelim1 }}
      • {%- endblock %} {%- for parent in parents %} -
    • {{ parent.title }}{{ reldelim1 }}
      • +
    • {{ parent.title }}{{ reldelim1 }}
      • {%- endfor %} - {%- block relbaritems %}{% endblock %} + {%- block relbaritems %} {% endblock %}
    {%- endmacro %} -{%- macro sidebar %} - {%- if builder != 'htmlhelp' %} + +{%- macro sidebar() %} + {%- if not embedded %}{% if not theme_nosidebar|tobool %}
    {%- block sidebarlogo %} @@ -44,71 +46,69 @@ {%- block sidebarrel %} {%- if prev %}

    {{ _('Previous topic') }}

    -

    {{ prev.title }}

    +

    {{ prev.title }}

    {%- endif %} {%- if next %}

    {{ _('Next topic') }}

    -

    {{ next.title }}

    +

    {{ next.title }}

    {%- endif %} {%- endblock %} - {%- if sourcename %} + {%- block sidebarsourcelink %} + {%- if show_source and has_source and sourcename %}

    {{ _('This Page') }}

    {%- endif %} + {%- endblock %} {%- if customsidebar %} - {{ rendertemplate(customsidebar) }} + {% include customsidebar %} {%- endif %} {%- block sidebarsearch %} {%- if pagename != "search" %} -

    {% if builder == 'web' %}{{ _('Keyword search')}}{% else %}{{ _('Quick search') }}{% endif %}

    -
    - - - -
    - {%- if builder == 'web' %} -

    {{ _('Enter a module, class or function name.') }}

    - {%- endif %} + + {%- endif %} {%- endblock %}
    - {%- endif %} -{%- endmacro -%} + {%- endif %}{% endif %} +{%- endmacro %} {{ metatags }} - {%- if builder != 'htmlhelp' %} - {%- set titlesuffix = " — " + docstitle %} + {%- if not embedded %} + {%- set titlesuffix = " — "|safe + docstitle|e %} + {%- else %} + {%- set titlesuffix = "" %} {%- endif %} {{ title|striptags }}{{ titlesuffix }} - {%- if builder == 'web' %} - - {%- for link, type, title in page_links %} - - {%- endfor %} - {%- else %} - {%- endif %} - {%- if builder != 'htmlhelp' %} + {%- if not embedded %} {%- for scriptfile in script_files %} @@ -116,7 +116,7 @@ {%- endfor %} {%- if use_opensearch %} {%- endif %} {%- if favicon %} @@ -127,12 +127,16 @@ {%- if hasdoc('about') %} {%- endif %} + {%- if hasdoc('genindex') %} + {%- endif %} + {%- if hasdoc('search') %} + {%- endif %} {%- if hasdoc('copyright') %} {%- endif %} - + {%- if parents %} {%- endif %} @@ -143,26 +147,27 @@ {%- endif %} {%- endblock %} -{%- block extrahead %}{% endblock %} +{%- block extrahead %} {% endblock %} +{%- block header %}{% endblock %} {%- block relbar1 %}{{ relbar() }}{% endblock %} -{%- block sidebar1 %}{# possible location for sidebar #}{% endblock %} +{%- block sidebar1 %} {# possible location for sidebar #} {% endblock %} -{%- block document %}
    +{%- block document %}
    - {%- if builder != 'htmlhelp' %} + {%- if not embedded %}{% if not theme_nosidebar|tobool %}
    - {%- endif %} + {%- endif %}{% endif %}
    - {% block body %}{% endblock %} + {% block body %} {% endblock %}
    - {%- if builder != 'htmlhelp' %} + {%- if not embedded %}{% if not theme_nosidebar|tobool %}
    - {%- endif %} + {%- endif %}{% endif %}
    {%- endblock %} @@ -175,15 +180,15 @@ {%- block footer %}
    {%- if hasdoc('copyright') %} - {% trans path=pathto('copyright'), copyright=copyright %}© Copyright {{ copyright }}.{% endtrans %} + {% trans path=pathto('copyright'), copyright=copyright|e %}© Copyright {{ copyright }}.{% endtrans %} {%- else %} - {% trans copyright=copyright %}© Copyright {{ copyright }}.{% endtrans %} + {% trans copyright=copyright|e %}© Copyright {{ copyright }}.{% endtrans %} {%- endif %} {%- if last_updated %} - {% trans last_updated %}Last updated on {{ last_updated }}.{% endtrans %} + {% trans last_updated=last_updated|e %}Last updated on {{ last_updated }}.{% endtrans %} {%- endif %} {%- if show_sphinx %} - {% trans sphinx_version=sphinx_version %}Created using Sphinx {{ sphinx_version }}.{% endtrans %} + {% trans sphinx_version=sphinx_version|e %}Created using Sphinx {{ sphinx_version }}.{% endtrans %} {%- endif %}
    {%- endblock %} diff --git a/sphinx/templates/modindex.html b/sphinx/themes/basic/modindex.html similarity index 56% rename from sphinx/templates/modindex.html rename to sphinx/themes/basic/modindex.html index 692013578..0392edc80 100644 --- a/sphinx/templates/modindex.html +++ b/sphinx/themes/basic/modindex.html @@ -2,7 +2,7 @@ {% set title = _('Global Module Index') %} {% block extrahead %} {{ super() }} -{% if builder != 'htmlhelp' and collapse_modindex %} +{% if not embedded and collapse_modindex %} @@ -11,26 +11,6 @@ {% block body %}

    {{ _('Global Module Index') }}

    -{% if builder == 'web' and freqentries %} -

    {{ _('Most popular modules:') }}

    -
    - {%- for module in freqentries %} - {{ module.name|e }} - {%- endfor %} -
    -{% endif %} -{% if builder == 'web' %} -
    - {{ _('Show modules only available on these platforms') }}:
    - {% for pl in platforms -%} - - - {% endfor %} - - -
    -{% endif %} {%- for letter in letters %} {{ letter }} {% if not loop.last %}| {% endif %} @@ -38,7 +18,7 @@
    - {%- for modname, collapse, cgroup, indent, fname, synops, pform, dep in modindexentries %} + {%- for modname, collapse, cgroup, indent, fname, synops, pform, dep, stripped in modindexentries %} {%- if not modname -%} @@ -46,13 +26,13 @@ {%- endif -%} diff --git a/sphinx/templates/opensearch.xml b/sphinx/themes/basic/opensearch.xml similarity index 56% rename from sphinx/templates/opensearch.xml rename to sphinx/themes/basic/opensearch.xml index 5b6ab7bf6..03875be49 100644 --- a/sphinx/templates/opensearch.xml +++ b/sphinx/themes/basic/opensearch.xml @@ -1,10 +1,10 @@ - {{ project }} - {% trans docstitle=docstitle %}Search {{ docstitle }}{% endtrans %} + {{ project|e }} + {% trans docstitle=docstitle|e %}Search {{ docstitle }}{% endtrans %} utf-8 - {{ docstitle }} -{% block extra %}{# Put e.g. an element here. #}{% endblock %} + {{ docstitle|e }} +{% block extra %} {# Put e.g. an element here. #} {% endblock %} diff --git a/sphinx/themes/basic/page.html b/sphinx/themes/basic/page.html new file mode 100644 index 000000000..17a930165 --- /dev/null +++ b/sphinx/themes/basic/page.html @@ -0,0 +1,4 @@ +{% extends "layout.html" %} +{% block body %} + {{ body }} +{% endblock %} diff --git a/sphinx/templates/search.html b/sphinx/themes/basic/search.html similarity index 80% rename from sphinx/templates/search.html rename to sphinx/themes/basic/search.html index ded792d7b..224d87b86 100644 --- a/sphinx/templates/search.html +++ b/sphinx/themes/basic/search.html @@ -3,11 +3,18 @@ {% set script_files = script_files + ['_static/searchtools.js'] %} {% block body %}

    {{ _('Search') }}

    +
    + +

    + {% trans %}Please activate JavaScript to enable the search + functionality.{% endtrans %} +

    +

    {% trans %}From here you can search these documents. Enter your search words into the box below and click "search". Note that the search function will automatically search for all of the words. Pages - containing less words won't appear in the result list.{% endtrans %} + containing fewer words won't appear in the result list.{% endtrans %}

    diff --git a/sphinx/themes/basic/static/basic.css b/sphinx/themes/basic/static/basic.css new file mode 100644 index 000000000..ed737d3ba --- /dev/null +++ b/sphinx/themes/basic/static/basic.css @@ -0,0 +1,414 @@ +/** + * Sphinx stylesheet -- basic theme + * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + */ + +/* -- main layout ----------------------------------------------------------- */ + +div.documentwrapper { + float: left; + width: 100%; +} + +div.bodywrapper { + margin: 0 0 0 230px; +} + +div.clearer { + clear: both; +} + +/* -- relbar ---------------------------------------------------------------- */ + +div.related { + width: 100%; + font-size: 90%; +} + +div.related h3 { + display: none; +} + +div.related ul { + margin: 0; + padding: 0 0 0 10px; + list-style: none; +} + +div.related li { + display: inline; +} + +div.related li.right { + float: right; + margin-right: 5px; +} + +/* -- sidebar --------------------------------------------------------------- */ + +div.sphinxsidebarwrapper { + padding: 10px 5px 0 10px; +} + +div.sphinxsidebar { + float: left; + width: 230px; + margin-left: -100%; + font-size: 90%; +} + +div.sphinxsidebar ul { + list-style: none; +} + +div.sphinxsidebar ul ul, +div.sphinxsidebar ul.want-points { + margin-left: 20px; + list-style: square; +} + +div.sphinxsidebar ul ul { + margin-top: 0; + margin-bottom: 0; +} + +div.sphinxsidebar form { + margin-top: 10px; +} + +div.sphinxsidebar input { + border: 1px solid #98dbcc; + font-family: sans-serif; + font-size: 1em; +} + +img { + border: 0; +} + +/* -- search page ----------------------------------------------------------- */ + +ul.search { + margin: 10px 0 0 20px; + padding: 0; +} + +ul.search li { + padding: 5px 0 5px 20px; + background-image: url(file.png); + background-repeat: no-repeat; + background-position: 0 7px; +} + +ul.search li a { + font-weight: bold; +} + +ul.search li div.context { + color: #888; + margin: 2px 0 0 30px; + text-align: left; +} + +ul.keywordmatches li.goodmatch a { + font-weight: bold; +} + +/* -- index page ------------------------------------------------------------ */ + +table.contentstable { + width: 90%; +} + +table.contentstable p.biglink { + line-height: 150%; +} + +a.biglink { + font-size: 1.3em; +} + +span.linkdescr { + font-style: italic; + padding-top: 5px; + font-size: 90%; +} + +/* -- general index --------------------------------------------------------- */ + +table.indextable td { + text-align: left; + vertical-align: top; +} + +table.indextable dl, table.indextable dd { + margin-top: 0; + margin-bottom: 0; +} + +table.indextable tr.pcap { + height: 10px; +} + +table.indextable tr.cap { + margin-top: 10px; + background-color: #f2f2f2; +} + +img.toggler { + margin-right: 3px; + margin-top: 3px; + cursor: pointer; +} + +/* -- general body styles --------------------------------------------------- */ + +a.headerlink { + visibility: hidden; +} + +h1:hover > a.headerlink, +h2:hover > a.headerlink, +h3:hover > a.headerlink, +h4:hover > a.headerlink, +h5:hover > a.headerlink, +h6:hover > a.headerlink, +dt:hover > a.headerlink { + visibility: visible; +} + +div.body p.caption { + text-align: inherit; +} + +div.body td { + text-align: left; +} + +.field-list ul { + padding-left: 1em; +} + +.first { + margin-top: 0 !important; +} + +p.rubric { + margin-top: 30px; + font-weight: bold; +} + +/* -- sidebars -------------------------------------------------------------- */ + +div.sidebar { + margin: 0 0 0.5em 1em; + border: 1px solid #ddb; + padding: 7px 7px 0 7px; + background-color: #ffe; + width: 40%; + float: right; +} + +p.sidebar-title { + font-weight: bold; +} + +/* -- topics ---------------------------------------------------------------- */ + +div.topic { + border: 1px solid #ccc; + padding: 7px 7px 0 7px; + margin: 10px 0 10px 0; +} + +p.topic-title { + font-size: 1.1em; + font-weight: bold; + margin-top: 10px; +} + +/* -- admonitions ----------------------------------------------------------- */ + +div.admonition { + margin-top: 10px; + margin-bottom: 10px; + padding: 7px; +} + +div.admonition dt { + font-weight: bold; +} + +div.admonition dl { + margin-bottom: 0; +} + +p.admonition-title { + margin: 0px 10px 5px 0px; + font-weight: bold; +} + +div.body p.centered { + text-align: center; + margin-top: 25px; +} + +/* -- tables ---------------------------------------------------------------- */ + +table.docutils { + border: 0; + border-collapse: collapse; +} + +table.docutils td, table.docutils th { + padding: 1px 8px 1px 0; + border-top: 0; + border-left: 0; + border-right: 0; + border-bottom: 1px solid #aaa; +} + +table.field-list td, table.field-list th { + border: 0 !important; +} + +table.footnote td, table.footnote th { + border: 0 !important; +} + +th { + text-align: left; + padding-right: 5px; +} + +/* -- other body styles ----------------------------------------------------- */ + +dl { + margin-bottom: 15px; +} + +dd p { + margin-top: 0px; +} + +dd ul, dd table { + margin-bottom: 10px; +} + +dd { + margin-top: 3px; + margin-bottom: 10px; + margin-left: 30px; +} + +dt:target, .highlight { + background-color: #fbe54e; +} + +dl.glossary dt { + font-weight: bold; + font-size: 1.1em; +} + +.field-list ul { + margin: 0; + padding-left: 1em; +} + +.field-list p { + margin: 0; +} + +.refcount { + color: #060; +} + +.optional { + font-size: 1.3em; +} + +.versionmodified { + font-style: italic; +} + +.system-message { + background-color: #fda; + padding: 5px; + border: 3px solid red; +} + +.footnote:target { + background-color: #ffa +} + +/* -- code displays --------------------------------------------------------- */ + +pre { + overflow: auto; +} + +td.linenos pre { + padding: 5px 0px; + border: 0; + background-color: transparent; + color: #aaa; +} + +table.highlighttable { + margin-left: 0.5em; +} + +table.highlighttable td { + padding: 0 0.5em 0 0.5em; +} + +tt.descname { + background-color: transparent; + font-weight: bold; + font-size: 1.2em; +} + +tt.descclassname { + background-color: transparent; +} + +tt.xref, a tt { + background-color: transparent; + font-weight: bold; +} + +h1 tt, h2 tt, h3 tt, h4 tt, h5 tt, h6 tt { + background-color: transparent; +} + +/* -- math display ---------------------------------------------------------- */ + +img.math { + vertical-align: middle; +} + +div.math p { + text-align: center; +} + +span.eqno { + float: right; +} + +/* -- printout stylesheet --------------------------------------------------- */ + +@media print { + div.document, + div.documentwrapper, + div.bodywrapper { + margin: 0; + width: 100%; + } + + div.sphinxsidebar, + div.related, + div.footer, + #top-link { + display: none; + } +} diff --git a/sphinx/static/doctools.js b/sphinx/themes/basic/static/doctools.js similarity index 100% rename from sphinx/static/doctools.js rename to sphinx/themes/basic/static/doctools.js diff --git a/sphinx/static/file.png b/sphinx/themes/basic/static/file.png similarity index 100% rename from sphinx/static/file.png rename to sphinx/themes/basic/static/file.png diff --git a/sphinx/static/jquery.js b/sphinx/themes/basic/static/jquery.js similarity index 100% rename from sphinx/static/jquery.js rename to sphinx/themes/basic/static/jquery.js diff --git a/sphinx/static/minus.png b/sphinx/themes/basic/static/minus.png similarity index 100% rename from sphinx/static/minus.png rename to sphinx/themes/basic/static/minus.png diff --git a/sphinx/static/plus.png b/sphinx/themes/basic/static/plus.png similarity index 100% rename from sphinx/static/plus.png rename to sphinx/themes/basic/static/plus.png diff --git a/sphinx/static/searchtools.js b/sphinx/themes/basic/static/searchtools.js similarity index 97% rename from sphinx/static/searchtools.js rename to sphinx/themes/basic/static/searchtools.js index e945d20f0..c4ac17d89 100644 --- a/sphinx/static/searchtools.js +++ b/sphinx/themes/basic/static/searchtools.js @@ -239,7 +239,7 @@ var Search = { }, hasIndex : function() { - return self._index !== null; + return this._index !== null; }, deferQuery : function(query) { @@ -283,7 +283,7 @@ var Search = { if (this.hasIndex()) this.query(query); else - this.setQuery(query); + this.deferQuery(query); }, query : function(query) { @@ -431,7 +431,7 @@ var Search = { listItem.slideDown(5, function() { displayNextItem(); }); - } else { + } else if (DOCUMENTATION_OPTIONS.HAS_SOURCE) { $.get('_sources/' + item[0] + '.txt', function(data) { listItem.append($.makeSearchSummary(data, searchterms, hlterms)); Search.output.append(listItem); @@ -439,6 +439,12 @@ var Search = { displayNextItem(); }); }); + } else { + // no source available, just display title + Search.output.append(listItem); + listItem.slideDown(5, function() { + displayNextItem(); + }); } } // search finished, update title and status message diff --git a/sphinx/themes/basic/theme.conf b/sphinx/themes/basic/theme.conf new file mode 100644 index 000000000..d1fe6d1f9 --- /dev/null +++ b/sphinx/themes/basic/theme.conf @@ -0,0 +1,7 @@ +[theme] +inherit = none +stylesheet = basic.css +pygments_style = none + +[options] +nosidebar = false diff --git a/sphinx/themes/default/static/default.css_t b/sphinx/themes/default/static/default.css_t new file mode 100644 index 000000000..ab2aeb0c1 --- /dev/null +++ b/sphinx/themes/default/static/default.css_t @@ -0,0 +1,234 @@ +/** + * Sphinx stylesheet -- default theme + * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + */ + +@import url("basic.css"); + +/* -- page layout ----------------------------------------------------------- */ + +body { + font-family: {{ theme_bodyfont }}; + font-size: 100%; + background-color: {{ theme_footerbgcolor }}; + color: #000; + margin: 0; + padding: 0; +} + +div.document { + background-color: {{ theme_sidebarbgcolor }}; +} + +div.body { + background-color: {{ theme_bgcolor }}; + color: {{ theme_textcolor }}; + padding: 0 20px 30px 20px; +} + +{%- if theme_rightsidebar|tobool %} +div.bodywrapper { + margin: 0 230px 0 0; +} +{%- endif %} + +div.footer { + color: {{ theme_footertextcolor }}; + width: 100%; + padding: 9px 0 9px 0; + text-align: center; + font-size: 75%; +} + +div.footer a { + color: {{ theme_footertextcolor }}; + text-decoration: underline; +} + +div.related { + background-color: {{ theme_relbarbgcolor }}; + line-height: 30px; + color: {{ theme_relbartextcolor }}; +} + +div.related a { + color: {{ theme_relbarlinkcolor }}; +} + +div.sphinxsidebar { + {%- if theme_stickysidebar|tobool %} + top: 30px; + margin: 0; + position: fixed; + overflow: auto; + height: 100%; + {%- endif %} + {%- if theme_rightsidebar|tobool %} + float: right; + {%- if theme_stickysidebar|tobool %} + right: 0; + {%- endif %} + {%- endif %} +} + +{%- if theme_stickysidebar|tobool %} +/* this is nice, but it it leads to hidden headings when jumping + to an anchor */ +/* +div.related { + position: fixed; +} + +div.documentwrapper { + margin-top: 30px; +} +*/ +{%- endif %} + +div.sphinxsidebar h3 { + font-family: {{ theme_headfont }}; + color: {{ theme_sidebartextcolor }}; + font-size: 1.4em; + font-weight: normal; + margin: 0; + padding: 0; +} + +div.sphinxsidebar h3 a { + color: {{ theme_sidebartextcolor }}; +} + +div.sphinxsidebar h4 { + font-family: {{ theme_headfont }}; + color: {{ theme_sidebartextcolor }}; + font-size: 1.3em; + font-weight: normal; + margin: 5px 0 0 0; + padding: 0; +} + +div.sphinxsidebar p { + color: {{ theme_sidebartextcolor }}; +} + +div.sphinxsidebar p.topless { + margin: 5px 10px 10px 10px; +} + +div.sphinxsidebar ul { + margin: 10px; + padding: 0; + color: {{ theme_sidebartextcolor }}; +} + +div.sphinxsidebar a { + color: {{ theme_sidebarlinkcolor }}; +} + +div.sphinxsidebar input { + border: 1px solid {{ theme_sidebarlinkcolor }}; + font-family: sans-serif; + font-size: 1em; +} + +/* -- body styles ----------------------------------------------------------- */ + +a { + color: {{ theme_linkcolor }}; + text-decoration: none; +} + +a:hover { + text-decoration: underline; +} + +div.body p, div.body dd, div.body li { + text-align: justify; + line-height: 130%; +} + +div.body h1, +div.body h2, +div.body h3, +div.body h4, +div.body h5, +div.body h6 { + font-family: {{ theme_headfont }}; + background-color: {{ theme_headbgcolor }}; + font-weight: normal; + color: {{ theme_headtextcolor }}; + border-bottom: 1px solid #ccc; + margin: 20px -20px 10px -20px; + padding: 3px 0 3px 10px; +} + +div.body h1 { margin-top: 0; font-size: 200%; } +div.body h2 { font-size: 160%; } +div.body h3 { font-size: 140%; } +div.body h4 { font-size: 120%; } +div.body h5 { font-size: 110%; } +div.body h6 { font-size: 100%; } + +a.headerlink { + color: {{ theme_headlinkcolor }}; + font-size: 0.8em; + padding: 0 4px 0 4px; + text-decoration: none; +} + +a.headerlink:hover { + background-color: {{ theme_headlinkcolor }}; + color: white; +} + +div.body p, div.body dd, div.body li { + text-align: justify; + line-height: 130%; +} + +div.admonition p.admonition-title + p { + display: inline; +} + +div.note { + background-color: #eee; + border: 1px solid #ccc; +} + +div.seealso { + background-color: #ffc; + border: 1px solid #ff6; +} + +div.topic { + background-color: #eee; +} + +div.warning { + background-color: #ffe4e4; + border: 1px solid #f66; +} + +p.admonition-title { + display: inline; +} + +p.admonition-title:after { + content: ":"; +} + +pre { + padding: 5px; + background-color: {{ theme_codebgcolor }}; + color: {{ theme_codetextcolor }}; + line-height: 120%; + border: 1px solid #ac9; + border-left: none; + border-right: none; +} + +tt { + background-color: #ecf0f3; + padding: 0 1px 0 1px; + font-size: 0.95em; +} diff --git a/sphinx/themes/default/theme.conf b/sphinx/themes/default/theme.conf new file mode 100644 index 000000000..812330f8a --- /dev/null +++ b/sphinx/themes/default/theme.conf @@ -0,0 +1,28 @@ +[theme] +inherit = basic +stylesheet = default.css +pygments_style = sphinx + +[options] +rightsidebar = false +stickysidebar = false + +footerbgcolor = #11303d +footertextcolor = #ffffff +sidebarbgcolor = #1c4e63 +sidebartextcolor = #ffffff +sidebarlinkcolor = #98dbcc +relbarbgcolor = #133f52 +relbartextcolor = #ffffff +relbarlinkcolor = #ffffff +bgcolor = #ffffff +textcolor = #000000 +headbgcolor = #f2f2f2 +headtextcolor = #20435c +headlinkcolor = #c60f0f +linkcolor = #355f7c +codebgcolor = #eeffcc +codetextcolor = #333333 + +bodyfont = sans-serif +headfont = 'Trebuchet MS', sans-serif diff --git a/sphinx/themes/sphinxdoc/layout.html b/sphinx/themes/sphinxdoc/layout.html new file mode 100644 index 000000000..48d2118e8 --- /dev/null +++ b/sphinx/themes/sphinxdoc/layout.html @@ -0,0 +1,5 @@ +{% extends "basic/layout.html" %} + +{# put the sidebar before the body #} +{% block sidebar1 %}{{ sidebar() }}{% endblock %} +{% block sidebar2 %}{% endblock %} diff --git a/sphinx/static/contents.png b/sphinx/themes/sphinxdoc/static/contents.png similarity index 100% rename from sphinx/static/contents.png rename to sphinx/themes/sphinxdoc/static/contents.png diff --git a/sphinx/static/navigation.png b/sphinx/themes/sphinxdoc/static/navigation.png similarity index 100% rename from sphinx/static/navigation.png rename to sphinx/themes/sphinxdoc/static/navigation.png diff --git a/sphinx/static/sphinxdoc.css b/sphinx/themes/sphinxdoc/static/sphinxdoc.css similarity index 58% rename from sphinx/static/sphinxdoc.css rename to sphinx/themes/sphinxdoc/static/sphinxdoc.css index b4bdaef26..1d11e8b9a 100644 --- a/sphinx/static/sphinxdoc.css +++ b/sphinx/themes/sphinxdoc/static/sphinxdoc.css @@ -1,15 +1,21 @@ /** - * Alternate Sphinx design + * Sphinx stylesheet -- sphinxdoc theme + * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + * * Originally created by Armin Ronacher for Werkzeug, adapted by Georg Brandl. */ +@import url("basic.css"); + +/* -- page layout ----------------------------------------------------------- */ + body { - font-family: 'Lucida Grande', 'Lucida Sans Unicode', 'Geneva', 'Verdana', sans-serif; + font-family: 'Lucida Grande', 'Lucida Sans Unicode', 'Geneva', + 'Verdana', sans-serif; font-size: 14px; letter-spacing: -0.01em; line-height: 150%; text-align: center; - /*background-color: #AFC1C4; */ background-color: #BFD1D4; color: black; padding: 0; @@ -19,137 +25,8 @@ body { min-width: 740px; } -a { - color: #CA7900; - text-decoration: none; -} - -a:hover { - color: #2491CF; -} - -pre { - font-family: 'Consolas', 'Deja Vu Sans Mono', 'Bitstream Vera Sans Mono', monospace; - font-size: 0.95em; - letter-spacing: 0.015em; - padding: 0.5em; - border: 1px solid #ccc; - background-color: #f8f8f8; -} - -td.linenos pre { - padding: 0.5em 0; - border: 0; - background-color: transparent; - color: #aaa; -} - -table.highlighttable { - margin-left: 0.5em; -} - -table.highlighttable td { - padding: 0 0.5em 0 0.5em; -} - -cite, code, tt { - font-family: 'Consolas', 'Deja Vu Sans Mono', 'Bitstream Vera Sans Mono', monospace; - font-size: 0.95em; - letter-spacing: 0.01em; -} - -hr { - border: 1px solid #abc; - margin: 2em; -} - -tt { - background-color: #f2f2f2; - border-bottom: 1px solid #ddd; - color: #333; -} - -tt.descname { - background-color: transparent; - font-weight: bold; - font-size: 1.2em; - border: 0; -} - -tt.descclassname { - background-color: transparent; - border: 0; -} - -tt.xref { - background-color: transparent; - font-weight: bold; - border: 0; -} - -a tt { - background-color: transparent; - font-weight: bold; - border: 0; - color: #CA7900; -} - -a tt:hover { - color: #2491CF; -} - -.field-list ul { - margin: 0; - padding-left: 1em; -} - -.field-list p { - margin: 0; -} - -dl { - margin-bottom: 15px; -} - -dd p { - margin-top: 0px; -} - -dd ul, dd table { - margin-bottom: 10px; -} - -dd { - margin-top: 3px; - margin-bottom: 10px; - margin-left: 30px; -} - -.refcount { - color: #060; -} - -dt:target, -.highlight { - background-color: #fbe54e; -} - -dl.glossary dt { - font-weight: bold; - font-size: 1.1em; -} - -pre { - line-height: 120%; -} - -pre a { - color: inherit; - text-decoration: underline; -} - -.first { - margin-top: 0 !important; +div.documentwrapper { + float: none; } div.document { @@ -159,28 +36,25 @@ div.document { background-repeat: repeat-x; } -/* -div.documentwrapper { - width: 100%; -} -*/ - -div.clearer { - clear: both; +div.bodywrapper { + margin: 0 240px 0 0; + border-right: 1px solid #ccc; } -div.related h3 { - display: none; +div.body { + margin: 0; + padding: 0.5em 20px 20px 20px; +} + +div.related { + font-size: 1em; } div.related ul { background-image: url(navigation.png); height: 2em; - list-style: none; border-top: 1px solid #ddd; border-bottom: 1px solid #ddd; - margin: 0; - padding-left: 10px; } div.related ul li { @@ -206,18 +80,8 @@ div.related ul li a:hover { color: #3CA8E7; } -div.body { - margin: 0; - padding: 0.5em 20px 20px 20px; -} - -div.bodywrapper { - margin: 0 240px 0 0; - border-right: 1px solid #ccc; -} - -div.body a { - text-decoration: underline; +div.sphinxsidebarwrapper { + padding: 0; } div.sphinxsidebar { @@ -225,13 +89,13 @@ div.sphinxsidebar { padding: 0.5em 15px 15px 0; width: 210px; float: right; + font-size: 1em; text-align: left; -/* margin-left: -100%; */ } -div.sphinxsidebar h4, div.sphinxsidebar h3 { +div.sphinxsidebar h3, div.sphinxsidebar h4 { margin: 1em 0 0.5em 0; - font-size: 0.9em; + font-size: 1em; padding: 0.1em 0 0.1em 0.5em; color: white; border: 1px solid #86989B; @@ -245,22 +109,45 @@ div.sphinxsidebar h3 a { div.sphinxsidebar ul { padding-left: 1.5em; margin-top: 7px; - list-style: none; padding: 0; line-height: 130%; } div.sphinxsidebar ul ul { - list-style: square; margin-left: 20px; } -p { +div.footer { + background-color: #E3EFF1; + color: #86989B; + padding: 3px 8px 3px 0; + clear: both; + font-size: 0.8em; + text-align: right; +} + +div.footer a { + color: #86989B; + text-decoration: underline; +} + +/* -- body styles ----------------------------------------------------------- */ + +p { margin: 0.8em 0 0.5em 0; } -p.rubric { - font-weight: bold; +a { + color: #CA7900; + text-decoration: none; +} + +a:hover { + color: #2491CF; +} + +div.body a { + text-decoration: underline; } h1 { @@ -303,6 +190,82 @@ h5 a.anchor:hover, h6 a.anchor:hover { background-color: #eee; } +a.headerlink { + color: #c60f0f!important; + font-size: 1em; + margin-left: 6px; + padding: 0 4px 0 4px; + text-decoration: none!important; +} + +a.headerlink:hover { + background-color: #ccc; + color: white!important; +} + +cite, code, tt { + font-family: 'Consolas', 'Deja Vu Sans Mono', + 'Bitstream Vera Sans Mono', monospace; + font-size: 0.95em; + letter-spacing: 0.01em; +} + +tt { + background-color: #f2f2f2; + border-bottom: 1px solid #ddd; + color: #333; +} + +tt.descname, tt.descclassname, tt.xref { + border: 0; +} + +hr { + border: 1px solid #abc; + margin: 2em; +} + +a tt { + border: 0; + color: #CA7900; +} + +a tt:hover { + color: #2491CF; +} + +pre { + font-family: 'Consolas', 'Deja Vu Sans Mono', + 'Bitstream Vera Sans Mono', monospace; + font-size: 0.95em; + letter-spacing: 0.015em; + line-height: 120%; + padding: 0.5em; + border: 1px solid #ccc; + background-color: #f8f8f8; +} + +pre a { + color: inherit; + text-decoration: underline; +} + +td.linenos pre { + padding: 0.5em 0; +} + +div.quotebar { + background-color: #f8f8f8; + max-width: 250px; + float: right; + padding: 2px 7px; + border: 1px solid #ccc; +} + +div.topic { + background-color: #f8f8f8; +} + table { border-collapse: collapse; margin: 0 -0.5em 0 -0.5em; @@ -312,58 +275,12 @@ table td, table th { padding: 0.2em 0.5em 0.2em 0.5em; } -div.footer { - background-color: #E3EFF1; - color: #86989B; - padding: 3px 8px 3px 0; - clear: both; - font-size: 0.8em; - text-align: right; -} - -div.footer a { - color: #86989B; - text-decoration: underline; -} - -div.pagination { - margin-top: 2em; - padding-top: 0.5em; - border-top: 1px solid black; - text-align: center; -} - -div.sphinxsidebar ul.toc { - margin: 1em 0 1em 0; - padding: 0 0 0 0.5em; - list-style: none; -} - -div.sphinxsidebar ul.toc li { - margin: 0.5em 0 0.5em 0; - font-size: 0.9em; - line-height: 130%; -} - -div.sphinxsidebar ul.toc li p { - margin: 0; - padding: 0; -} - -div.sphinxsidebar ul.toc ul { - margin: 0.2em 0 0.2em 0; - padding: 0 0 0 1.8em; -} - -div.sphinxsidebar ul.toc ul li { - padding: 0; -} - div.admonition, div.warning { font-size: 0.9em; - margin: 1em 0 0 0; + margin: 1em 0 1em 0; border: 1px solid #86989B; background-color: #f7f7f7; + padding: 0; } div.admonition p, div.warning p { @@ -408,113 +325,3 @@ div.versioninfo { line-height: 1.3em; font-size: 0.9em; } - - -a.headerlink { - color: #c60f0f!important; - font-size: 1em; - margin-left: 6px; - padding: 0 4px 0 4px; - text-decoration: none!important; - visibility: hidden; -} - -h1:hover > a.headerlink, -h2:hover > a.headerlink, -h3:hover > a.headerlink, -h4:hover > a.headerlink, -h5:hover > a.headerlink, -h6:hover > a.headerlink, -dt:hover > a.headerlink { - visibility: visible; -} - -a.headerlink:hover { - background-color: #ccc; - color: white!important; -} - -table.indextable td { - text-align: left; - vertical-align: top; -} - -table.indextable dl, table.indextable dd { - margin-top: 0; - margin-bottom: 0; -} - -table.indextable tr.pcap { - height: 10px; -} - -table.indextable tr.cap { - margin-top: 10px; - background-color: #f2f2f2; -} - -img.toggler { - margin-right: 3px; - margin-top: 3px; - cursor: pointer; -} - -form.pfform { - margin: 10px 0 20px 0; -} - -table.contentstable { - width: 90%; -} - -table.contentstable p.biglink { - line-height: 150%; -} - -a.biglink { - font-size: 1.3em; -} - -span.linkdescr { - font-style: italic; - padding-top: 5px; - font-size: 90%; -} - -ul.search { - margin: 10px 0 0 20px; - padding: 0; -} - -ul.search li { - padding: 5px 0 5px 20px; - background-image: url(file.png); - background-repeat: no-repeat; - background-position: 0 7px; -} - -ul.search li a { - font-weight: bold; -} - -ul.search li div.context { - color: #888; - margin: 2px 0 0 30px; - text-align: left; -} - -ul.keywordmatches li.goodmatch a { - font-weight: bold; -} - -div.math { - text-align: center; -} - -span.eqno { - float: right; -} - -img.logo { - border: 0; -} diff --git a/sphinx/themes/sphinxdoc/theme.conf b/sphinx/themes/sphinxdoc/theme.conf new file mode 100644 index 000000000..9a22fefd3 --- /dev/null +++ b/sphinx/themes/sphinxdoc/theme.conf @@ -0,0 +1,4 @@ +[theme] +inherit = basic +stylesheet = sphinxdoc.css +pygments_style = friendly diff --git a/sphinx/static/traditional.css b/sphinx/themes/traditional/static/traditional.css similarity index 100% rename from sphinx/static/traditional.css rename to sphinx/themes/traditional/static/traditional.css diff --git a/sphinx/themes/traditional/theme.conf b/sphinx/themes/traditional/theme.conf new file mode 100644 index 000000000..02b77833e --- /dev/null +++ b/sphinx/themes/traditional/theme.conf @@ -0,0 +1,3 @@ +[theme] +inherit = basic +stylesheet = traditional.css diff --git a/sphinx/theming.py b/sphinx/theming.py new file mode 100644 index 000000000..77c3137c7 --- /dev/null +++ b/sphinx/theming.py @@ -0,0 +1,159 @@ +# -*- coding: utf-8 -*- +""" + sphinx.theming + ~~~~~~~~~~~~~~ + + Theming support for HTML builders. + + :copyright: Copyright 2007-2009 by the Sphinx team, see AUTHORS. + :license: BSD, see LICENSE for details. +""" + +import os +import shutil +import zipfile +import tempfile +import ConfigParser +from os import path + +from sphinx.errors import ThemeError + + +NODEFAULT = object() +THEMECONF = 'theme.conf' + +class Theme(object): + """ + Represents the theme chosen in the configuration. + """ + themes = {} + + @classmethod + def init_themes(cls, builder): + """Search all theme paths for available themes.""" + cls.themepath = list(builder.config.html_theme_path) + cls.themepath.append( + path.join(path.abspath(path.dirname(__file__)), 'themes')) + + for themedir in cls.themepath[::-1]: + themedir = path.join(builder.confdir, themedir) + if not path.isdir(themedir): + continue + for theme in os.listdir(themedir): + if theme.lower().endswith('.zip'): + try: + zfile = zipfile.ZipFile(path.join(themedir, theme)) + if THEMECONF not in zfile.namelist(): + continue + tname = theme[:-4] + tinfo = zfile + except Exception: + builder.warn('file %r on theme path is not a valid ' + 'zipfile or contains no theme' % theme) + continue + else: + if not path.isfile(path.join(themedir, theme, THEMECONF)): + continue + tname = theme + tinfo = None + cls.themes[tname] = (path.join(themedir, theme), tinfo) + + def __init__(self, name): + if name not in self.themes: + raise ThemeError('no theme named %r found ' + '(missing theme.conf?)' % name) + self.name = name + + tdir, tinfo = self.themes[name] + if tinfo is None: + # already a directory, do nothing + self.themedir = tdir + self.themedir_created = False + else: + # extract the theme to a temp directory + self.themedir = tempfile.mkdtemp('sxt') + self.themedir_created = True + for name in tinfo.namelist(): + if name.endswith('/'): continue + dirname = path.dirname(name) + if not path.isdir(path.join(self.themedir, dirname)): + os.makedirs(path.join(self.themedir, dirname)) + fp = open(path.join(self.themedir, name), 'w') + fp.write(tinfo.read(name)) + fp.close() + + self.themeconf = ConfigParser.RawConfigParser() + self.themeconf.read(path.join(self.themedir, THEMECONF)) + + try: + inherit = self.themeconf.get('theme', 'inherit') + except ConfigParser.NoOptionError: + raise ThemeError('theme %r doesn\'t have "inherit" setting' % name) + if inherit == 'none': + self.base = None + elif inherit not in self.themes: + raise ThemeError('no theme named %r found, inherited by %r' % + (inherit, name)) + else: + self.base = Theme(inherit) + + def get_confstr(self, section, name, default=NODEFAULT): + """ + Return the value for a theme configuration setting, searching the + base theme chain. + """ + try: + return self.themeconf.get(section, name) + except (ConfigParser.NoOptionError, ConfigParser.NoSectionError): + if self.base is not None: + return self.base.get_confstr(section, name, default) + if default is NODEFAULT: + raise ThemeError('setting %s.%s occurs in none of the ' + 'searched theme configs' % (section, name)) + else: + return default + + def get_options(self, overrides): + """ + Return a dictionary of theme options and their values. + """ + chain = [self.themeconf] + base = self.base + while base is not None: + chain.append(base.themeconf) + base = base.base + options = {} + for conf in reversed(chain): + try: + options.update(conf.items('options')) + except ConfigParser.NoSectionError: + pass + for option, value in overrides.iteritems(): + if option not in options: + raise ThemeError('unsupported theme option %r given' % option) + options[option] = value + return options + + def get_dirchain(self): + """ + Return a list of theme directories, beginning with this theme's, + then the base theme's, then that one's base theme's, etc. + """ + chain = [self.themedir] + base = self.base + while base is not None: + chain.append(base.themedir) + base = base.base + return chain + + def cleanup(self): + """ + Remove temporary directories. + """ + if self.themedir_created: + try: + shutil.rmtree(self.themedir) + except Exception: + pass + if self.base: + self.base.cleanup() diff --git a/sphinx/util/__init__.py b/sphinx/util/__init__.py index 662523454..c03016a40 100644 --- a/sphinx/util/__init__.py +++ b/sphinx/util/__init__.py @@ -5,19 +5,28 @@ Utility functions for Sphinx. - :copyright: 2007-2008 by Georg Brandl. - :license: BSD. + :copyright: Copyright 2007-2009 by the Sphinx team, see AUTHORS. + :license: BSD, see LICENSE for details. """ import os import re import sys +import time +import types +import shutil import fnmatch import tempfile +import posixpath import traceback from os import path +# Generally useful regular expressions. +ws_re = re.compile(r'\s+') +caption_ref_re = re.compile(r'^([^<]+?)\s*<(.+)>$') +url_re = re.compile(r'(?P.+)://.*') + # SEP separates path elements in the canonical file names # # Define SEP as a manifest constant, not so much because we expect it to change @@ -31,6 +40,8 @@ def os_path(canonicalpath): def relative_uri(base, to): """Return a relative URL from ``base`` to ``to``.""" + if to.startswith(SEP): + return to b2 = base.split(SEP) t2 = to.split(SEP) # remove common segments @@ -42,6 +53,11 @@ def relative_uri(base, to): return ('..' + SEP) * (len(b2)-1) + SEP.join(t2) +def docname_join(basedocname, docname): + return posixpath.normpath( + posixpath.join('/' + basedocname, '..', docname))[1:] + + def ensuredir(path): """Ensure that a path exists.""" try: @@ -260,3 +276,175 @@ no_fn_re = re.compile(r'[^a-zA-Z0-9_-]') def make_filename(string): return no_fn_re.sub('', string) + + +def nested_parse_with_titles(state, content, node): + # hack around title style bookkeeping + surrounding_title_styles = state.memo.title_styles + surrounding_section_level = state.memo.section_level + state.memo.title_styles = [] + state.memo.section_level = 0 + try: + return state.nested_parse(content, 0, node, match_titles=1) + finally: + state.memo.title_styles = surrounding_title_styles + state.memo.section_level = surrounding_section_level + + +def ustrftime(format, *args): + # strftime for unicode strings + return time.strftime(unicode(format).encode('utf-8'), *args).decode('utf-8') + + +class Tee(object): + """ + File-like object writing to two streams. + """ + def __init__(self, stream1, stream2): + self.stream1 = stream1 + self.stream2 = stream2 + + def write(self, text): + self.stream1.write(text) + self.stream2.write(text) + + +class FilenameUniqDict(dict): + """ + A dictionary that automatically generates unique names for its keys, + interpreted as filenames, and keeps track of a set of docnames they + appear in. Used for images and downloadable files in the environment. + """ + def __init__(self): + self._existing = set() + + def add_file(self, docname, newfile): + if newfile in self: + self[newfile][0].add(docname) + return self[newfile][1] + uniquename = path.basename(newfile) + base, ext = path.splitext(uniquename) + i = 0 + while uniquename in self._existing: + i += 1 + uniquename = '%s%s%s' % (base, i, ext) + self[newfile] = (set([docname]), uniquename) + self._existing.add(uniquename) + return uniquename + + def purge_doc(self, docname): + for filename, (docs, _) in self.items(): + docs.discard(docname) + #if not docs: + # del self[filename] + # self._existing.discard(filename) + + def __getstate__(self): + return self._existing + + def __setstate__(self, state): + self._existing = state + + +def parselinenos(spec, total): + """ + Parse a line number spec (such as "1,2,4-6") and return a list of + wanted line numbers. + """ + items = list() + parts = spec.split(',') + for part in parts: + try: + begend = part.strip().split('-') + if len(begend) > 2: + raise ValueError + if len(begend) == 1: + items.append(int(begend[0])-1) + else: + start = (begend[0] == '') and 0 or int(begend[0])-1 + end = (begend[1] == '') and total or int(begend[1]) + items.extend(xrange(start, end)) + except Exception, err: + raise ValueError('invalid line number spec: %r' % spec) + return items + + +def force_decode(string, encoding): + if isinstance(string, str): + if encoding: + string = string.decode(encoding) + else: + try: + # try decoding with utf-8, should only work for real UTF-8 + string = string.decode('utf-8') + except UnicodeError: + # last resort -- can't fail + string = string.decode('latin1') + return string + + +def movefile(source, dest): + # move a file, removing the destination if it exists + if os.path.exists(dest): + try: + os.unlink(dest) + except OSError: + pass + os.rename(source, dest) + + +def copy_static_entry(source, target, builder, context={}): + if path.isfile(source): + if source.lower().endswith('_t'): + # templated! + fsrc = open(source, 'rb') + fdst = open(target[:-2], 'wb') + fdst.write(builder.templates.render_string(fsrc.read(), context)) + fsrc.close() + fdst.close() + else: + shutil.copyfile(source, target) + elif path.isdir(source): + if filename in builder.config.exclude_dirnames: + return + if path.exists(target): + shutil.rmtree(target) + shutil.copytree(source, target) + + +# monkey-patch Node.traverse to get more speed +# traverse() is called so many times during a build that it saves +# on average 20-25% overall build time! + +def _all_traverse(self): + """Version of Node.traverse() that doesn't need a condition.""" + result = [] + result.append(self) + for child in self.children: + result.extend(child._all_traverse()) + return result + +def _fast_traverse(self, cls): + """Version of Node.traverse() that only supports instance checks.""" + result = [] + if isinstance(self, cls): + result.append(self) + for child in self.children: + result.extend(child._fast_traverse(cls)) + return result + +def _new_traverse(self, condition=None, + include_self=1, descend=1, siblings=0, ascend=0): + if include_self and descend and not siblings and not ascend: + if condition is None: + return self._all_traverse() + elif isinstance(condition, (types.ClassType, type)): + return self._fast_traverse(condition) + return self._old_traverse(condition, include_self, + descend, siblings, ascend) + +import docutils.nodes +docutils.nodes.Node._old_traverse = docutils.nodes.Node.traverse +docutils.nodes.Node._all_traverse = _all_traverse +docutils.nodes.Node._fast_traverse = _fast_traverse +docutils.nodes.Node.traverse = _new_traverse diff --git a/sphinx/util/compat.py b/sphinx/util/compat.py index f9b88a449..c00f9d4ec 100644 --- a/sphinx/util/compat.py +++ b/sphinx/util/compat.py @@ -5,21 +5,20 @@ Stuff for docutils compatibility. - :copyright: 2008 by Georg Brandl. - :license: BSD. + :copyright: Copyright 2007-2009 by the Sphinx team, see AUTHORS. + :license: BSD, see LICENSE for details. """ from docutils import nodes - # function missing in 0.5 SVN def make_admonition(node_class, name, arguments, options, content, lineno, content_offset, block_text, state, state_machine): - if not content: - error = state_machine.reporter.error( - 'The "%s" admonition is empty; content required.' % (name), - nodes.literal_block(block_text, block_text), line=lineno) - return [error] + #if not content: + # error = state_machine.reporter.error( + # 'The "%s" admonition is empty; content required.' % (name), + # nodes.literal_block(block_text, block_text), line=lineno) + # return [error] text = '\n'.join(content) admonition_node = node_class(text) if arguments: @@ -27,11 +26,73 @@ def make_admonition(node_class, name, arguments, options, content, lineno, textnodes, messages = state.inline_text(title_text, lineno) admonition_node += nodes.title(title_text, '', *textnodes) admonition_node += messages - if options.has_key('class'): + if 'class' in options: classes = options['class'] else: classes = ['admonition-' + nodes.make_id(title_text)] admonition_node['classes'] += classes state.nested_parse(content, content_offset, admonition_node) - return admonition_node + return [admonition_node] + +# support the class-style Directive interface even when using docutils 0.4 + +try: + from docutils.parsers.rst import Directive + +except ImportError: + class Directive(object): + """ + Fake Directive class to allow Sphinx directives to be written in + class style. + """ + required_arguments = 0 + optional_arguments = 0 + final_argument_whitespace = False + option_spec = None + has_content = False + + def __init__(self, name, arguments, options, content, lineno, + content_offset, block_text, state, state_machine): + self.name = name + self.arguments = arguments + self.options = options + self.content = content + self.lineno = lineno + self.content_offset = content_offset + self.block_text = block_text + self.state = state + self.state_machine = state_machine + + def run(self): + raise NotImplementedError('Must override run() is subclass.') + + def directive_dwim(obj): + """ + Return something usable with register_directive(), regardless if + class or function. For that, we need to convert classes to a + function for docutils 0.4. + """ + if isinstance(obj, type) and issubclass(obj, Directive): + def _class_directive(name, arguments, options, content, + lineno, content_offset, block_text, + state, state_machine): + return obj(name, arguments, options, content, + lineno, content_offset, block_text, + state, state_machine).run() + _class_directive.options = obj.option_spec + _class_directive.content = obj.has_content + _class_directive.arguments = (obj.required_arguments, + obj.optional_arguments, + obj.final_argument_whitespace) + return _class_directive + return obj + +else: + def directive_dwim(obj): + """ + Return something usable with register_directive(), regardless if + class or function. Nothing to do here, because docutils 0.5 takes + care of converting functions itself. + """ + return obj diff --git a/sphinx/util/console.py b/sphinx/util/console.py index d6ebcb947..083fc6f46 100644 --- a/sphinx/util/console.py +++ b/sphinx/util/console.py @@ -5,8 +5,8 @@ Format colored console output. - :copyright: 2007-2008 by Georg Brandl. - :license: BSD. + :copyright: Copyright 2007-2009 by the Sphinx team, see AUTHORS. + :license: BSD, see LICENSE for details. """ import os @@ -16,25 +16,26 @@ codes = {} def get_terminal_width(): """Borrowed from the py lib.""" try: - import os, termios, fcntl, struct - call = fcntl.ioctl(0, termios.TIOCGWINSZ, "\000"*8) - height, width = struct.unpack("hhhh", call)[:2] + import termios, fcntl, struct + call = fcntl.ioctl(0, termios.TIOCGWINSZ, + struct.pack('hhhh', 0, 0, 0, 0)) + height, width = struct.unpack('hhhh', call)[:2] terminal_width = width except (SystemExit, KeyboardInterrupt): raise except: # FALLBACK - terminal_width = int(os.environ.get('COLUMNS', 80))-1 + terminal_width = int(os.environ.get('COLUMNS', 80)) - 1 return terminal_width _tw = get_terminal_width() -def print_and_backspace(text, func): +def term_width_line(text): if not codes: # if no coloring, don't output fancy backspaces - func(text) + return text + '\n' else: - func(text.ljust(_tw) + _tw * "\b") + return text.ljust(_tw) + '\r' def color_terminal(): if 'COLORTERM' in os.environ: diff --git a/sphinx/util/docstrings.py b/sphinx/util/docstrings.py new file mode 100644 index 000000000..ea03340a0 --- /dev/null +++ b/sphinx/util/docstrings.py @@ -0,0 +1,60 @@ +# -*- coding: utf-8 -*- +""" + sphinx.util.docstrings + ~~~~~~~~~~~~~~~~~~~~~~ + + Utilities for docstring processing. + + :copyright: Copyright 2007-2009 by the Sphinx team, see AUTHORS. + :license: BSD, see LICENSE for details. +""" + +import sys + + +def prepare_docstring(s): + """ + Convert a docstring into lines of parseable reST. Return it as a list of + lines usable for inserting into a docutils ViewList (used as argument + of nested_parse().) An empty line is added to act as a separator between + this docstring and following content. + """ + lines = s.expandtabs().splitlines() + # Find minimum indentation of any non-blank lines after first line. + margin = sys.maxint + for line in lines[1:]: + content = len(line.lstrip()) + if content: + indent = len(line) - content + margin = min(margin, indent) + # Remove indentation. + if lines: + lines[0] = lines[0].lstrip() + if margin < sys.maxint: + for i in range(1, len(lines)): lines[i] = lines[i][margin:] + # Remove any leading blank lines. + while lines and not lines[0]: + lines.pop(0) + # make sure there is an empty line at the end + if lines and lines[-1]: + lines.append('') + return lines + + +def prepare_commentdoc(s): + """ + Extract documentation comment lines (starting with #:) and return them as a + list of lines. Returns an empty list if there is no documentation. + """ + result = [] + lines = [line.strip() for line in s.expandtabs().splitlines()] + for line in lines: + if line.startswith('#:'): + line = line[2:] + # the first space after the comment is ignored + if line and line[0] == ' ': + line = line[1:] + result.append(line) + if result and result[-1]: + result.append('') + return result diff --git a/sphinx/util/jsdump.py b/sphinx/util/jsdump.py index 199c5e09c..8c760b68c 100644 --- a/sphinx/util/jsdump.py +++ b/sphinx/util/jsdump.py @@ -4,10 +4,10 @@ ~~~~~~~~~~~~~~~~~~ This module implements a simple JavaScript serializer. - Uses the basestring encode function from simplejson. + Uses the basestring encode function from simplejson by Bob Ippolito. - :copyright: 2008 by Armin Ronacher, Bob Ippolito, Georg Brandl. - :license: BSD. + :copyright: Copyright 2007-2009 by the Sphinx team, see AUTHORS. + :license: BSD, see LICENSE for details. """ import re @@ -124,7 +124,10 @@ def loads(x): i += 1 elif c in '}]': if key: - raise ValueError("unfinished dict") + if keys[-1] is not nothing: + raise ValueError("unfinished dict") + # empty dict + key = False oldobj = stack.pop() keys.pop() if stack: diff --git a/sphinx/util/png.py b/sphinx/util/png.py new file mode 100644 index 000000000..805a6bdc3 --- /dev/null +++ b/sphinx/util/png.py @@ -0,0 +1,58 @@ +# -*- coding: utf-8 -*- +""" + sphinx.util.png + ~~~~~~~~~~~~~~~ + + PNG image manipulation helpers. + + :copyright: Copyright 2007-2009 by the Sphinx team, see AUTHORS. + :license: BSD, see LICENSE for details. +""" + +import struct +import binascii + +LEN_IEND = 12 +LEN_DEPTH = 22 + +DEPTH_CHUNK_LEN = struct.pack('!i', 10) +DEPTH_CHUNK_START = 'tEXtDepth\x00' +IEND_CHUNK = '\x00\x00\x00\x00IEND\xAE\x42\x60\x82' + + +def read_png_depth(filename): + """ + Read the special tEXt chunk indicating the depth from a PNG file. + """ + result = None + f = open(filename, 'rb') + try: + f.seek(- (LEN_IEND + LEN_DEPTH), 2) + depthchunk = f.read(LEN_DEPTH) + if not depthchunk.startswith(DEPTH_CHUNK_LEN + DEPTH_CHUNK_START): + # either not a PNG file or not containing the depth chunk + return None + result = struct.unpack('!i', depthchunk[14:18])[0] + finally: + f.close() + return result + + +def write_png_depth(filename, depth): + """ + Write the special tEXt chunk indicating the depth to a PNG file. + The chunk is placed immediately before the special IEND chunk. + """ + data = struct.pack('!i', depth) + f = open(filename, 'r+b') + try: + # seek to the beginning of the IEND chunk + f.seek(-LEN_IEND, 2) + # overwrite it with the depth chunk + f.write(DEPTH_CHUNK_LEN + DEPTH_CHUNK_START + data) + # calculate the checksum over chunk name and data + f.write(struct.pack('!i', binascii.crc32(DEPTH_CHUNK_START + data))) + # replace the IEND chunk + f.write(IEND_CHUNK) + finally: + f.close() diff --git a/sphinx/util/smartypants.py b/sphinx/util/smartypants.py index 42f20f366..75888ea4d 100644 --- a/sphinx/util/smartypants.py +++ b/sphinx/util/smartypants.py @@ -162,7 +162,8 @@ def educateQuotes(s): """ # Special case if the very first character is a quote - # followed by punctuation at a non-word-break. Close the quotes by brute force: + # followed by punctuation at a non-word-break. Close the quotes + # by brute force: s = single_quote_start_re.sub("’", s) s = double_quote_start_re.sub("”", s) @@ -200,7 +201,8 @@ def educateQuotesLatex(s, dquotes=("``", "''")): """ # Special case if the very first character is a quote - # followed by punctuation at a non-word-break. Close the quotes by brute force: + # followed by punctuation at a non-word-break. Close the quotes + # by brute force: s = single_quote_start_re.sub("\x04", s) s = double_quote_start_re.sub("\x02", s) @@ -300,4 +302,5 @@ __author__ = "Chad Miller " __version__ = "1.5_1.5: Sat, 13 Aug 2005 15:50:24 -0400" __url__ = "http://wiki.chad.org/SmartyPantsPy" __description__ = \ - "Smart-quotes, smart-ellipses, and smart-dashes for weblog entries in pyblosxom" + "Smart-quotes, smart-ellipses, and smart-dashes for weblog entries" \ + " in pyblosxom" diff --git a/sphinx/util/stemmer.py b/sphinx/util/stemmer.py index a5e5cbbc5..10ce90656 100644 --- a/sphinx/util/stemmer.py +++ b/sphinx/util/stemmer.py @@ -24,7 +24,7 @@ Release 1: January 2001 - :copyright: 2001 by Vivake Gupta . + :copyright: Copyright 2001 by Vivake Gupta . :license: Public Domain ("can be used free of charge for any purpose"). """ @@ -111,14 +111,16 @@ class PorterStemmer(object): return self.cons(j) def cvc(self, i): - """cvc(i) is TRUE <=> i-2,i-1,i has the form consonant - vowel - consonant + """cvc(i) is TRUE <=> i-2,i-1,i has the form + consonant - vowel - consonant and also if the second c is not w,x or y. this is used when trying to restore an e at the end of a short e.g. cav(e), lov(e), hop(e), crim(e), but snow, box, tray. """ - if i < (self.k0 + 2) or not self.cons(i) or self.cons(i-1) or not self.cons(i-2): + if i < (self.k0 + 2) or not self.cons(i) or self.cons(i-1) \ + or not self.cons(i-2): return 0 ch = self.b[i] if ch == 'w' or ch == 'x' or ch == 'y': @@ -138,7 +140,8 @@ class PorterStemmer(object): return 1 def setto(self, s): - """setto(s) sets (j+1),...k to the characters in the string s, readjusting k.""" + """setto(s) sets (j+1),...k to the characters in the string s, + readjusting k.""" length = len(s) self.b = self.b[:self.j+1] + s + self.b[self.j+length+1:] self.k = self.j + length @@ -193,7 +196,8 @@ class PorterStemmer(object): self.setto("e") def step1c(self): - """step1c() turns terminal y to i when there is another vowel in the stem.""" + """step1c() turns terminal y to i when there is another vowel in + the stem.""" if (self.ends("y") and self.vowelinstem()): self.b = self.b[:self.k] + 'i' + self.b[self.k+1:] @@ -236,7 +240,8 @@ class PorterStemmer(object): # To match the published algorithm, delete this phrase def step3(self): - """step3() dels with -ic-, -full, -ness etc. similar strategy to step2.""" + """step3() dels with -ic-, -full, -ness etc. similar strategy + to step2.""" if self.b[self.k] == 'e': if self.ends("icate"): self.r("ic") elif self.ends("ative"): self.r("") diff --git a/sphinx/util/tags.py b/sphinx/util/tags.py new file mode 100644 index 000000000..c08e5e5a0 --- /dev/null +++ b/sphinx/util/tags.py @@ -0,0 +1,90 @@ +# -*- coding: utf-8 -*- +""" + sphinx.util.tags + ~~~~~~~~~~~~~~~~ + + :copyright: Copyright 2007-2009 by the Sphinx team, see AUTHORS. + :license: BSD, see LICENSE for details. +""" + +import warnings +# jinja2.sandbox imports the sets module on purpose +warnings.filterwarnings('ignore', 'the sets module', DeprecationWarning, + module='jinja2.sandbox') + +# (ab)use the Jinja parser for parsing our boolean expressions +from jinja2 import nodes +from jinja2.parser import Parser +from jinja2.environment import Environment + +env = Environment() + + +class BooleanParser(Parser): + """ + Only allow condition exprs and/or/not operations. + """ + + def parse_compare(self): + token = self.stream.current + if token.type == 'name': + if token.value in ('true', 'false', 'True', 'False'): + node = nodes.Const(token.value in ('true', 'True'), + lineno=token.lineno) + elif token.value in ('none', 'None'): + node = nodes.Const(None, lineno=token.lineno) + else: + node = nodes.Name(token.value, 'load', lineno=token.lineno) + self.stream.next() + elif token.type == 'lparen': + self.stream.next() + node = self.parse_expression() + self.stream.expect('rparen') + else: + self.fail("unexpected token '%s'" % (token,), token.lineno) + return node + + +class Tags(object): + def __init__(self, tags=None): + self.tags = dict.fromkeys(tags or [], True) + + def has(self, tag): + return tag in self.tags + + __contains__ = has + + def __iter__(self): + return iter(self.tags) + + def add(self, tag): + self.tags[tag] = True + + def remove(self, tag): + self.tags.pop(tag, None) + + def eval_condition(self, condition): + # exceptions are handled by the caller + parser = BooleanParser(env, condition, state='variable') + expr = parser.parse_expression() + if not parser.stream.eos: + raise ValueError('chunk after expression') + + def eval_node(node): + if isinstance(node, nodes.CondExpr): + if eval_node(node.test): + return eval_node(node.expr1) + else: + return eval_node(node.expr2) + elif isinstance(node, nodes.And): + return eval_node(node.left) and eval_node(node.right) + elif isinstance(node, nodes.Or): + return eval_node(node.left) or eval_node(node.right) + elif isinstance(node, nodes.Not): + return not eval_node(node.node) + elif isinstance(node, nodes.Name): + return self.tags.get(node.name, False) + else: + raise ValueError('invalid node, check parsing') + + return eval_node(expr) diff --git a/sphinx/util/texescape.py b/sphinx/util/texescape.py index 8412a3a3f..f495243cb 100644 --- a/sphinx/util/texescape.py +++ b/sphinx/util/texescape.py @@ -5,8 +5,8 @@ TeX escaping helper. - :copyright: 2008 by Georg Brandl. - :license: BSD. + :copyright: Copyright 2007-2009 by the Sphinx team, see AUTHORS. + :license: BSD, see LICENSE for details. """ tex_replacements = [ @@ -40,7 +40,8 @@ tex_replacements = [ (u'─', ur'-'), (u'⎽', ur'\_'), (u'╲', ur'\textbackslash{}'), - (u'│', ur'|'), + (u'|', ur'\textbar{}'), + (u'│', ur'\textbar{}'), (u'ℯ', ur'e'), (u'ⅈ', ur'i'), (u'₁', ur'1'), diff --git a/sphinx/writers/__init__.py b/sphinx/writers/__init__.py new file mode 100644 index 000000000..7bb8cad91 --- /dev/null +++ b/sphinx/writers/__init__.py @@ -0,0 +1,10 @@ +# -*- coding: utf-8 -*- +""" + sphinx.writers + ~~~~~~~~~~~~~~ + + Custom docutils writers. + + :copyright: Copyright 2007-2009 by the Sphinx team, see AUTHORS. + :license: BSD, see LICENSE for details. +""" diff --git a/sphinx/htmlwriter.py b/sphinx/writers/html.py similarity index 79% rename from sphinx/htmlwriter.py rename to sphinx/writers/html.py index dd56b4097..f600e8bd2 100644 --- a/sphinx/htmlwriter.py +++ b/sphinx/writers/html.py @@ -1,12 +1,12 @@ # -*- coding: utf-8 -*- """ - sphinx.htmlwriter - ~~~~~~~~~~~~~~~~~ + sphinx.writers.html + ~~~~~~~~~~~~~~~~~~~ docutils writers handling Sphinx' custom nodes. - :copyright: 2007-2008 by Georg Brandl. - :license: BSD. + :copyright: Copyright 2007-2009 by the Sphinx team, see AUTHORS. + :license: BSD, see LICENSE for details. """ import sys @@ -17,7 +17,6 @@ from docutils import nodes from docutils.writers.html4css1 import Writer, HTMLTranslator as BaseTranslator from sphinx.locale import admonitionlabels, versionlabels -from sphinx.highlighting import PygmentsBridge from sphinx.util.smartypants import sphinx_smarty_pants try: @@ -25,6 +24,7 @@ try: except ImportError: Image = None + class HTMLWriter(Writer): def __init__(self, builder): Writer.__init__(self) @@ -52,12 +52,13 @@ class HTMLTranslator(BaseTranslator): def __init__(self, builder, *args, **kwds): BaseTranslator.__init__(self, *args, **kwds) - self.highlighter = PygmentsBridge('html', builder.config.pygments_style) + self.highlighter = builder.highlighter self.no_smarty = 0 self.builder = builder self.highlightlang = builder.config.highlight_language self.highlightlinenothreshold = sys.maxint self.protect_literal_text = 0 + self.add_permalinks = builder.config.html_add_permalinks def visit_desc(self, node): self.body.append(self.starttag(node, 'dl', CLASS=node['desctype'])) @@ -68,13 +69,13 @@ class HTMLTranslator(BaseTranslator): # the id is set automatically self.body.append(self.starttag(node, 'dt')) # anchor for per-desc interactive data - if node.parent['desctype'] != 'describe' and node['ids'] and node['first']: + if node.parent['desctype'] != 'describe' \ + and node['ids'] and node['first']: self.body.append('' % node['ids'][0]) - if node.parent['desctype'] in ('class', 'exception'): - self.body.append('%s ' % node.parent['desctype']) def depart_desc_signature(self, node): - if node['ids'] and self.builder.add_definition_links: - self.body.append(u'\u00B6' % _('Permalink to this definition')) self.body.append('\n') @@ -89,6 +90,11 @@ class HTMLTranslator(BaseTranslator): def depart_desc_type(self, node): pass + def visit_desc_returns(self, node): + self.body.append(' → ') + def depart_desc_returns(self, node): + pass + def visit_desc_name(self, node): self.body.append(self.starttag(node, 'tt', '', CLASS='descname')) def depart_desc_name(self, node): @@ -152,6 +158,8 @@ class HTMLTranslator(BaseTranslator): return self.body[-1] = ' tag BaseTranslator.visit_title(self, node, move_ids=0) + self.add_secnumber(node) + else: + def visit_title(self, node): + BaseTranslator.visit_title(self, node) + self.add_secnumber(node) # overwritten def visit_literal_block(self, node): @@ -187,18 +211,18 @@ class HTMLTranslator(BaseTranslator): # most probably a parsed-literal block -- don't highlight return BaseTranslator.visit_literal_block(self, node) lang = self.highlightlang - linenos = node.rawsource.count('\n') >= self.highlightlinenothreshold - 1 + linenos = node.rawsource.count('\n') >= \ + self.highlightlinenothreshold - 1 if node.has_key('language'): # code-block directives lang = node['language'] if node.has_key('linenos'): linenos = node['linenos'] - highlighted = self.highlighter.highlight_block(node.rawsource, lang, linenos) - starttag = self.starttag(node, 'div', suffix='') - if starttag != '
    ': - self.body.append(starttag + highlighted + '
    \n') - else: - self.body.append(highlighted) + highlighted = self.highlighter.highlight_block(node.rawsource, + lang, linenos) + starttag = self.starttag(node, 'div', suffix='', + CLASS='highlight-%s' % lang) + self.body.append(starttag + highlighted + '\n') raise nodes.SkipNode def visit_doctest_block(self, node): @@ -209,7 +233,8 @@ class HTMLTranslator(BaseTranslator): if len(node.children) == 1 and \ node.children[0] in ('None', 'True', 'False'): node['classes'].append('xref') - self.body.append(self.starttag(node, 'tt', '', CLASS='docutils literal')) + self.body.append(self.starttag(node, 'tt', '', + CLASS='docutils literal')) self.protect_literal_text += 1 def depart_literal(self, node): self.protect_literal_text -= 1 @@ -241,7 +266,8 @@ class HTMLTranslator(BaseTranslator): pass def visit_centered(self, node): - self.body.append(self.starttag(node, 'p', CLASS="centered") + '') + self.body.append(self.starttag(node, 'p', CLASS="centered") + + '') def depart_centered(self, node): self.body.append('

    ') @@ -256,6 +282,16 @@ class HTMLTranslator(BaseTranslator): def depart_highlightlang(self, node): pass + def visit_download_reference(self, node): + if node.hasattr('filename'): + self.body.append('    ' % posixpath.join( + self.builder.dlpath, node['filename'])) + self.context.append('') + else: + self.context.append('') + def depart_download_reference(self, node): + self.body.append(self.context.pop()) + # overwritten def visit_image(self, node): olduri = node['uri'] @@ -264,15 +300,33 @@ class HTMLTranslator(BaseTranslator): node['uri'] = posixpath.join(self.builder.imgpath, self.builder.images[olduri]) + if node['uri'].lower().endswith('svg') or \ + node['uri'].lower().endswith('svgz'): + atts = {'data': node['uri'], 'type': 'image/svg+xml'} + if 'width' in node: + atts['width'] = node['width'] + if 'height' in node: + atts['height'] = node['height'] + if 'align' in node: + self.body.append('
    ' % + (node['align'], node['align'])) + self.context.append('
    \n') + else: + self.context.append('') + embatts = atts.copy() + embatts['src'] = embatts.pop('data') + self.body.append(self.starttag(node, 'object', '', **atts)) + self.body.append(self.emptytag(node, 'embed', '', **embatts)) + self.body.append('\n') + return + if node.has_key('scale'): if Image and not (node.has_key('width') and node.has_key('height')): try: - im = Image.open(os.path.join(self.builder.srcdir, - olduri)) + im = Image.open(os.path.join(self.builder.srcdir, olduri)) except (IOError, # Source image can't be found or opened UnicodeError): # PIL doesn't like Unicode paths. - print olduri pass else: if not node.has_key('width'): @@ -308,6 +362,16 @@ class HTMLTranslator(BaseTranslator): def depart_module(self, node): pass + def visit_hlist(self, node): + self.body.append('
     
    {{ fname }}
    {% if collapse -%} + class="toggler" style="display: none" alt="-" /> {%- endif %} {% if indent %}   {% endif %} {% if fname %}{% endif -%} - {{ modname|e }} + {{ stripped|e }}{{ modname|e }} {%- if fname %}{% endif %} - {%- if pform[0] %} ({{ pform|join(', ') }}){% endif -%} + {%- if pform and pform[0] %} ({{ pform|join(', ') }}){% endif -%} {% if dep %}{{ _('Deprecated')}}:{% endif %} {{ synops|e }}
    ') + def depart_hlist(self, node): + self.body.append('
    \n') + + def visit_hlistcol(self, node): + self.body.append('') + def depart_hlistcol(self, node): + self.body.append('') + def bulk_text_processor(self, text): return text @@ -389,9 +453,17 @@ class HTMLTranslator(BaseTranslator): def depart_literal_emphasis(self, node): return self.depart_emphasis(node) + def visit_abbreviation(self, node): + attrs = {} + if node.hasattr('explanation'): + attrs['title'] = node['explanation'] + self.body.append(self.starttag(node, 'abbr', **attrs)) + def depart_abbreviation(self, node): + self.body.append('') + def depart_title(self, node): close_tag = self.context[-1] - if self.builder.add_header_links and \ + if self.add_permalinks and self.builder.add_permalinks and \ (close_tag.startswith(' 0: self.body.append(' & ') self.table.col += 1 @@ -605,14 +678,17 @@ class LaTeXTranslator(nodes.NodeVisitor): # this is a list in the source, but should be rendered as a # comma-separated list here self.body.append('\n\n') - self.body.append(', '.join(n.astext() for n in node.children[0].children) + '.') + self.body.append(', '.join(n.astext() + for n in node.children[0].children) + '.') self.body.append('\n\n') raise nodes.SkipNode def visit_bullet_list(self, node): - self.body.append('\\begin{itemize}\n' ) + if not self.compact_list: + self.body.append('\\begin{itemize}\n' ) def depart_bullet_list(self, node): - self.body.append('\\end{itemize}\n' ) + if not self.compact_list: + self.body.append('\\end{itemize}\n' ) def visit_enumerated_list(self, node): self.body.append('\\begin{enumerate}\n' ) @@ -681,11 +757,29 @@ class LaTeXTranslator(nodes.NodeVisitor): def depart_centered(self, node): self.body.append('\n\\end{centering}') + def visit_hlist(self, node): + # for now, we don't support a more compact list format + # don't add individual itemize environments, but one for all columns + self.compact_list += 1 + self.body.append('\\begin{itemize}\\setlength{\\itemsep}{0pt}' + '\\setlength{\\parskip}{0pt}\n') + def depart_hlist(self, node): + self.compact_list -= 1 + self.body.append('\\end{itemize}\n') + + def visit_hlistcol(self, node): + pass + def depart_hlistcol(self, node): + pass + def visit_module(self, node): modname = node['modname'] - self.body.append('\n\\declaremodule[%s]{}{%s}' % (modname.replace('_', ''), - self.encode(modname))) - self.body.append('\n\\modulesynopsis{%s}' % self.encode(node['synopsis'])) + self.body.append('\n\\hypertarget{module-%s}{}' % + (modname.replace(' ',''))) + self.body.append('\n\\declaremodule[%s]{}{%s}' % ( + modname.replace('_', ''), self.encode(modname))) + self.body.append('\n\\modulesynopsis{%s}' % + self.encode(node['synopsis'])) if node.has_key('platform'): self.body.append('\\platform{%s}' % self.encode(node['platform'])) def depart_module(self, node): @@ -698,9 +792,9 @@ class LaTeXTranslator(nodes.NodeVisitor): return width_str res = width_str amount, unit = match.groups()[:2] - if unit == "px": - # LaTeX does not know pixels but points - res = "%spt" % amount + if not unit or unit == "px": + # pixels: let LaTeX alone + return None elif unit == "%": res = "%.3f\\linewidth" % (float(amount) / 100.0) return res @@ -717,11 +811,13 @@ class LaTeXTranslator(nodes.NodeVisitor): pre.append('\\scalebox{%f}{' % (attrs['scale'] / 100.0,)) post.append('}') if attrs.has_key('width'): - include_graphics_options.append('width=%s' % ( - self.latex_image_length(attrs['width']), )) + w = self.latex_image_length(attrs['width']) + if w: + include_graphics_options.append('width=%s' % w) if attrs.has_key('height'): - include_graphics_options.append('height=%s' % ( - self.latex_image_length(attrs['height']), )) + h = self.latex_image_length(attrs['height']) + if h: + include_graphics_options.append('height=%s' % h) if attrs.has_key('align'): align_prepost = { # By default latex aligns the top of an image. @@ -763,17 +859,23 @@ class LaTeXTranslator(nodes.NodeVisitor): pass def visit_figure(self, node): - if (not node.attributes.has_key('align') or - node.attributes['align'] == 'center'): - # centering does not add vertical space like center. - align = '\n\\centering' - align_end = '' + if node.has_key('width') and node.get('align', '') in ('left', 'right'): + self.body.append('\\begin{wrapfigure}{%s}{%s}\n\\centering' % + (node['align'] == 'right' and 'r' or 'l', + node['width'])) + self.context.append('\\end{wrapfigure}\n') else: - # TODO non vertical space for other alignments. - align = '\\begin{flush%s}' % node.attributes['align'] - align_end = '\\end{flush%s}' % node.attributes['align'] - self.body.append('\\begin{figure}[htbp]%s\n' % align) - self.context.append('%s\\end{figure}\n' % align_end) + if (not node.attributes.has_key('align') or + node.attributes['align'] == 'center'): + # centering does not add vertical space like center. + align = '\n\\centering' + align_end = '' + else: + # TODO non vertical space for other alignments. + align = '\\begin{flush%s}' % node.attributes['align'] + align_end = '\\end{flush%s}' % node.attributes['align'] + self.body.append('\\begin{figure}[htbp]%s\n' % align) + self.context.append('%s\\end{figure}\n' % align_end) def depart_figure(self, node): self.body.append(self.context.pop()) @@ -788,9 +890,9 @@ class LaTeXTranslator(nodes.NodeVisitor): self.body.append('}') def visit_admonition(self, node): - self.body.append('\n\\begin{quote}') + self.body.append('\n\\begin{notice}{note}') def depart_admonition(self, node): - self.body.append('\\end{quote}\n') + self.body.append('\\end{notice}\n') def _make_visit_admonition(name): def visit_admonition(self, node): @@ -860,13 +962,22 @@ class LaTeXTranslator(nodes.NodeVisitor): entries = node['entries'] for type, string, tid, _ in entries: if type == 'single': - self.body.append(r'\index{%s}' % scre.sub('!', self.encode(string))) + self.body.append(r'\index{%s}' % + scre.sub('!', self.encode(string))) elif type == 'pair': - parts = tuple(self.encode(x.strip()) for x in string.split(';', 1)) - self.body.append(r'\indexii{%s}{%s}' % parts) + parts = tuple(self.encode(x.strip()) + for x in string.split(';', 1)) + try: + self.body.append(r'\indexii{%s}{%s}' % parts) + except TypeError: + self.builder.warn('invalid pair index entry %r' % string) elif type == 'triple': - parts = tuple(self.encode(x.strip()) for x in string.split(';', 2)) - self.body.append(r'\indexiii{%s}{%s}{%s}' % parts) + parts = tuple(self.encode(x.strip()) + for x in string.split(';', 2)) + try: + self.body.append(r'\indexiii{%s}{%s}{%s}' % parts) + except TypeError: + self.builder.warn('invalid triple index entry %r' % string) else: self.builder.warn('unknown index entry type %s found' % type) raise nodes.SkipNode @@ -887,6 +998,12 @@ class LaTeXTranslator(nodes.NodeVisitor): elif uri.startswith('#'): self.body.append('\\hyperlink{%s}{' % uri[1:]) self.context.append('}') + elif uri.startswith('%'): + hashindex = uri.find('#') + targetname = (hashindex == -1) and '--doc-' + uri[1:] \ + or uri[hashindex+1:] + self.body.append('\\hyperlink{%s}{' % targetname) + self.context.append('}') elif uri.startswith('@token'): if self.in_production_list: self.body.append('\\token{') @@ -894,11 +1011,19 @@ class LaTeXTranslator(nodes.NodeVisitor): self.body.append('\\grammartoken{') self.context.append('}') else: - self.builder.warn('unusable reference target found: %s' % uri) + self.builder.warn( + 'unusable reference target found: %s' % uri, + '%s:%s' % (self.builder.env.doc2path(self.curfilestack[-1]), + node.line or '')) self.context.append('') def depart_reference(self, node): self.body.append(self.context.pop()) + def visit_download_reference(self, node): + pass + def depart_download_reference(self, node): + pass + def visit_pending_xref(self, node): pass def depart_pending_xref(self, node): @@ -911,14 +1036,28 @@ class LaTeXTranslator(nodes.NodeVisitor): def visit_literal_emphasis(self, node): self.body.append(r'\emph{\texttt{') + self.no_contractions += 1 def depart_literal_emphasis(self, node): self.body.append('}}') + self.no_contractions -= 1 def visit_strong(self, node): self.body.append(r'\textbf{') def depart_strong(self, node): self.body.append('}') + def visit_abbreviation(self, node): + abbr = node.astext() + self.body.append(r'\textsc{') + # spell out the explanation once + if node.hasattr('explanation') and abbr not in self.handled_abbrs: + self.context.append('} (%s)' % self.encode(node['explanation'])) + self.handled_abbrs.add(abbr) + else: + self.context.append('}') + def depart_abbreviation(self, node): + self.body.append(self.context.pop()) + def visit_title_reference(self, node): self.body.append(r'\emph{') def depart_title_reference(self, node): @@ -940,7 +1079,9 @@ class LaTeXTranslator(nodes.NodeVisitor): raise nodes.SkipNode def visit_literal(self, node): + self.no_contractions += 1 content = self.encode(node.astext().strip()) + self.no_contractions -= 1 if self.in_title: self.body.append(r'\texttt{%s}' % content) elif node.has_key('role') and node['role'] == 'samp': @@ -952,14 +1093,19 @@ class LaTeXTranslator(nodes.NodeVisitor): def visit_footnote_reference(self, node): num = node.astext().strip() try: - fn = self.footnotestack[-1][num] + footnode, used = self.footnotestack[-1][num] except (KeyError, IndexError): raise nodes.SkipNode - self.body.append('\\footnote{') - fn.walkabout(self) + # if a footnote has been inserted once, it shouldn't be repeated + # by the next reference + if used: + self.body.append('\\footnotemark[%s]' % num) + else: + footnode.walkabout(self) + self.footnotestack[-1][num][1] = True raise nodes.SkipChildren def depart_footnote_reference(self, node): - self.body.append('}') + pass def visit_literal_block(self, node): self.verbatim = '' @@ -1010,7 +1156,10 @@ class LaTeXTranslator(nodes.NodeVisitor): # no output in this line -- add a nonbreaking space, else the # \\ command will give an error self.body.append('~') - self.body.append('\\\\\n') + if self.table is not None: + self.body.append('\\newline\n') + else: + self.body.append('\\\\\n') def visit_block_quote(self, node): # If the block quote contains a single object and that object @@ -1070,7 +1219,7 @@ class LaTeXTranslator(nodes.NodeVisitor): def visit_option_string(self, node): ostring = node.astext() - self.body.append(self.encode(ostring.replace('--', u'--'))) + self.body.append(self.encode(ostring.replace('--', u'-{-}'))) raise nodes.SkipNode def visit_description(self, node): @@ -1122,6 +1271,8 @@ class LaTeXTranslator(nodes.NodeVisitor): # Insert a blank before the newline, to avoid # ! LaTeX Error: There's no line here to end. text = text.replace(u'\n', u'~\\\\\n').replace(u' ', u'~') + if self.no_contractions: + text = text.replace('--', u'-{-}') return text def visit_Text(self, node): diff --git a/sphinx/textwriter.py b/sphinx/writers/text.py similarity index 95% rename from sphinx/textwriter.py rename to sphinx/writers/text.py index 378514c7e..b3b565c51 100644 --- a/sphinx/textwriter.py +++ b/sphinx/writers/text.py @@ -1,12 +1,12 @@ # -*- coding: utf-8 -*- """ - sphinx.textwriter - ~~~~~~~~~~~~~~~~~ + sphinx.writers.text + ~~~~~~~~~~~~~~~~~~~ Custom docutils writer for plain text. - :copyright: 2008 by Georg Brandl. - :license: BSD. + :copyright: Copyright 2007-2009 by the Sphinx team, see AUTHORS. + :license: BSD, see LICENSE for details. """ import re @@ -126,11 +126,6 @@ class TextTranslator(nodes.NodeVisitor): self.add_text(' ]-') self.end_state() - def visit_sidebar(self, node): - pass - def depart_sidebar(self, node): - pass - def visit_compound(self, node): pass def depart_compound(self, node): @@ -200,6 +195,11 @@ class TextTranslator(nodes.NodeVisitor): def depart_desc_type(self, node): pass + def visit_desc_returns(self, node): + self.add_text(' -> ') + def depart_desc_returns(self, node): + pass + def visit_desc_parameterlist(self, node): self.add_text('(') self.first_param = 1 @@ -419,7 +419,8 @@ class TextTranslator(nodes.NodeVisitor): def visit_acks(self, node): self.new_state(0) - self.add_text(', '.join(n.astext() for n in node.children[0].children) + '.') + self.add_text(', '.join(n.astext() for n in node.children[0].children) + + '.') self.end_state() raise nodes.SkipNode @@ -516,6 +517,16 @@ class TextTranslator(nodes.NodeVisitor): def depart_centered(self, node): pass + def visit_hlist(self, node): + pass + def depart_hlist(self, node): + pass + + def visit_hlistcol(self, node): + pass + def depart_hlistcol(self, node): + pass + def visit_admonition(self, node): self.new_state(0) def depart_admonition(self, node): @@ -614,6 +625,11 @@ class TextTranslator(nodes.NodeVisitor): def depart_reference(self, node): pass + def visit_download_reference(self, node): + pass + def depart_download_reference(self, node): + pass + def visit_emphasis(self, node): self.add_text('*') def depart_emphasis(self, node): @@ -629,6 +645,12 @@ class TextTranslator(nodes.NodeVisitor): def depart_strong(self, node): self.add_text('**') + def visit_abbreviation(self, node): + self.add_text('') + def depart_abbreviation(self, node): + if node.hasattr('explanation'): + self.add_text(' (%s)' % node['explanation']) + def visit_title_reference(self, node): self.add_text('*') def depart_title_reference(self, node): diff --git a/tests/coverage.py b/tests/coverage.py new file mode 100755 index 000000000..148e573c6 --- /dev/null +++ b/tests/coverage.py @@ -0,0 +1,1163 @@ +#!/usr/bin/python +# +# Perforce Defect Tracking Integration Project +# +# +# COVERAGE.PY -- COVERAGE TESTING +# +# Gareth Rees, Ravenbrook Limited, 2001-12-04 +# Ned Batchelder, 2004-12-12 +# http://nedbatchelder.com/code/modules/coverage.html +# +# +# 1. INTRODUCTION +# +# This module provides coverage testing for Python code. +# +# The intended readership is all Python developers. +# +# This document is not confidential. +# +# See [GDR 2001-12-04a] for the command-line interface, programmatic +# interface and limitations. See [GDR 2001-12-04b] for requirements and +# design. + +r"""Usage: + +coverage.py -x [-p] MODULE.py [ARG1 ARG2 ...] + Execute module, passing the given command-line arguments, collecting + coverage data. With the -p option, write to a temporary file containing + the machine name and process ID. + +coverage.py -e + Erase collected coverage data. + +coverage.py -c + Collect data from multiple coverage files (as created by -p option above) + and store it into a single file representing the union of the coverage. + +coverage.py -r [-m] [-o dir1,dir2,...] FILE1 FILE2 ... + Report on the statement coverage for the given files. With the -m + option, show line numbers of the statements that weren't executed. + +coverage.py -a [-d dir] [-o dir1,dir2,...] FILE1 FILE2 ... + Make annotated copies of the given files, marking statements that + are executed with > and statements that are missed with !. With + the -d option, make the copies in that directory. Without the -d + option, make each copy in the same directory as the original. + +-o dir,dir2,... + Omit reporting or annotating files when their filename path starts with + a directory listed in the omit list. + e.g. python coverage.py -i -r -o c:\python23,lib\enthought\traits + +Coverage data is saved in the file .coverage by default. Set the +COVERAGE_FILE environment variable to save it somewhere else.""" + +__version__ = "2.85.20080914" # see detailed history at the end of this file. + +import compiler +import compiler.visitor +import glob +import os +import re +import string +import symbol +import sys +import threading +import token +import types +import zipimport +from socket import gethostname + +# Python version compatibility +try: + strclass = basestring # new to 2.3 +except: + strclass = str + +# 2. IMPLEMENTATION +# +# This uses the "singleton" pattern. +# +# The word "morf" means a module object (from which the source file can +# be deduced by suitable manipulation of the __file__ attribute) or a +# filename. +# +# When we generate a coverage report we have to canonicalize every +# filename in the coverage dictionary just in case it refers to the +# module we are reporting on. It seems a shame to throw away this +# information so the data in the coverage dictionary is transferred to +# the 'cexecuted' dictionary under the canonical filenames. +# +# The coverage dictionary is called "c" and the trace function "t". The +# reason for these short names is that Python looks up variables by name +# at runtime and so execution time depends on the length of variables! +# In the bottleneck of this application it's appropriate to abbreviate +# names to increase speed. + +class StatementFindingAstVisitor(compiler.visitor.ASTVisitor): + """ A visitor for a parsed Abstract Syntax Tree which finds executable + statements. + """ + def __init__(self, statements, excluded, suite_spots): + compiler.visitor.ASTVisitor.__init__(self) + self.statements = statements + self.excluded = excluded + self.suite_spots = suite_spots + self.excluding_suite = 0 + + def doRecursive(self, node): + for n in node.getChildNodes(): + self.dispatch(n) + + visitStmt = visitModule = doRecursive + + def doCode(self, node): + if hasattr(node, 'decorators') and node.decorators: + self.dispatch(node.decorators) + self.recordAndDispatch(node.code) + else: + self.doSuite(node, node.code) + + visitFunction = visitClass = doCode + + def getFirstLine(self, node): + # Find the first line in the tree node. + lineno = node.lineno + for n in node.getChildNodes(): + f = self.getFirstLine(n) + if lineno and f: + lineno = min(lineno, f) + else: + lineno = lineno or f + return lineno + + def getLastLine(self, node): + # Find the first line in the tree node. + lineno = node.lineno + for n in node.getChildNodes(): + lineno = max(lineno, self.getLastLine(n)) + return lineno + + def doStatement(self, node): + self.recordLine(self.getFirstLine(node)) + + visitAssert = visitAssign = visitAssTuple = visitPrint = \ + visitPrintnl = visitRaise = visitSubscript = visitDecorators = \ + doStatement + + def visitPass(self, node): + # Pass statements have weird interactions with docstrings. If this + # pass statement is part of one of those pairs, claim that the statement + # is on the later of the two lines. + l = node.lineno + if l: + lines = self.suite_spots.get(l, [l,l]) + self.statements[lines[1]] = 1 + + def visitDiscard(self, node): + # Discard nodes are statements that execute an expression, but then + # discard the results. This includes function calls, so we can't + # ignore them all. But if the expression is a constant, the statement + # won't be "executed", so don't count it now. + if node.expr.__class__.__name__ != 'Const': + self.doStatement(node) + + def recordNodeLine(self, node): + # Stmt nodes often have None, but shouldn't claim the first line of + # their children (because the first child might be an ignorable line + # like "global a"). + if node.__class__.__name__ != 'Stmt': + return self.recordLine(self.getFirstLine(node)) + else: + return 0 + + def recordLine(self, lineno): + # Returns a bool, whether the line is included or excluded. + if lineno: + # Multi-line tests introducing suites have to get charged to their + # keyword. + if lineno in self.suite_spots: + lineno = self.suite_spots[lineno][0] + # If we're inside an excluded suite, record that this line was + # excluded. + if self.excluding_suite: + self.excluded[lineno] = 1 + return 0 + # If this line is excluded, or suite_spots maps this line to + # another line that is exlcuded, then we're excluded. + elif self.excluded.has_key(lineno) or \ + self.suite_spots.has_key(lineno) and \ + self.excluded.has_key(self.suite_spots[lineno][1]): + return 0 + # Otherwise, this is an executable line. + else: + self.statements[lineno] = 1 + return 1 + return 0 + + default = recordNodeLine + + def recordAndDispatch(self, node): + self.recordNodeLine(node) + self.dispatch(node) + + def doSuite(self, intro, body, exclude=0): + exsuite = self.excluding_suite + if exclude or (intro and not self.recordNodeLine(intro)): + self.excluding_suite = 1 + self.recordAndDispatch(body) + self.excluding_suite = exsuite + + def doPlainWordSuite(self, prevsuite, suite): + # Finding the exclude lines for else's is tricky, because they aren't + # present in the compiler parse tree. Look at the previous suite, + # and find its last line. If any line between there and the else's + # first line are excluded, then we exclude the else. + lastprev = self.getLastLine(prevsuite) + firstelse = self.getFirstLine(suite) + for l in range(lastprev+1, firstelse): + if self.suite_spots.has_key(l): + self.doSuite(None, suite, exclude=self.excluded.has_key(l)) + break + else: + self.doSuite(None, suite) + + def doElse(self, prevsuite, node): + if node.else_: + self.doPlainWordSuite(prevsuite, node.else_) + + def visitFor(self, node): + self.doSuite(node, node.body) + self.doElse(node.body, node) + + visitWhile = visitFor + + def visitIf(self, node): + # The first test has to be handled separately from the rest. + # The first test is credited to the line with the "if", but the others + # are credited to the line with the test for the elif. + self.doSuite(node, node.tests[0][1]) + for t, n in node.tests[1:]: + self.doSuite(t, n) + self.doElse(node.tests[-1][1], node) + + def visitTryExcept(self, node): + self.doSuite(node, node.body) + for i in range(len(node.handlers)): + a, b, h = node.handlers[i] + if not a: + # It's a plain "except:". Find the previous suite. + if i > 0: + prev = node.handlers[i-1][2] + else: + prev = node.body + self.doPlainWordSuite(prev, h) + else: + self.doSuite(a, h) + self.doElse(node.handlers[-1][2], node) + + def visitTryFinally(self, node): + self.doSuite(node, node.body) + self.doPlainWordSuite(node.body, node.final) + + def visitWith(self, node): + self.doSuite(node, node.body) + + def visitGlobal(self, node): + # "global" statements don't execute like others (they don't call the + # trace function), so don't record their line numbers. + pass + +the_coverage = None + +class CoverageException(Exception): + pass + +class coverage: + # Name of the cache file (unless environment variable is set). + cache_default = ".coverage" + + # Environment variable naming the cache file. + cache_env = "COVERAGE_FILE" + + # A dictionary with an entry for (Python source file name, line number + # in that file) if that line has been executed. + c = {} + + # A map from canonical Python source file name to a dictionary in + # which there's an entry for each line number that has been + # executed. + cexecuted = {} + + # Cache of results of calling the analysis2() method, so that you can + # specify both -r and -a without doing double work. + analysis_cache = {} + + # Cache of results of calling the canonical_filename() method, to + # avoid duplicating work. + canonical_filename_cache = {} + + def __init__(self): + global the_coverage + if the_coverage: + raise CoverageException("Only one coverage object allowed.") + self.usecache = 1 + self.cache = None + self.parallel_mode = False + self.exclude_re = '' + self.nesting = 0 + self.cstack = [] + self.xstack = [] + self.relative_dir = self.abs_file(os.curdir)+os.sep + self.exclude('# *pragma[: ]*[nN][oO] *[cC][oO][vV][eE][rR]') + + # t(f, x, y). This method is passed to sys.settrace as a trace function. + # See [van Rossum 2001-07-20b, 9.2] for an explanation of sys.settrace and + # the arguments and return value of the trace function. + # See [van Rossum 2001-07-20a, 3.2] for a description of frame and code + # objects. + + def t(self, f, w, unused): #pragma: no cover + if w == 'line': + self.c[(f.f_code.co_filename, f.f_lineno)] = 1 + #-for c in self.cstack: + #- c[(f.f_code.co_filename, f.f_lineno)] = 1 + return self.t + + def help(self, error=None): #pragma: no cover + if error: + print error + print + print __doc__ + sys.exit(1) + + def command_line(self, argv, help_fn=None): + import getopt + help_fn = help_fn or self.help + settings = {} + optmap = { + '-a': 'annotate', + '-c': 'collect', + '-d:': 'directory=', + '-e': 'erase', + '-h': 'help', + '-i': 'ignore-errors', + '-m': 'show-missing', + '-p': 'parallel-mode', + '-r': 'report', + '-x': 'execute', + '-o:': 'omit=', + } + short_opts = string.join(map(lambda o: o[1:], optmap.keys()), '') + long_opts = optmap.values() + options, args = getopt.getopt(argv, short_opts, long_opts) + for o, a in options: + if optmap.has_key(o): + settings[optmap[o]] = 1 + elif optmap.has_key(o + ':'): + settings[optmap[o + ':']] = a + elif o[2:] in long_opts: + settings[o[2:]] = 1 + elif o[2:] + '=' in long_opts: + settings[o[2:]+'='] = a + else: #pragma: no cover + pass # Can't get here, because getopt won't return anything unknown. + + if settings.get('help'): + help_fn() + + for i in ['erase', 'execute']: + for j in ['annotate', 'report', 'collect']: + if settings.get(i) and settings.get(j): + help_fn("You can't specify the '%s' and '%s' " + "options at the same time." % (i, j)) + + args_needed = (settings.get('execute') + or settings.get('annotate') + or settings.get('report')) + action = (settings.get('erase') + or settings.get('collect') + or args_needed) + if not action: + help_fn("You must specify at least one of -e, -x, -c, -r, or -a.") + if not args_needed and args: + help_fn("Unexpected arguments: %s" % " ".join(args)) + + self.parallel_mode = settings.get('parallel-mode') + self.get_ready() + + if settings.get('erase'): + self.erase() + if settings.get('execute'): + if not args: + help_fn("Nothing to do.") + sys.argv = args + self.start() + import __main__ + sys.path[0] = os.path.dirname(sys.argv[0]) + execfile(sys.argv[0], __main__.__dict__) + if settings.get('collect'): + self.collect() + if not args: + args = self.cexecuted.keys() + + ignore_errors = settings.get('ignore-errors') + show_missing = settings.get('show-missing') + directory = settings.get('directory=') + + omit = settings.get('omit=') + if omit is not None: + omit = [self.abs_file(p) for p in omit.split(',')] + else: + omit = [] + + if settings.get('report'): + self.report(args, show_missing, ignore_errors, omit_prefixes=omit) + if settings.get('annotate'): + self.annotate(args, directory, ignore_errors, omit_prefixes=omit) + + def use_cache(self, usecache, cache_file=None): + self.usecache = usecache + if cache_file and not self.cache: + self.cache_default = cache_file + + def get_ready(self, parallel_mode=False): + if self.usecache and not self.cache: + self.cache = os.environ.get(self.cache_env, self.cache_default) + if self.parallel_mode: + self.cache += "." + gethostname() + "." + str(os.getpid()) + self.restore() + self.analysis_cache = {} + + def start(self, parallel_mode=False): + self.get_ready() + if self.nesting == 0: #pragma: no cover + sys.settrace(self.t) + if hasattr(threading, 'settrace'): + threading.settrace(self.t) + self.nesting += 1 + + def stop(self): + self.nesting -= 1 + if self.nesting == 0: #pragma: no cover + sys.settrace(None) + if hasattr(threading, 'settrace'): + threading.settrace(None) + + def erase(self): + self.get_ready() + self.c = {} + self.analysis_cache = {} + self.cexecuted = {} + if self.cache and os.path.exists(self.cache): + os.remove(self.cache) + + def exclude(self, re): + if self.exclude_re: + self.exclude_re += "|" + self.exclude_re += "(" + re + ")" + + def begin_recursive(self): + self.cstack.append(self.c) + self.xstack.append(self.exclude_re) + + def end_recursive(self): + self.c = self.cstack.pop() + self.exclude_re = self.xstack.pop() + + # save(). Save coverage data to the coverage cache. + + def save(self): + if self.usecache and self.cache: + self.canonicalize_filenames() + cache = open(self.cache, 'wb') + import marshal + marshal.dump(self.cexecuted, cache) + cache.close() + + # restore(). Restore coverage data from the coverage cache (if it exists). + + def restore(self): + self.c = {} + self.cexecuted = {} + assert self.usecache + if os.path.exists(self.cache): + self.cexecuted = self.restore_file(self.cache) + + def restore_file(self, file_name): + try: + cache = open(file_name, 'rb') + import marshal + cexecuted = marshal.load(cache) + cache.close() + if isinstance(cexecuted, types.DictType): + return cexecuted + else: + return {} + except: + return {} + + # collect(). Collect data in multiple files produced by parallel mode + + def collect(self): + cache_dir, local = os.path.split(self.cache) + for f in os.listdir(cache_dir or '.'): + if not f.startswith(local): + continue + + full_path = os.path.join(cache_dir, f) + cexecuted = self.restore_file(full_path) + self.merge_data(cexecuted) + + def merge_data(self, new_data): + for file_name, file_data in new_data.items(): + if self.cexecuted.has_key(file_name): + self.merge_file_data(self.cexecuted[file_name], file_data) + else: + self.cexecuted[file_name] = file_data + + def merge_file_data(self, cache_data, new_data): + for line_number in new_data.keys(): + if not cache_data.has_key(line_number): + cache_data[line_number] = new_data[line_number] + + def abs_file(self, filename): + """ Helper function to turn a filename into an absolute normalized + filename. + """ + return os.path.normcase(os.path.abspath(os.path.realpath(filename))) + + def get_zip_data(self, filename): + """ Get data from `filename` if it is a zip file path, or return None + if it is not. + """ + markers = ['.zip'+os.sep, '.egg'+os.sep] + for marker in markers: + if marker in filename: + parts = filename.split(marker) + try: + zi = zipimport.zipimporter(parts[0]+marker[:-1]) + except zipimport.ZipImportError: + continue + try: + data = zi.get_data(parts[1]) + except IOError: + continue + return data + return None + + # canonical_filename(filename). Return a canonical filename for the + # file (that is, an absolute path with no redundant components and + # normalized case). See [GDR 2001-12-04b, 3.3]. + + def canonical_filename(self, filename): + if not self.canonical_filename_cache.has_key(filename): + f = filename + if os.path.isabs(f) and not os.path.exists(f): + if not self.get_zip_data(f): + f = os.path.basename(f) + if not os.path.isabs(f): + for path in [os.curdir] + sys.path: + g = os.path.join(path, f) + if os.path.exists(g): + f = g + break + cf = self.abs_file(f) + self.canonical_filename_cache[filename] = cf + return self.canonical_filename_cache[filename] + + # canonicalize_filenames(). Copy results from "c" to "cexecuted", + # canonicalizing filenames on the way. Clear the "c" map. + + def canonicalize_filenames(self): + for filename, lineno in self.c.keys(): + if filename == '': + # Can't do anything useful with exec'd strings, so skip them. + continue + f = self.canonical_filename(filename) + if not self.cexecuted.has_key(f): + self.cexecuted[f] = {} + self.cexecuted[f][lineno] = 1 + self.c = {} + + # morf_filename(morf). Return the filename for a module or file. + + def morf_filename(self, morf): + if hasattr(morf, '__file__'): + f = morf.__file__ + else: + f = morf + return self.canonical_filename(f) + + # analyze_morf(morf). Analyze the module or filename passed as + # the argument. If the source code can't be found, raise an error. + # Otherwise, return a tuple of (1) the canonical filename of the + # source code for the module, (2) a list of lines of statements + # in the source code, (3) a list of lines of excluded statements, + # and (4), a map of line numbers to multi-line line number ranges, for + # statements that cross lines. + + def analyze_morf(self, morf): + if self.analysis_cache.has_key(morf): + return self.analysis_cache[morf] + filename = self.morf_filename(morf) + ext = os.path.splitext(filename)[1] + source, sourcef = None, None + if ext == '.pyc': + if not os.path.exists(filename[:-1]): + source = self.get_zip_data(filename[:-1]) + if not source: + raise CoverageException( + "No source for compiled code '%s'." % filename + ) + filename = filename[:-1] + if not source: + sourcef = open(filename, 'rU') + source = sourcef.read() + try: + lines, excluded_lines, line_map = self.find_executable_statements( + source, exclude=self.exclude_re + ) + except SyntaxError, synerr: + raise CoverageException( + "Couldn't parse '%s' as Python source: '%s' at line %d" % + (filename, synerr.msg, synerr.lineno) + ) + if sourcef: + sourcef.close() + result = filename, lines, excluded_lines, line_map + self.analysis_cache[morf] = result + return result + + def first_line_of_tree(self, tree): + while True: + if len(tree) == 3 and type(tree[2]) == type(1): + return tree[2] + tree = tree[1] + + def last_line_of_tree(self, tree): + while True: + if len(tree) == 3 and type(tree[2]) == type(1): + return tree[2] + tree = tree[-1] + + def find_docstring_pass_pair(self, tree, spots): + for i in range(1, len(tree)): + if self.is_string_constant(tree[i]) and self.is_pass_stmt(tree[i+1]): + first_line = self.first_line_of_tree(tree[i]) + last_line = self.last_line_of_tree(tree[i+1]) + self.record_multiline(spots, first_line, last_line) + + def is_string_constant(self, tree): + try: + return tree[0] == symbol.stmt and tree[1][1][1][0] == symbol.expr_stmt + except: + return False + + def is_pass_stmt(self, tree): + try: + return tree[0] == symbol.stmt and tree[1][1][1][0] == symbol.pass_stmt + except: + return False + + def record_multiline(self, spots, i, j): + for l in range(i, j+1): + spots[l] = (i, j) + + def get_suite_spots(self, tree, spots): + """ Analyze a parse tree to find suite introducers which span a number + of lines. + """ + for i in range(1, len(tree)): + if type(tree[i]) == type(()): + if tree[i][0] == symbol.suite: + # Found a suite, look back for the colon and keyword. + lineno_colon = lineno_word = None + for j in range(i-1, 0, -1): + if tree[j][0] == token.COLON: + # Colons are never executed themselves: we want the + # line number of the last token before the colon. + lineno_colon = self.last_line_of_tree(tree[j-1]) + elif tree[j][0] == token.NAME: + if tree[j][1] == 'elif': + # Find the line number of the first non-terminal + # after the keyword. + t = tree[j+1] + while t and token.ISNONTERMINAL(t[0]): + t = t[1] + if t: + lineno_word = t[2] + else: + lineno_word = tree[j][2] + break + elif tree[j][0] == symbol.except_clause: + # "except" clauses look like: + # ('except_clause', ('NAME', 'except', lineno), ...) + if tree[j][1][0] == token.NAME: + lineno_word = tree[j][1][2] + break + if lineno_colon and lineno_word: + # Found colon and keyword, mark all the lines + # between the two with the two line numbers. + self.record_multiline(spots, lineno_word, lineno_colon) + + # "pass" statements are tricky: different versions of Python + # treat them differently, especially in the common case of a + # function with a doc string and a single pass statement. + self.find_docstring_pass_pair(tree[i], spots) + + elif tree[i][0] == symbol.simple_stmt: + first_line = self.first_line_of_tree(tree[i]) + last_line = self.last_line_of_tree(tree[i]) + if first_line != last_line: + self.record_multiline(spots, first_line, last_line) + self.get_suite_spots(tree[i], spots) + + def find_executable_statements(self, text, exclude=None): + # Find lines which match an exclusion pattern. + excluded = {} + suite_spots = {} + if exclude: + reExclude = re.compile(exclude) + lines = text.split('\n') + for i in range(len(lines)): + if reExclude.search(lines[i]): + excluded[i+1] = 1 + + # Parse the code and analyze the parse tree to find out which statements + # are multiline, and where suites begin and end. + import parser + tree = parser.suite(text+'\n\n').totuple(1) + self.get_suite_spots(tree, suite_spots) + #print "Suite spots:", suite_spots + + # Use the compiler module to parse the text and find the executable + # statements. We add newlines to be impervious to final partial lines. + statements = {} + ast = compiler.parse(text+'\n\n') + visitor = StatementFindingAstVisitor(statements, excluded, suite_spots) + compiler.walk(ast, visitor, walker=visitor) + + lines = statements.keys() + lines.sort() + excluded_lines = excluded.keys() + excluded_lines.sort() + return lines, excluded_lines, suite_spots + + # format_lines(statements, lines). Format a list of line numbers + # for printing by coalescing groups of lines as long as the lines + # represent consecutive statements. This will coalesce even if + # there are gaps between statements, so if statements = + # [1,2,3,4,5,10,11,12,13,14] and lines = [1,2,5,10,11,13,14] then + # format_lines will return "1-2, 5-11, 13-14". + + def format_lines(self, statements, lines): + pairs = [] + i = 0 + j = 0 + start = None + pairs = [] + while i < len(statements) and j < len(lines): + if statements[i] == lines[j]: + if start == None: + start = lines[j] + end = lines[j] + j = j + 1 + elif start: + pairs.append((start, end)) + start = None + i = i + 1 + if start: + pairs.append((start, end)) + def stringify(pair): + start, end = pair + if start == end: + return "%d" % start + else: + return "%d-%d" % (start, end) + ret = string.join(map(stringify, pairs), ", ") + return ret + + # Backward compatibility with version 1. + def analysis(self, morf): + f, s, _, m, mf = self.analysis2(morf) + return f, s, m, mf + + def analysis2(self, morf): + filename, statements, excluded, line_map = self.analyze_morf(morf) + self.canonicalize_filenames() + if not self.cexecuted.has_key(filename): + self.cexecuted[filename] = {} + missing = [] + for line in statements: + lines = line_map.get(line, [line, line]) + for l in range(lines[0], lines[1]+1): + if self.cexecuted[filename].has_key(l): + break + else: + missing.append(line) + return (filename, statements, excluded, missing, + self.format_lines(statements, missing)) + + def relative_filename(self, filename): + """ Convert filename to relative filename from self.relative_dir. + """ + return filename.replace(self.relative_dir, "") + + def morf_name(self, morf): + """ Return the name of morf as used in report. + """ + if hasattr(morf, '__name__'): + return morf.__name__ + else: + return self.relative_filename(os.path.splitext(morf)[0]) + + def filter_by_prefix(self, morfs, omit_prefixes): + """ Return list of morfs where the morf name does not begin + with any one of the omit_prefixes. + """ + filtered_morfs = [] + for morf in morfs: + for prefix in omit_prefixes: + if self.morf_name(morf).startswith(prefix): + break + else: + filtered_morfs.append(morf) + + return filtered_morfs + + def morf_name_compare(self, x, y): + return cmp(self.morf_name(x), self.morf_name(y)) + + def report(self, morfs, show_missing=1, ignore_errors=0, file=None, omit_prefixes=[]): + if not isinstance(morfs, types.ListType): + morfs = [morfs] + # On windows, the shell doesn't expand wildcards. Do it here. + globbed = [] + for morf in morfs: + if isinstance(morf, strclass): + globbed.extend(glob.glob(morf)) + else: + globbed.append(morf) + morfs = globbed + + morfs = self.filter_by_prefix(morfs, omit_prefixes) + morfs.sort(self.morf_name_compare) + + max_name = max([5,] + map(len, map(self.morf_name, morfs))) + fmt_name = "%%- %ds " % max_name + fmt_err = fmt_name + "%s: %s" + header = fmt_name % "Name" + " Stmts Exec Cover" + fmt_coverage = fmt_name + "% 6d % 6d % 5d%%" + if show_missing: + header = header + " Missing" + fmt_coverage = fmt_coverage + " %s" + if not file: + file = sys.stdout + print >>file, header + print >>file, "-" * len(header) + total_statements = 0 + total_executed = 0 + for morf in morfs: + name = self.morf_name(morf) + try: + _, statements, _, missing, readable = self.analysis2(morf) + n = len(statements) + m = n - len(missing) + if n > 0: + pc = 100.0 * m / n + else: + pc = 100.0 + args = (name, n, m, pc) + if show_missing: + args = args + (readable,) + print >>file, fmt_coverage % args + total_statements = total_statements + n + total_executed = total_executed + m + except KeyboardInterrupt: #pragma: no cover + raise + except: + if not ignore_errors: + typ, msg = sys.exc_info()[:2] + print >>file, fmt_err % (name, typ, msg) + if len(morfs) > 1: + print >>file, "-" * len(header) + if total_statements > 0: + pc = 100.0 * total_executed / total_statements + else: + pc = 100.0 + args = ("TOTAL", total_statements, total_executed, pc) + if show_missing: + args = args + ("",) + print >>file, fmt_coverage % args + + # annotate(morfs, ignore_errors). + + blank_re = re.compile(r"\s*(#|$)") + else_re = re.compile(r"\s*else\s*:\s*(#|$)") + + def annotate(self, morfs, directory=None, ignore_errors=0, omit_prefixes=[]): + morfs = self.filter_by_prefix(morfs, omit_prefixes) + for morf in morfs: + try: + filename, statements, excluded, missing, _ = self.analysis2(morf) + self.annotate_file(filename, statements, excluded, missing, directory) + except KeyboardInterrupt: + raise + except: + if not ignore_errors: + raise + + def annotate_file(self, filename, statements, excluded, missing, directory=None): + source = open(filename, 'r') + if directory: + dest_file = os.path.join(directory, + os.path.basename(filename) + + ',cover') + else: + dest_file = filename + ',cover' + dest = open(dest_file, 'w') + lineno = 0 + i = 0 + j = 0 + covered = 1 + while 1: + line = source.readline() + if line == '': + break + lineno = lineno + 1 + while i < len(statements) and statements[i] < lineno: + i = i + 1 + while j < len(missing) and missing[j] < lineno: + j = j + 1 + if i < len(statements) and statements[i] == lineno: + covered = j >= len(missing) or missing[j] > lineno + if self.blank_re.match(line): + dest.write(' ') + elif self.else_re.match(line): + # Special logic for lines containing only 'else:'. + # See [GDR 2001-12-04b, 3.2]. + if i >= len(statements) and j >= len(missing): + dest.write('! ') + elif i >= len(statements) or j >= len(missing): + dest.write('> ') + elif statements[i] == missing[j]: + dest.write('! ') + else: + dest.write('> ') + elif lineno in excluded: + dest.write('- ') + elif covered: + dest.write('> ') + else: + dest.write('! ') + dest.write(line) + source.close() + dest.close() + +# Singleton object. +the_coverage = coverage() + +# Module functions call methods in the singleton object. +def use_cache(*args, **kw): + return the_coverage.use_cache(*args, **kw) + +def start(*args, **kw): + return the_coverage.start(*args, **kw) + +def stop(*args, **kw): + return the_coverage.stop(*args, **kw) + +def erase(*args, **kw): + return the_coverage.erase(*args, **kw) + +def begin_recursive(*args, **kw): + return the_coverage.begin_recursive(*args, **kw) + +def end_recursive(*args, **kw): + return the_coverage.end_recursive(*args, **kw) + +def exclude(*args, **kw): + return the_coverage.exclude(*args, **kw) + +def analysis(*args, **kw): + return the_coverage.analysis(*args, **kw) + +def analysis2(*args, **kw): + return the_coverage.analysis2(*args, **kw) + +def report(*args, **kw): + return the_coverage.report(*args, **kw) + +def annotate(*args, **kw): + return the_coverage.annotate(*args, **kw) + +def annotate_file(*args, **kw): + return the_coverage.annotate_file(*args, **kw) + +# Save coverage data when Python exits. (The atexit module wasn't +# introduced until Python 2.0, so use sys.exitfunc when it's not +# available.) +try: + import atexit + atexit.register(the_coverage.save) +except ImportError: + sys.exitfunc = the_coverage.save + +def main(): + the_coverage.command_line(sys.argv[1:]) + +# Command-line interface. +if __name__ == '__main__': + main() + + +# A. REFERENCES +# +# [GDR 2001-12-04a] "Statement coverage for Python"; Gareth Rees; +# Ravenbrook Limited; 2001-12-04; +# . +# +# [GDR 2001-12-04b] "Statement coverage for Python: design and +# analysis"; Gareth Rees; Ravenbrook Limited; 2001-12-04; +# . +# +# [van Rossum 2001-07-20a] "Python Reference Manual (releae 2.1.1)"; +# Guide van Rossum; 2001-07-20; +# . +# +# [van Rossum 2001-07-20b] "Python Library Reference"; Guido van Rossum; +# 2001-07-20; . +# +# +# B. DOCUMENT HISTORY +# +# 2001-12-04 GDR Created. +# +# 2001-12-06 GDR Added command-line interface and source code +# annotation. +# +# 2001-12-09 GDR Moved design and interface to separate documents. +# +# 2001-12-10 GDR Open cache file as binary on Windows. Allow +# simultaneous -e and -x, or -a and -r. +# +# 2001-12-12 GDR Added command-line help. Cache analysis so that it +# only needs to be done once when you specify -a and -r. +# +# 2001-12-13 GDR Improved speed while recording. Portable between +# Python 1.5.2 and 2.1.1. +# +# 2002-01-03 GDR Module-level functions work correctly. +# +# 2002-01-07 GDR Update sys.path when running a file with the -x option, +# so that it matches the value the program would get if it were run on +# its own. +# +# 2004-12-12 NMB Significant code changes. +# - Finding executable statements has been rewritten so that docstrings and +# other quirks of Python execution aren't mistakenly identified as missing +# lines. +# - Lines can be excluded from consideration, even entire suites of lines. +# - The filesystem cache of covered lines can be disabled programmatically. +# - Modernized the code. +# +# 2004-12-14 NMB Minor tweaks. Return 'analysis' to its original behavior +# and add 'analysis2'. Add a global for 'annotate', and factor it, adding +# 'annotate_file'. +# +# 2004-12-31 NMB Allow for keyword arguments in the module global functions. +# Thanks, Allen. +# +# 2005-12-02 NMB Call threading.settrace so that all threads are measured. +# Thanks Martin Fuzzey. Add a file argument to report so that reports can be +# captured to a different destination. +# +# 2005-12-03 NMB coverage.py can now measure itself. +# +# 2005-12-04 NMB Adapted Greg Rogers' patch for using relative filenames, +# and sorting and omitting files to report on. +# +# 2006-07-23 NMB Applied Joseph Tate's patch for function decorators. +# +# 2006-08-21 NMB Applied Sigve Tjora and Mark van der Wal's fixes for argument +# handling. +# +# 2006-08-22 NMB Applied Geoff Bache's parallel mode patch. +# +# 2006-08-23 NMB Refactorings to improve testability. Fixes to command-line +# logic for parallel mode and collect. +# +# 2006-08-25 NMB "#pragma: nocover" is excluded by default. +# +# 2006-09-10 NMB Properly ignore docstrings and other constant expressions that +# appear in the middle of a function, a problem reported by Tim Leslie. +# Minor changes to avoid lint warnings. +# +# 2006-09-17 NMB coverage.erase() shouldn't clobber the exclude regex. +# Change how parallel mode is invoked, and fix erase() so that it erases the +# cache when called programmatically. +# +# 2007-07-21 NMB In reports, ignore code executed from strings, since we can't +# do anything useful with it anyway. +# Better file handling on Linux, thanks Guillaume Chazarain. +# Better shell support on Windows, thanks Noel O'Boyle. +# Python 2.2 support maintained, thanks Catherine Proulx. +# +# 2007-07-22 NMB Python 2.5 now fully supported. The method of dealing with +# multi-line statements is now less sensitive to the exact line that Python +# reports during execution. Pass statements are handled specially so that their +# disappearance during execution won't throw off the measurement. +# +# 2007-07-23 NMB Now Python 2.5 is *really* fully supported: the body of the +# new with statement is counted as executable. +# +# 2007-07-29 NMB Better packaging. +# +# 2007-09-30 NMB Don't try to predict whether a file is Python source based on +# the extension. Extensionless files are often Pythons scripts. Instead, simply +# parse the file and catch the syntax errors. Hat tip to Ben Finney. +# +# 2008-05-25 NMB Open files in rU mode to avoid line ending craziness. +# Thanks, Edward Loper. +# +# 2008-09-14 NMB Add support for finding source files in eggs. +# Don't check for morf's being instances of ModuleType, instead use duck typing +# so that pseudo-modules can participate. Thanks, Imri Goldberg. +# Use os.realpath as part of the fixing of filenames so that symlinks won't +# confuse things. Thanks, Patrick Mezard. +# +# +# C. COPYRIGHT AND LICENCE +# +# Copyright 2001 Gareth Rees. All rights reserved. +# Copyright 2004-2008 Ned Batchelder. All rights reserved. +# +# Redistribution and use in source and binary forms, with or without +# modification, are permitted provided that the following conditions are +# met: +# +# 1. Redistributions of source code must retain the above copyright +# notice, this list of conditions and the following disclaimer. +# +# 2. Redistributions in binary form must reproduce the above copyright +# notice, this list of conditions and the following disclaimer in the +# documentation and/or other materials provided with the +# distribution. +# +# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +# "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +# LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +# A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +# HOLDERS AND CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, +# INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, +# BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS +# OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND +# ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR +# TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE +# USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH +# DAMAGE. +# +# $Id: coverage.py 100 2008-10-12 12:08:22Z nedbat $ diff --git a/tests/root/_static/README b/tests/root/_static/README new file mode 100644 index 000000000..d517219be --- /dev/null +++ b/tests/root/_static/README @@ -0,0 +1 @@ +This placeholder file is there because Mercurial ignores empty directories. diff --git a/tests/root/_templates/layout.html b/tests/root/_templates/layout.html index 1f4688e60..e8920025d 100644 --- a/tests/root/_templates/layout.html +++ b/tests/root/_templates/layout.html @@ -1,4 +1,5 @@ {% extends "!layout.html" %} {% block extrahead %} +{{ super() }} {% endblock %} diff --git a/tests/root/autodoc.txt b/tests/root/autodoc.txt index 2b57e0e98..c718feb4c 100644 --- a/tests/root/autodoc.txt +++ b/tests/root/autodoc.txt @@ -1,7 +1,28 @@ Autodoc tests ============= +Just testing a few autodoc possibilities... + +.. automodule:: util + .. automodule:: test_autodoc :members: .. autofunction:: function + +.. autoclass:: Class + :inherited-members: + + Additional content. + +.. autoclass:: Outer + :members: Inner + +.. autoattribute:: Class.docattr + +.. autoexception:: CustomEx + :members: f + +.. autoclass:: CustomDict + :show-inheritance: + :members: diff --git a/tests/root/conf.py b/tests/root/conf.py index 8d2b276f9..85e9f468b 100644 --- a/tests/root/conf.py +++ b/tests/root/conf.py @@ -1,182 +1,68 @@ # -*- coding: utf-8 -*- -# -# Sphinx Tests documentation build configuration file, created by -# sphinx-quickstart on Wed Jun 4 23:49:58 2008. -# -# This file is execfile()d with the current directory set to its containing dir. -# -# The contents of this file are pickled, so don't put values in the namespace -# that aren't pickleable (module imports are okay, they're removed automatically). -# -# All configuration values have a default value; values that are commented out -# serve to show the default value. import sys, os -# If your extensions are in another directory, add it here. If the directory -# is relative to the documentation root, use os.path.abspath to make it -# absolute, like shown here. sys.path.append(os.path.abspath('.')) -# General configuration -# --------------------- +extensions = ['ext', 'sphinx.ext.autodoc', 'sphinx.ext.jsmath', + 'sphinx.ext.coverage', 'sphinx.ext.todo'] -# Add any Sphinx extension module names here, as strings. They can be extensions -# coming with Sphinx (named 'sphinx.ext.*') or your custom ones. -extensions = ['ext', 'sphinx.ext.autodoc', 'sphinx.ext.jsmath', 'sphinx.ext.coverage'] jsmath_path = 'dummy.js' -# Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] -# The suffix of source filenames. +master_doc = 'contents' source_suffix = '.txt' -# The master toctree document. -master_doc = 'contents' - -# General substitutions. -project = 'Sphinx Tests' -copyright = '2008, Georg Brandl' - -# The default replacements for |version| and |release|, also used in various -# other places throughout the built documents. -# -# The short X.Y version. -version = '0.4' -# The full version, including alpha/beta/rc tags. -release = '0.4alpha1' - -# There are two options for replacing |today|: either, you set today to some -# non-false value, then it is used: -#today = '' -# Else, today_fmt is used as the format for a strftime call. +project = 'Sphinx ' +copyright = '2008, Georg Brandl & Team' +# If this is changed, remember to update the versionchanges! +version = '0.6' +release = '0.6alpha1' today_fmt = '%B %d, %Y' - -# List of documents that shouldn't be included in the build. #unused_docs = [] - -# List of directories, relative to source directories, that shouldn't be searched -# for source files. exclude_trees = ['_build'] - keep_warnings = True - -# If true, '()' will be appended to :func: etc. cross-reference text. -#add_function_parentheses = True - -# If true, the current module name will be prepended to all description -# unit titles (such as .. function::). -#add_module_names = True - -# If true, sectionauthor and moduleauthor directives will be shown in the -# output. They are ignored by default. -#show_authors = False - -# The name of the Pygments (syntax highlighting) style to use. pygments_style = 'sphinx' +rst_epilog = '.. |subst| replace:: global substitution' -# Options for HTML output -# ----------------------- +html_theme = 'testtheme' +html_theme_path = ['.'] +html_theme_options = {'testopt': 'testoverride'} -# The style sheet to use for HTML and HTML Help pages. A file of that name -# must exist either in Sphinx' static/ path, or in one of the custom paths -# given in html_static_path. html_style = 'default.css' - -# The name for this set of Sphinx documents. If None, it defaults to -# " v documentation". -#html_title = None - -# A shorter title for the navigation bar. Default is the same as html_title. -#html_short_title = None - -# The name of an image file (within the static path) to place at the top of -# the sidebar. -#html_logo = None - -# Add any paths that contain custom static files (such as style sheets) here, -# relative to this directory. They are copied after the builtin static files, -# so a file named "default.css" will overwrite the builtin "default.css". html_static_path = ['_static'] - -# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, -# using the given strftime format. html_last_updated_fmt = '%b %d, %Y' - -# If true, SmartyPants will be used to convert quotes and dashes to -# typographically correct entities. -#html_use_smartypants = True - -# Custom sidebar templates, maps document names to template names. -#html_sidebars = {} - -# Additional templates that should be rendered to pages, maps page names to -# template names. -#html_additional_pages = {} - -# If false, no module index is generated. -#html_use_modindex = True - -# If false, no index is generated. -#html_use_index = True - -# If true, the reST sources are included in the HTML build as _sources/. -#html_copy_source = True - -# If true, an OpenSearch description file will be output, and all pages will -# contain a tag referring to it. The value of this option must be the -# base URL from which the finished HTML is served. -#html_use_opensearch = '' - -# If nonempty, this is the file name suffix for HTML files (e.g. ".xhtml"). -#html_file_suffix = '' - html_context = {'hckey': 'hcval'} -# Output file base name for HTML help builder. htmlhelp_basename = 'SphinxTestsdoc' - -# Options for LaTeX output -# ------------------------ - -# The paper size ('letter' or 'a4'). -#latex_paper_size = 'letter' - -# The font size ('10pt', '11pt' or '12pt'). -#latex_font_size = '10pt' - -# Grouping the document tree into LaTeX files. List of tuples -# (source start file, target name, title, author, document class [howto/manual]). latex_documents = [ ('contents', 'SphinxTests.tex', 'Sphinx Tests Documentation', 'Georg Brandl', 'manual'), ] -# The name of an image file (relative to this directory) to place at the top of -# the title page. -#latex_logo = None - -# For "manual" documents, if this is true, then toplevel headings are parts, -# not chapters. -#latex_use_parts = False - -# Additional stuff for the LaTeX preamble. -#latex_preamble = '' - -# Documents to append as an appendix to all manuals. -#latex_appendices = [] - -# If false, no module index is generated. -#latex_use_modindex = True +latex_additional_files = ['svgimg.svg'] value_from_conf_py = 84 coverage_c_path = ['special/*.h'] coverage_c_regexes = {'cfunction': r'^PyAPI_FUNC\(.*\)\s+([^_][\w_]+)'} +# modify tags from conf.py +tags.add('confpytag') + +from sphinx import addnodes + +def userdesc_parse(env, sig, signode): + x, y = sig.split(':') + signode += addnodes.desc_name(x, x) + signode += addnodes.desc_parameterlist() + signode[-1] += addnodes.desc_parameter(y, y) + return x def setup(app): app.add_config_value('value_from_conf_py', 42, False) + app.add_description_unit('userdesc', 'userdescrole', '%s (userdesc)', + userdesc_parse) diff --git a/tests/root/contents.txt b/tests/root/contents.txt index e8e6a5644..0e52593e2 100644 --- a/tests/root/contents.txt +++ b/tests/root/contents.txt @@ -9,14 +9,19 @@ Contents: .. toctree:: :maxdepth: 2 + :numbered: images + subdir/images + subdir/includes includes markup desc math autodoc + Python + Indices and tables ================== diff --git a/tests/root/desc.txt b/tests/root/desc.txt index beb470b60..d6915dc27 100644 --- a/tests/root/desc.txt +++ b/tests/root/desc.txt @@ -58,3 +58,14 @@ Testing references ================== Referencing :class:`mod.Cls` or :Class:`mod.Cls` should be the same. + + +User markup +=========== + +.. userdesc:: myobj:parameter + + Description of userdesc. + + +Referencing :userdescrole:`myobj`. diff --git a/tests/root/images.txt b/tests/root/images.txt index 84f89c6e0..bd64d573a 100644 --- a/tests/root/images.txt +++ b/tests/root/images.txt @@ -9,6 +9,8 @@ Sphinx image handling .. an image with path name (relative to this directory!) .. image:: subdir/img.png + :height: 100 + :width: 200 .. an image with unspecified extension .. image:: img.* @@ -18,3 +20,9 @@ Sphinx image handling .. a non-local image URI .. image:: http://www.python.org/logo.png + +.. an image with subdir and unspecified extension +.. image:: subdir/simg.* + +.. an SVG image (for HTML at least) +.. image:: svgimg.* diff --git a/tests/root/includes.txt b/tests/root/includes.txt index ad507fc68..44e33af0d 100644 --- a/tests/root/includes.txt +++ b/tests/root/includes.txt @@ -14,3 +14,33 @@ Test file and literal inclusion :encoding: latin-1 .. include:: wrongenc.inc :encoding: latin-1 + +Literalinclude options +====================== + +.. highlight:: text + +.. cssclass:: inc-pyobj1 +.. literalinclude:: literal.inc + :pyobject: Foo + +.. cssclass:: inc-pyobj2 +.. literalinclude:: literal.inc + :pyobject: Bar.baz + +.. cssclass:: inc-lines +.. literalinclude:: literal.inc + :lines: 6-7,9 + +.. cssclass:: inc-startend +.. literalinclude:: literal.inc + :start-after: coding: utf-8 + :end-before: class Foo + + +Testing downloadable files +========================== + +Download :download:`img.png` here. +Download :download:`this ` there. +Don't download :download:`this `. diff --git a/tests/root/literal.inc b/tests/root/literal.inc index a4ce93d24..d5b9890c9 100644 --- a/tests/root/literal.inc +++ b/tests/root/literal.inc @@ -2,3 +2,12 @@ # -*- coding: utf-8 -*- foo = u"Including Unicode characters: üöä" + +class Foo: + pass + +class Bar: + def baz(): + pass + +def bar(): pass diff --git a/tests/root/markup.txt b/tests/root/markup.txt index c2c6b7440..52d407e22 100644 --- a/tests/root/markup.txt +++ b/tests/root/markup.txt @@ -11,6 +11,8 @@ Testing various markup :author: Me :keywords: docs, sphinx +A |subst|. + .. _label: :: @@ -82,13 +84,13 @@ Tables Version markup -------------- -.. versionadded:: 0.5 +.. versionadded:: 0.6 Some funny **stuff**. -.. versionchanged:: 0.5 +.. versionchanged:: 0.6 Even more funny stuff. -.. deprecated:: 0.4 +.. deprecated:: 0.6 Boring stuff. @@ -104,6 +106,16 @@ Reference lookup: [Ref1]_ (defined in another file). `Google `_ For everything. +.. hlist:: + :columns: 4 + + * This + * is + * a horizontal + * list + * with several + * items + .. rubric:: Side note This is a side note. @@ -140,6 +152,7 @@ Option list: try2_stmt: "try" ":" `suite` : "finally" ":" `suite` +Test :abbr:`abbr (abbreviation)` and another :abbr:`abbr (abbreviation)`. Index markup ------------ @@ -148,6 +161,14 @@ Index markup single: entry pair: entry; pair triple: index; entry; triple + keyword: with + +Invalid index markup... + +.. index:: + single: + pair: + keyword: Ö... Some strange characters @@ -156,6 +177,26 @@ Index markup Testing öäü... +Only directive +-------------- + +.. only:: html + + In HTML. + +.. only:: latex + + In LaTeX. + +.. only:: html or latex + + In both. + +.. only:: confpytag and (testtag or nonexisting_tag) + + Always present, because set through conf.py/command line. + + .. rubric:: Footnotes .. [#] Like footnotes. diff --git a/tests/root/rimg.png b/tests/root/rimg.png new file mode 100644 index 000000000..1081dc143 Binary files /dev/null and b/tests/root/rimg.png differ diff --git a/tests/root/special/code.py b/tests/root/special/code.py new file mode 100644 index 000000000..70c48d2e7 --- /dev/null +++ b/tests/root/special/code.py @@ -0,0 +1,2 @@ +print "line 1" +print "line 2" diff --git a/tests/root/subdir/images.txt b/tests/root/subdir/images.txt new file mode 100644 index 000000000..f2adf88d3 --- /dev/null +++ b/tests/root/subdir/images.txt @@ -0,0 +1,6 @@ +Image including source in subdir +================================ + +.. image:: img.* + +.. image:: /rimg.png diff --git a/tests/root/subdir/includes.txt b/tests/root/subdir/includes.txt new file mode 100644 index 000000000..3e1ae0d13 --- /dev/null +++ b/tests/root/subdir/includes.txt @@ -0,0 +1,12 @@ +Including in subdir +=================== + +.. absolute filename +.. literalinclude:: /special/code.py + :lines: 1 + +.. relative filename +.. literalinclude:: ../special/code.py + :lines: 2 + +Absolute :download:`/img.png` download. diff --git a/tests/root/subdir/simg.png b/tests/root/subdir/simg.png new file mode 100644 index 000000000..72c12d13f Binary files /dev/null and b/tests/root/subdir/simg.png differ diff --git a/tests/root/svgimg.pdf b/tests/root/svgimg.pdf new file mode 100644 index 000000000..cacbd855d Binary files /dev/null and b/tests/root/svgimg.pdf differ diff --git a/tests/root/svgimg.svg b/tests/root/svgimg.svg new file mode 100644 index 000000000..10e035b6d --- /dev/null +++ b/tests/root/svgimg.svg @@ -0,0 +1,158 @@ + + + + + + + + + + + + + + Part of the Flat Icon Collection (Thu Aug 26 14:31:40 2004) + + + +
  • + + + + + + </Agent> + </publisher> + <creator + id="creator24"> + <Agent + about="" + id="Agent25"> + <title + id="title26">Danny Allen + + + + + Danny Allen + + + + image/svg+xml + + + + + en + + + + + image/svg+xml + + + + + + + + + + + + + diff --git a/tests/root/testtheme/layout.html b/tests/root/testtheme/layout.html new file mode 100644 index 000000000..81372be0f --- /dev/null +++ b/tests/root/testtheme/layout.html @@ -0,0 +1,5 @@ +{% extends "basic/layout.html" %} +{% block extrahead %} + +{{ super() }} +{% endblock %} diff --git a/tests/root/testtheme/static/staticimg.png b/tests/root/testtheme/static/staticimg.png new file mode 100644 index 000000000..1081dc143 Binary files /dev/null and b/tests/root/testtheme/static/staticimg.png differ diff --git a/tests/root/testtheme/static/statictmpl.html_t b/tests/root/testtheme/static/statictmpl.html_t new file mode 100644 index 000000000..4ab292b42 --- /dev/null +++ b/tests/root/testtheme/static/statictmpl.html_t @@ -0,0 +1,2 @@ + +{{ project|e }} diff --git a/tests/root/testtheme/theme.conf b/tests/root/testtheme/theme.conf new file mode 100644 index 000000000..a87767379 --- /dev/null +++ b/tests/root/testtheme/theme.conf @@ -0,0 +1,7 @@ +[theme] +inherit = basic +stylesheet = default.css +pygments_style = emacs + +[options] +testopt = optdefault diff --git a/tests/root/ziptheme.zip b/tests/root/ziptheme.zip new file mode 100644 index 000000000..8a246ed98 Binary files /dev/null and b/tests/root/ziptheme.zip differ diff --git a/tests/run.py b/tests/run.py index f67a34327..4cc23442a 100755 --- a/tests/run.py +++ b/tests/run.py @@ -6,8 +6,8 @@ This script runs the Sphinx unit test suite. - :copyright: 2008 by Georg Brandl. - :license: BSD. + :copyright: Copyright 2007-2009 by the Sphinx team, see AUTHORS. + :license: BSD, see LICENSE for details. """ import sys diff --git a/tests/test_application.py b/tests/test_application.py index e00e990f6..6425e2753 100644 --- a/tests/test_application.py +++ b/tests/test_application.py @@ -5,8 +5,8 @@ Test the Sphinx class. - :copyright: 2008 by Benjamin Peterson. - :license: BSD. + :copyright: Copyright 2007-2009 by the Sphinx team, see AUTHORS. + :license: BSD, see LICENSE for details. """ from StringIO import StringIO diff --git a/tests/test_autodoc.py b/tests/test_autodoc.py index f3920ff04..a9e030fef 100644 --- a/tests/test_autodoc.py +++ b/tests/test_autodoc.py @@ -3,27 +3,29 @@ test_autodoc ~~~~~~~~~~~~ - Test the autodoc extension. This tests mainly the RstGenerator; the auto + Test the autodoc extension. This tests mainly the Documenters; the auto directives are tested in a test source file translated by test_build. - :copyright: 2008 by Georg Brandl. - :license: BSD. + :copyright: Copyright 2007-2009 by the Sphinx team, see AUTHORS. + :license: BSD, see LICENSE for details. """ from util import * from docutils.statemachine import ViewList -from sphinx.ext.autodoc import RstGenerator, cut_lines, between +from sphinx.ext.autodoc import AutoDirective, Documenter, add_documenter, \ + ModuleLevelDocumenter, FunctionDocumenter, cut_lines, between, ALL def setup_module(): - global app, lid, options, gen + global app, lid, options, directive app = TestApp() app.builder.env.app = app app.connect('autodoc-process-docstring', process_docstring) app.connect('autodoc-process-signature', process_signature) + app.connect('autodoc-skip-member', skip_member) options = Struct( inherited_members = False, @@ -33,27 +35,26 @@ def setup_module(): synopsis = '', platform = '', deprecated = False, + members = [], + member_order = 'alphabetic', ) - gen = TestGenerator(options, app) + directive = Struct( + env = app.builder.env, + genopt = options, + result = ViewList(), + warn = warnfunc, + filename_set = set(), + ) def teardown_module(): app.cleanup() -class TestGenerator(RstGenerator): - """Generator that handles warnings without a reporter.""" +_warnings = [] - def __init__(self, options, app): - self.options = options - self.env = app.builder.env - self.lineno = 42 - self.filename_set = set() - self.warnings = [] - self.result = ViewList() - - def warn(self, msg): - self.warnings.append(msg) +def warnfunc(msg): + _warnings.append(msg) processed_docstrings = [] @@ -71,62 +72,73 @@ def process_signature(app, what, name, obj, options, args, retann): return '42', None -def test_resolve_name(): - # for modules - assert gen.resolve_name('module', 'test_autodoc') == \ - ('test_autodoc', 'test_autodoc', [], None, None) - assert gen.resolve_name('module', 'test.test_autodoc') == \ - ('test.test_autodoc', 'test.test_autodoc', [], None, None) +def skip_member(app, what, name, obj, skip, options): + if name.startswith('_'): + return True + if name == 'skipmeth': + return True - assert gen.resolve_name('module', 'test(arg)') == \ - ('test', 'test', [], None, None) - assert 'ignoring signature arguments' in gen.warnings[0] - del gen.warnings[:] + +def test_parse_name(): + def verify(objtype, name, result): + inst = AutoDirective._registry[objtype](directive, name) + assert inst.parse_name() + assert (inst.modname, inst.objpath, inst.args, inst.retann) == result + + # for modules + verify('module', 'test_autodoc', ('test_autodoc', [], None, None)) + verify('module', 'test.test_autodoc', ('test.test_autodoc', [], None, None)) + verify('module', 'test(arg)', ('test', [], 'arg', None)) + assert 'signature arguments' in _warnings[0] + del _warnings[:] # for functions/classes - assert gen.resolve_name('function', 'util.raises') == \ - ('util.raises', 'util', ['raises'], None, None) - assert gen.resolve_name('function', 'util.raises(exc) -> None') == \ - ('util.raises', 'util', ['raises'], 'exc', ' -> None') - gen.env.autodoc_current_module = 'util' - assert gen.resolve_name('function', 'raises') == \ - ('raises', 'util', ['raises'], None, None) - gen.env.autodoc_current_module = None - gen.env.currmodule = 'util' - assert gen.resolve_name('function', 'raises') == \ - ('raises', 'util', ['raises'], None, None) - assert gen.resolve_name('class', 'TestApp') == \ - ('TestApp', 'util', ['TestApp'], None, None) + verify('function', 'util.raises', ('util', ['raises'], None, None)) + verify('function', 'util.raises(exc) -> None', + ('util', ['raises'], 'exc', 'None')) + directive.env.autodoc_current_module = 'util' + verify('function', 'raises', ('util', ['raises'], None, None)) + directive.env.autodoc_current_module = None + directive.env.currmodule = 'util' + verify('function', 'raises', ('util', ['raises'], None, None)) + verify('class', 'TestApp', ('util', ['TestApp'], None, None)) # for members - gen.env.currmodule = 'foo' - assert gen.resolve_name('method', 'util.TestApp.cleanup') == \ - ('util.TestApp.cleanup', 'util', ['TestApp', 'cleanup'], None, None) - gen.env.currmodule = 'util' - gen.env.currclass = 'Foo' - gen.env.autodoc_current_class = 'TestApp' - assert gen.resolve_name('method', 'cleanup') == \ - ('cleanup', 'util', ['TestApp', 'cleanup'], None, None) - assert gen.resolve_name('method', 'TestApp.cleanup') == \ - ('TestApp.cleanup', 'util', ['TestApp', 'cleanup'], None, None) + directive.env.currmodule = 'foo' + verify('method', 'util.TestApp.cleanup', + ('util', ['TestApp', 'cleanup'], None, None)) + directive.env.currmodule = 'util' + directive.env.currclass = 'Foo' + directive.env.autodoc_current_class = 'TestApp' + verify('method', 'cleanup', ('util', ['TestApp', 'cleanup'], None, None)) + verify('method', 'TestApp.cleanup', + ('util', ['TestApp', 'cleanup'], None, None)) # and clean up - gen.env.currmodule = None - gen.env.currclass = None - gen.env.autodoc_current_class = None + directive.env.currmodule = None + directive.env.currclass = None + directive.env.autodoc_current_class = None def test_format_signature(): + def formatsig(objtype, name, obj, args, retann): + inst = AutoDirective._registry[objtype](directive, name) + inst.fullname = name + inst.doc_as_attr = False # for class objtype + inst.object = obj + inst.args = args + inst.retann = retann + return inst.format_signature() + # no signatures for modules - assert gen.format_signature('module', 'test', None, None, None) == '' + assert formatsig('module', 'test', None, None, None) == '' # test for functions def f(a, b, c=1, **d): pass - assert gen.format_signature('function', 'f', f, None, None) == '(a, b, c=1, **d)' - assert gen.format_signature('function', 'f', f, 'a, b, c, d', None) == \ - '(a, b, c, d)' - assert gen.format_signature('function', 'f', f, None, ' -> None') == \ + assert formatsig('function', 'f', f, None, None) == '(a, b, c=1, **d)' + assert formatsig('function', 'f', f, 'a, b, c, d', None) == '(a, b, c, d)' + assert formatsig('function', 'f', f, None, 'None') == \ '(a, b, c=1, **d) -> None' # test for classes @@ -136,15 +148,15 @@ def test_format_signature(): pass # no signature for classes without __init__ for C in (D, E): - assert gen.format_signature('class', 'D', C, None, None) == '' + assert formatsig('class', 'D', C, None, None) == '' class F: def __init__(self, a, b=None): pass class G(F, object): pass for C in (F, G): - assert gen.format_signature('class', 'C', C, None, None) == '(a, b=None)' - assert gen.format_signature('class', 'C', D, 'a, b', ' -> X') == '(a, b) -> X' + assert formatsig('class', 'C', C, None, None) == '(a, b=None)' + assert formatsig('class', 'C', D, 'a, b', 'X') == '(a, b) -> X' # test for methods class H: @@ -152,26 +164,29 @@ def test_format_signature(): pass def foo2(b, *c): pass - assert gen.format_signature('method', 'H.foo', H.foo1, None, None) == '(b, *c)' - assert gen.format_signature('method', 'H.foo', H.foo1, 'a', None) == '(a)' - assert gen.format_signature('method', 'H.foo', H.foo2, None, None) == '(b, *c)' + assert formatsig('method', 'H.foo', H.foo1, None, None) == '(b, *c)' + assert formatsig('method', 'H.foo', H.foo1, 'a', None) == '(a)' + assert formatsig('method', 'H.foo', H.foo2, None, None) == '(b, *c)' # test exception handling - raises(RuntimeError, gen.format_signature, 'function', 'int', int, None, None) + raises(TypeError, formatsig, 'function', 'int', int, None, None) # test processing by event handler - assert gen.format_signature('method', 'bar', H.foo1, None, None) == '42' + assert formatsig('method', 'bar', H.foo1, None, None) == '42' def test_get_doc(): - def getdocl(*args): - # strip the empty line at the end - return list(gen.get_doc(*args))[:-1] + def getdocl(objtype, obj, encoding=None): + inst = AutoDirective._registry[objtype](directive, 'tmp') + inst.object = obj + ds = inst.get_doc(encoding) + # for testing purposes, concat them and strip the empty line at the end + return sum(ds, [])[:-1] # objects without docstring def f(): pass - assert getdocl('function', 'f', f) == [] + assert getdocl('function', f) == [] # standard function, diverse docstring styles... def f(): @@ -181,7 +196,7 @@ def test_get_doc(): Docstring """ for func in (f, g): - assert getdocl('function', 'f', func) == ['Docstring'] + assert getdocl('function', func) == ['Docstring'] # first line vs. other lines indentation def f(): @@ -190,47 +205,67 @@ def test_get_doc(): Other lines """ - assert getdocl('function', 'f', f) == ['First line', '', 'Other', ' lines'] + assert getdocl('function', f) == ['First line', '', 'Other', ' lines'] # charset guessing (this module is encoded in utf-8) def f(): """Döcstring""" - assert getdocl('function', 'f', f) == [u'Döcstring'] + assert getdocl('function', f) == [u'Döcstring'] # already-unicode docstrings must be taken literally def f(): u"""Döcstring""" - assert getdocl('function', 'f', f) == [u'Döcstring'] + assert getdocl('function', f) == [u'Döcstring'] # class docstring: depends on config value which one is taken class C: """Class docstring""" def __init__(self): """Init docstring""" - gen.env.config.autoclass_content = 'class' - assert getdocl('class', 'C', C) == ['Class docstring'] - gen.env.config.autoclass_content = 'init' - assert getdocl('class', 'C', C) == ['Init docstring'] - gen.env.config.autoclass_content = 'both' - assert getdocl('class', 'C', C) == ['Class docstring', '', 'Init docstring'] + directive.env.config.autoclass_content = 'class' + assert getdocl('class', C) == ['Class docstring'] + directive.env.config.autoclass_content = 'init' + assert getdocl('class', C) == ['Init docstring'] + directive.env.config.autoclass_content = 'both' + assert getdocl('class', C) == ['Class docstring', '', 'Init docstring'] class D: + """Class docstring""" + def __init__(self): + """Init docstring + + Other + lines + """ + + # Indentation is normalized for 'both' + assert getdocl('class', D) == ['Class docstring', '', 'Init docstring', + '', 'Other', ' lines'] + + +def test_docstring_processing(): + def process(objtype, name, obj): + inst = AutoDirective._registry[objtype](directive, name) + inst.object = obj + inst.fullname = name + return list(inst.process_doc(inst.get_doc())) + + class E: def __init__(self): """Init docstring""" # docstring processing by event handler - assert getdocl('class', 'bar', D) == ['Init docstring', '', '42'] + assert process('class', 'bar', E) == ['Init docstring', '', '42', ''] - -def test_docstring_processing_functions(): - lid = app.connect('autodoc-process-docstring', cut_lines(1, 1, ['function'])) + lid = app.connect('autodoc-process-docstring', + cut_lines(1, 1, ['function'])) def f(): """ first line second line third line """ - assert list(gen.get_doc('function', 'f', f)) == ['second line', ''] + assert process('function', 'f', f) == ['second line', ''] app.disconnect(lid) lid = app.connect('autodoc-process-docstring', between('---', ['function'])) @@ -242,118 +277,172 @@ def test_docstring_processing_functions(): --- third line """ - assert list(gen.get_doc('function', 'f', f)) == ['second line', ''] + assert process('function', 'f', f) == ['second line', ''] app.disconnect(lid) +def test_new_documenter(): + class MyDocumenter(ModuleLevelDocumenter): + objtype = 'integer' + directivetype = 'data' + priority = 100 + + @classmethod + def can_document_member(cls, member, membername, isattr, parent): + return isinstance(member, int) + + def document_members(self, all_members=False): + return + + add_documenter(MyDocumenter) + + def assert_result_contains(item, objtype, name, **kw): + inst = AutoDirective._registry[objtype](directive, name) + inst.generate(**kw) + #print '\n'.join(directive.result) + assert len(_warnings) == 0, _warnings + assert item in directive.result + del directive.result[:] + + options.members = ['integer'] + assert_result_contains('.. data:: integer', 'module', 'test_autodoc') + + def test_generate(): - def assert_warns(warn_str, *args): - gen.generate(*args) - assert len(gen.result) == 0, gen.result - assert len(gen.warnings) == 1, gen.warnings - assert warn_str in gen.warnings[0], gen.warnings - del gen.warnings[:] + def assert_warns(warn_str, objtype, name, **kw): + inst = AutoDirective._registry[objtype](directive, name) + inst.generate(**kw) + assert len(directive.result) == 0, directive.result + assert len(_warnings) == 1, _warnings + assert warn_str in _warnings[0], _warnings + del _warnings[:] - def assert_works(*args): - gen.generate(*args) - assert gen.result - assert len(gen.warnings) == 0, gen.warnings - del gen.result[:] + def assert_works(objtype, name, **kw): + inst = AutoDirective._registry[objtype](directive, name) + inst.generate(**kw) + assert directive.result + assert len(_warnings) == 0, _warnings + del directive.result[:] - def assert_processes(items, *args): + def assert_processes(items, objtype, name, **kw): del processed_docstrings[:] del processed_signatures[:] - assert_works(*args) - assert set(processed_docstrings) | set(processed_signatures) == set(items) + assert_works(objtype, name, **kw) + assert set(processed_docstrings) | set(processed_signatures) == \ + set(items) - def assert_result_contains(item, *args): - gen.generate(*args) - print '\n'.join(gen.result) - assert len(gen.warnings) == 0, gen.warnings - assert item in gen.result - del gen.result[:] + def assert_result_contains(item, objtype, name, **kw): + inst = AutoDirective._registry[objtype](directive, name) + inst.generate(**kw) + #print '\n'.join(directive.result) + assert len(_warnings) == 0, _warnings + assert item in directive.result + del directive.result[:] + + options.members = [] # no module found? assert_warns("import for autodocumenting 'foobar'", - 'function', 'foobar', None, None) + 'function', 'foobar', more_content=None) # importing assert_warns("import/find module 'test_foobar'", - 'module', 'test_foobar', None, None) + 'module', 'test_foobar', more_content=None) # attributes missing assert_warns("import/find function 'util.foobar'", - 'function', 'util.foobar', None, None) + 'function', 'util.foobar', more_content=None) # test auto and given content mixing - gen.env.currmodule = 'test_autodoc' - assert_result_contains(' Function.', 'method', 'Class.meth', [], None) + directive.env.currmodule = 'test_autodoc' + assert_result_contains(' Function.', 'method', 'Class.meth') add_content = ViewList() add_content.append('Content.', '', 0) - assert_result_contains(' Function.', 'method', 'Class.meth', [], add_content) - assert_result_contains(' Content.', 'method', 'Class.meth', [], add_content) + assert_result_contains(' Function.', 'method', + 'Class.meth', more_content=add_content) + assert_result_contains(' Content.', 'method', + 'Class.meth', more_content=add_content) # test check_module - gen.generate('function', 'raises', None, None, check_module=True) - assert len(gen.result) == 0 + inst = FunctionDocumenter(directive, 'raises') + inst.generate(check_module=True) + assert len(directive.result) == 0 # assert that exceptions can be documented - assert_works('exception', 'test_autodoc.CustomEx', ['__all__'], None) - assert_works('exception', 'test_autodoc.CustomEx', [], None) + assert_works('exception', 'test_autodoc.CustomEx', all_members=True) + assert_works('exception', 'test_autodoc.CustomEx') # test diverse inclusion settings for members - should = [('class', 'Class')] - assert_processes(should, 'class', 'Class', [], None) - should.extend([('method', 'Class.meth')]) - assert_processes(should, 'class', 'Class', ['meth'], None) - should.extend([('attribute', 'Class.prop')]) - assert_processes(should, 'class', 'Class', ['__all__'], None) + should = [('class', 'test_autodoc.Class')] + assert_processes(should, 'class', 'Class') + should.extend([('method', 'test_autodoc.Class.meth')]) + options.members = ['meth'] + assert_processes(should, 'class', 'Class') + should.extend([('attribute', 'test_autodoc.Class.prop'), + ('attribute', 'test_autodoc.Class.attr'), + ('attribute', 'test_autodoc.Class.docattr'), + ('attribute', 'test_autodoc.Class.udocattr')]) + options.members = ALL + assert_processes(should, 'class', 'Class') options.undoc_members = True - should.append(('method', 'Class.undocmeth')) - assert_processes(should, 'class', 'Class', ['__all__'], None) + should.append(('method', 'test_autodoc.Class.undocmeth')) + assert_processes(should, 'class', 'Class') options.inherited_members = True - should.append(('method', 'Class.inheritedmeth')) - assert_processes(should, 'class', 'Class', ['__all__'], None) + should.append(('method', 'test_autodoc.Class.inheritedmeth')) + assert_processes(should, 'class', 'Class') + options.members = [] # test module flags - assert_result_contains('.. module:: test_autodoc', 'module', - 'test_autodoc', [], None) + assert_result_contains('.. module:: test_autodoc', 'module', 'test_autodoc') options.synopsis = 'Synopsis' - assert_result_contains(' :synopsis: Synopsis', 'module', 'test_autodoc', [], None) + assert_result_contains(' :synopsis: Synopsis', 'module', 'test_autodoc') options.deprecated = True - assert_result_contains(' :deprecated:', 'module', 'test_autodoc', [], None) + assert_result_contains(' :deprecated:', 'module', 'test_autodoc') options.platform = 'Platform' - assert_result_contains(' :platform: Platform', 'module', 'test_autodoc', [], None) + assert_result_contains(' :platform: Platform', 'module', 'test_autodoc') # test if __all__ is respected for modules - assert_result_contains('.. class:: Class', 'module', 'test_autodoc', - ['__all__'], None) + options.members = ALL + assert_result_contains('.. class:: Class', 'module', 'test_autodoc') try: - assert_result_contains('.. exception:: CustomEx', 'module', 'test_autodoc', - ['__all__'], None) + assert_result_contains('.. exception:: CustomEx', + 'module', 'test_autodoc') except AssertionError: pass else: assert False, 'documented CustomEx which is not in __all__' # test noindex flag + options.members = [] options.noindex = True - assert_result_contains(' :noindex:', 'module', 'test_autodoc', [], None) - assert_result_contains(' :noindex:', 'class', 'Base', [], None) + assert_result_contains(' :noindex:', 'module', 'test_autodoc') + assert_result_contains(' :noindex:', 'class', 'Base') # okay, now let's get serious about mixing Python and C signature stuff assert_result_contains('.. class:: CustomDict', 'class', 'CustomDict', - ['__all__'], None) + all_members=True) + + # test inner class handling + assert_processes([('class', 'test_autodoc.Outer'), + ('class', 'test_autodoc.Outer.Inner'), + ('method', 'test_autodoc.Outer.Inner.meth')], + 'class', 'Outer', all_members=True) + + # test generation for C modules (which have no source file) + directive.env.currmodule = 'time' + assert_processes([('function', 'time.asctime')], 'function', 'asctime') + assert_processes([('function', 'time.asctime')], 'function', 'asctime') # --- generate fodder ------------ __all__ = ['Class'] +integer = 1 + class CustomEx(Exception): """My custom exception.""" def f(self): """Exception method.""" - class Base(object): def inheritedmeth(self): """Inherited function.""" @@ -367,10 +456,26 @@ class Class(Base): def undocmeth(self): pass + def skipmeth(self): + """Method that should be skipped.""" + pass + + # should not be documented + skipattr = 'foo' + + #: should be documented -- süß + attr = 'bar' + @property def prop(self): """Property.""" + docattr = 'baz' + """should likewise be documented -- süß""" + + udocattr = 'quux' + u"""should be documented as well - süß""" + class CustomDict(dict): """Docstring.""" @@ -379,3 +484,16 @@ def function(foo, *args, **kwds): Return spam. """ pass + + +class Outer(object): + """Foo""" + + class Inner(object): + """Foo""" + + def meth(self): + """Foo""" + + # should be documented as an alias + factory = dict diff --git a/tests/test_build.py b/tests/test_build.py index 07a946964..f509a9f43 100644 --- a/tests/test_build.py +++ b/tests/test_build.py @@ -5,11 +5,13 @@ Test the entire build process with the test root. - :copyright: 2008 by Georg Brandl. - :license: BSD. + :copyright: Copyright 2007-2009 by the Sphinx team, see AUTHORS. + :license: BSD, see LICENSE for details. """ import os +import re +import sys import difflib import htmlentitydefs from StringIO import StringIO @@ -18,41 +20,70 @@ from subprocess import Popen, PIPE from util import * from etree13 import ElementTree as ET -from sphinx.builder import StandaloneHTMLBuilder, LaTeXBuilder -from sphinx.latexwriter import LaTeXTranslator +try: + import pygments +except ImportError: + pygments = None + +from sphinx.builders.html import StandaloneHTMLBuilder +from sphinx.builders.latex import LaTeXBuilder +from sphinx.writers.latex import LaTeXTranslator + + +def teardown_module(): + (test_root / '_build').rmtree() html_warnfile = StringIO() latex_warnfile = StringIO() ENV_WARNINGS = """\ -WARNING: %(root)s/images.txt:9: Image file not readable: foo.png -WARNING: %(root)s/images.txt:20: Nonlocal image URI found: http://www.python.org/logo.png -WARNING: %(root)s/includes.txt:: (WARNING/2) Encoding 'utf-8' used for reading included \ -file u'wrongenc.inc' seems to be wrong, try giving an :encoding: option +%(root)s/images.txt:9: WARNING: image file not readable: foo.png +%(root)s/images.txt:23: WARNING: nonlocal image URI found: \ +http://www.python.org/logo.png +%(root)s/includes.txt:: (WARNING/2) Encoding 'utf-8' used for reading \ +included file u'wrongenc.inc' seems to be wrong, try giving an :encoding: option +%(root)s/includes.txt:56: WARNING: download file not readable: nonexisting.png """ HTML_WARNINGS = ENV_WARNINGS + """\ -WARNING: %(root)s/images.txt:: no matching candidate for image URI u'foo.*' +%(root)s/images.txt:20: WARNING: no matching candidate for image URI u'foo.*' +%(root)s/markup.txt:: WARNING: invalid index entry u'' +%(root)s/markup.txt:: WARNING: invalid pair index entry u'' +%(root)s/markup.txt:: WARNING: invalid pair index entry u'keyword; ' """ LATEX_WARNINGS = ENV_WARNINGS + """\ -WARNING: None:: no matching candidate for image URI u'foo.*' +None:None: WARNING: no matching candidate for image URI u'foo.*' +WARNING: invalid pair index entry u'' """ HTML_XPATH = { 'images.html': { ".//img[@src='_images/img.png']": '', ".//img[@src='_images/img1.png']": '', + ".//img[@src='_images/simg.png']": '', + ".//object[@data='_images/svgimg.svg']": '', + ".//embed[@src='_images/svgimg.svg']": '', + }, + 'subdir/images.html': { + ".//img[@src='../_images/img1.png']": '', + ".//img[@src='../_images/rimg.png']": '', + }, + 'subdir/includes.html': { + ".//pre/span": 'line 1', + ".//pre/span": 'line 2', + ".//a[@href='../_downloads/img.png']": '', }, 'includes.html': { - ".//pre/span[@class='s']": u'üöä', ".//pre": u'Max Strauß', + ".//a[@href='_downloads/img.png']": '', + ".//a[@href='_downloads/img1.png']": '', }, 'autodoc.html': { ".//dt[@id='test_autodoc.Class']": '', - ".//dt[@id='test_autodoc.function']/em": '**kwds', - ".//dd": 'Return spam.', + ".//dt[@id='test_autodoc.function']/em": r'\*\*kwds', + ".//dd": r'Return spam\.', }, 'markup.html': { ".//meta[@name='author'][@content='Me']": '', @@ -60,18 +91,47 @@ HTML_XPATH = { ".//a[@href='contents.html#ref1']": '', ".//div[@id='label']": '', ".//span[@class='option']": '--help', + ".//p": 'A global substitution.', + ".//p": 'In HTML.', + ".//p": 'In both.', + ".//p": 'Always present', }, 'desc.html': { ".//dt[@id='mod.Cls.meth1']": '', ".//dt[@id='errmod.Error']": '', ".//a[@href='#mod.Cls']": '', + ".//dl[@class='userdesc']": '', + ".//dt[@id='userdescrole-myobj']": '', + ".//a[@href='#userdescrole-myobj']": '', }, 'contents.html': { ".//meta[@name='hc'][@content='hcval']": '', - ".//td[@class='label']": '[Ref1]', + ".//meta[@name='testopt'][@content='testoverride']": '', + ".//td[@class='label']": r'\[Ref1\]', + ".//li[@class='toctree-l1']/a": 'Testing various markup', + ".//li[@class='toctree-l2']/a": 'Admonitions', + ".//title": 'Sphinx ', + ".//div[@class='footer']": 'Georg Brandl & Team', + ".//a[@href='http://python.org/']": '', + }, + '_static/statictmpl.html': { + ".//project": 'Sphinx ', }, } +if pygments: + HTML_XPATH['includes.html'].update({ + ".//pre/span[@class='s']": u'üöä', + ".//div[@class='inc-pyobj1 highlight-text']/div/pre": + r'^class Foo:\n pass\n\s*$', + ".//div[@class='inc-pyobj2 highlight-text']/div/pre": + r'^ def baz\(\):\n pass\n\s*$', + ".//div[@class='inc-lines highlight-text']/div/pre": + r'^class Foo:\n pass\nclass Bar:\n$', + ".//div[@class='inc-startend highlight-text']/div/pre": + ur'^foo = u"Including Unicode characters: üöä"\n$', + }) + class NslessParser(ET.XMLParser): """XMLParser that throws away namespaces in tag names.""" @@ -87,7 +147,26 @@ class NslessParser(ET.XMLParser): return name -@with_app(buildername='html', warning=html_warnfile) +def check_xpath(etree, fname, path, check): + nodes = list(etree.findall(path)) + assert nodes != [], ('did not find any node matching xpath ' + '%r in file %s' % (path, fname)) + if hasattr(check, '__call__'): + check(nodes) + elif not check: + # only check for node presence + pass + else: + rex = re.compile(check) + for node in nodes: + if node.text and rex.search(node.text): + break + else: + assert False, ('%r not found in any node matching ' + 'path %s in %s: %r' % (check, path, fname, + [node.text for node in nodes])) + +@gen_with_app(buildername='html', warning=html_warnfile, tags=['testtag']) def test_html(app): app.builder.build_all() html_warnings = html_warnfile.getvalue().replace(os.sep, '/') @@ -100,18 +179,8 @@ def test_html(app): parser = NslessParser() parser.entity.update(htmlentitydefs.entitydefs) etree = ET.parse(os.path.join(app.outdir, fname), parser) - for path, text in paths.iteritems(): - nodes = list(etree.findall(path)) - assert nodes != [] - if not text: - # only check for node presence - continue - for node in nodes: - if node.text and text in node.text: - break - else: - assert False, ('%r not found in any node matching ' - 'path %s in %s' % (text, path, fname)) + for path, check in paths.iteritems(): + yield check_xpath, etree, fname, path, check @with_app(buildername='latex', warning=latex_warnfile) @@ -123,14 +192,45 @@ def test_latex(app): assert latex_warnings == latex_warnings_exp, 'Warnings don\'t match:\n' + \ '\n'.join(difflib.ndiff(latex_warnings_exp.splitlines(), latex_warnings.splitlines())) + # file from latex_additional_files + assert (app.outdir / 'svgimg.svg').isfile() + + # only run latex if all needed packages are there + def kpsetest(filename): + try: + p = Popen(['kpsewhich', filename], stdout=PIPE) + except OSError, err: + # no kpsewhich... either no tex distribution is installed or it is + # a "strange" one -- don't bother running latex + return None + else: + p.communicate() + if p.returncode != 0: + # not found + return False + # found + return True + + if kpsetest('article.sty') is None: + print >>sys.stderr, \ + 'info: not running latex, it doesn\'t seem to be installed' + return + for filename in ['fancyhdr.sty', 'fancybox.sty', 'titlesec.sty', + 'amsmath.sty', 'framed.sty', 'color.sty', 'fancyvrb.sty', + 'threeparttable.sty']: + if not kpsetest(filename): + print >>sys.stderr, \ + 'info: not running latex, the %s package doesn\'t ' \ + 'seem to be installed' % filename + return # now, try to run latex over it cwd = os.getcwd() os.chdir(app.outdir) try: try: - p = Popen(['pdflatex', '--interaction=nonstopmode', 'SphinxTests.tex'], - stdout=PIPE, stderr=PIPE) + p = Popen(['pdflatex', '--interaction=nonstopmode', + 'SphinxTests.tex'], stdout=PIPE, stderr=PIPE) except OSError, err: pass # most likely pdflatex was not found else: @@ -144,6 +244,10 @@ def test_latex(app): # just let the remaining ones run for now +@with_app(buildername='pickle') +def test_pickle(app): + app.builder.build_all() + @with_app(buildername='linkcheck') def test_linkcheck(app): app.builder.build_all() @@ -152,6 +256,14 @@ def test_linkcheck(app): def test_text(app): app.builder.build_all() -@with_app(buildername='changes', cleanenv=True) +@with_app(buildername='htmlhelp') +def test_htmlhelp(app): + app.builder.build_all() + +@with_app(buildername='qthelp') +def test_qthelp(app): + app.builder.build_all() + +@with_app(buildername='changes') def test_changes(app): app.builder.build_all() diff --git a/tests/test_config.py b/tests/test_config.py index 3b9ea6920..b3aa4eeaa 100644 --- a/tests/test_config.py +++ b/tests/test_config.py @@ -6,8 +6,8 @@ Test the sphinx.config.Config class and its handling in the Application class. - :copyright: 2008 by Georg Brandl. - :license: BSD. + :copyright: Copyright 2007-2009 by the Sphinx team, see AUTHORS. + :license: BSD, see LICENSE for details. """ from util import * @@ -15,17 +15,19 @@ from util import * from sphinx.application import ExtensionError -@with_app(confoverrides={'master_doc': 'master', 'nonexisting_value': 'True'}) +@with_app(confoverrides={'master_doc': 'master', 'nonexisting_value': 'True', + 'latex_elements.docclass': 'scrartcl'}) def test_core_config(app): cfg = app.config # simple values assert 'project' in cfg.__dict__ - assert cfg.project == 'Sphinx Tests' + assert cfg.project == 'Sphinx ' assert cfg.templates_path == ['_templates'] # overrides assert cfg.master_doc == 'master' + assert cfg.latex_elements['docclass'] == 'scrartcl' # simple default values assert 'exclude_dirs' not in cfg.__dict__ @@ -34,7 +36,7 @@ def test_core_config(app): # complex default values assert 'html_title' not in cfg.__dict__ - assert cfg.html_title == 'Sphinx Tests v0.4alpha1 documentation' + assert cfg.html_title == 'Sphinx v0.6alpha1 documentation' # complex default values mustn't raise for valuename in cfg.config_values: diff --git a/tests/test_coverage.py b/tests/test_coverage.py index 82279f50d..369788a19 100644 --- a/tests/test_coverage.py +++ b/tests/test_coverage.py @@ -5,8 +5,8 @@ Test the coverage builder. - :copyright: 2008 by Georg Brandl. - :license: BSD. + :copyright: Copyright 2007-2009 by the Sphinx team, see AUTHORS. + :license: BSD, see LICENSE for details. """ import pickle diff --git a/tests/test_env.py b/tests/test_env.py index 528edc48f..0b944c509 100644 --- a/tests/test_env.py +++ b/tests/test_env.py @@ -5,14 +5,15 @@ Test the BuildEnvironment class. - :copyright: 2008 by Georg Brandl. - :license: BSD. + :copyright: Copyright 2007-2009 by the Sphinx team, see AUTHORS. + :license: BSD, see LICENSE for details. """ from util import * from sphinx.environment import BuildEnvironment -from sphinx.builder import StandaloneHTMLBuilder, LaTeXBuilder +from sphinx.builders.html import StandaloneHTMLBuilder +from sphinx.builders.latex import LaTeXBuilder app = env = None warnings = [] @@ -21,14 +22,14 @@ def setup_module(): global app, env app = TestApp(srcdir='(temp)') env = BuildEnvironment(app.srcdir, app.doctreedir, app.config) - env.set_warnfunc(warnings.append) + env.set_warnfunc(lambda *args: warnings.append(args)) def teardown_module(): app.cleanup() def warning_emitted(file, text): for warning in warnings: - if file+':' in warning and text in warning: + if len(warning) == 2 and file+':' in warning[1] and text in warning[0]: return True return False @@ -45,41 +46,52 @@ def test_first_update(): assert docnames == env.found_docs == set(env.all_docs) def test_images(): - assert warning_emitted('images.txt', 'Image file not readable: foo.png') - assert warning_emitted('images.txt', 'Nonlocal image URI found: ' + assert warning_emitted('images.txt', 'image file not readable: foo.png') + assert warning_emitted('images.txt', 'nonlocal image URI found: ' 'http://www.python.org/logo.png') tree = env.get_doctree('images') app._warning.reset() htmlbuilder = StandaloneHTMLBuilder(app, env) htmlbuilder.post_process_images(tree) - assert "no matching candidate for image URI u'foo.*'" in app._warning.content[-1] - assert set(htmlbuilder.images.keys()) == set(['subdir/img.png', 'img.png']) - assert set(htmlbuilder.images.values()) == set(['img.png', 'img1.png']) + assert "no matching candidate for image URI u'foo.*'" in \ + app._warning.content[-1] + assert set(htmlbuilder.images.keys()) == \ + set(['subdir/img.png', 'img.png', 'subdir/simg.png', 'svgimg.svg']) + assert set(htmlbuilder.images.values()) == \ + set(['img.png', 'img1.png', 'simg.png', 'svgimg.svg']) app._warning.reset() latexbuilder = LaTeXBuilder(app, env) latexbuilder.post_process_images(tree) - assert "no matching candidate for image URI u'foo.*'" in app._warning.content[-1] - assert set(latexbuilder.images.keys()) == set(['subdir/img.png', - 'img.png', 'img.pdf']) - assert set(latexbuilder.images.values()) == set(['img.pdf', 'img.png', 'img1.png']) + assert "no matching candidate for image URI u'foo.*'" in \ + app._warning.content[-1] + assert set(latexbuilder.images.keys()) == \ + set(['subdir/img.png', 'subdir/simg.png', 'img.png', 'img.pdf', + 'svgimg.pdf']) + assert set(latexbuilder.images.values()) == \ + set(['img.pdf', 'img.png', 'img1.png', 'simg.png', 'svgimg.pdf']) def test_second_update(): # delete, add and "edit" (change saved mtime) some files and update again env.all_docs['contents'] = 0 root = path(app.srcdir) - (root / 'images.txt').unlink() + # important: using "autodoc" because it is the last one to be included in + # the contents.txt toctree; otherwise section numbers would shift + (root / 'autodoc.txt').unlink() (root / 'new.txt').write_text('New file\n========\n') it = env.update(app.config, app.srcdir, app.doctreedir, app) msg = it.next() - assert '1 added, 1 changed, 1 removed' in msg + assert '1 added, 3 changed, 1 removed' in msg docnames = set() for docname in it: docnames.add(docname) - assert docnames == set(['contents', 'new']) - assert 'images' not in env.all_docs - assert 'images' not in env.found_docs + # "includes" and "images" are in there because they contain references + # to nonexisting downloadable or image files, which are given another + # chance to exist + assert docnames == set(['contents', 'new', 'includes', 'images']) + assert 'autodoc' not in env.all_docs + assert 'autodoc' not in env.found_docs def test_object_inventory(): refs = env.descrefs diff --git a/tests/test_highlighting.py b/tests/test_highlighting.py new file mode 100644 index 000000000..ea1f25f14 --- /dev/null +++ b/tests/test_highlighting.py @@ -0,0 +1,75 @@ +# -*- coding: utf-8 -*- +""" + test_highlighting + ~~~~~~~~~~~~~~~~~ + + Test the Pygments highlighting bridge. + + :copyright: Copyright 2007-2009 by the Sphinx team, see AUTHORS. + :license: BSD, see LICENSE for details. +""" + +from util import * + +try: + import pygments +except ImportError: + from nose.plugins.skip import SkipTest + raise SkipTest('pygments not available') + +from pygments.lexer import RegexLexer +from pygments.token import Text, Name +from pygments.formatters.html import HtmlFormatter + +from sphinx.highlighting import PygmentsBridge + + +class MyLexer(RegexLexer): + name = 'testlexer' + + tokens = { + 'root': [ + ('a', Name), + ('b', Text), + ], + } + + +class MyFormatter(HtmlFormatter): + def format(self, tokensource, outfile): + outfile.write('test') + + +class ComplainOnUnhighlighted(PygmentsBridge): + def unhighlighted(self, source): + raise AssertionError("should highlight %r" % source) + + +@with_app() +def test_add_lexer(app): + app.add_lexer('test', MyLexer()) + + bridge = PygmentsBridge('html') + ret = bridge.highlight_block('ab', 'test') + assert 'ab' in ret + +def test_detect_interactive(): + bridge = ComplainOnUnhighlighted('html') + blocks = [ + """ + >>> testing() + True + """, + ] + for block in blocks: + ret = bridge.highlight_block(block.lstrip(), 'python') + assert ret.startswith("
    ") + +def test_set_formatter(): + PygmentsBridge.html_formatter = MyFormatter + try: + bridge = PygmentsBridge('html') + ret = bridge.highlight_block('foo', 'python') + assert ret == 'test' + finally: + PygmentsBridge.html_formatter = HtmlFormatter diff --git a/tests/test_i18n.py b/tests/test_i18n.py index da0af246d..94648727e 100644 --- a/tests/test_i18n.py +++ b/tests/test_i18n.py @@ -5,8 +5,8 @@ Test locale features. - :copyright: 2008 by Georg Brandl. - :license: BSD. + :copyright: Copyright 2007-2009 by the Sphinx team, see AUTHORS. + :license: BSD, see LICENSE for details. """ from util import * diff --git a/tests/test_markup.py b/tests/test_markup.py index ffc6a0291..f0fbcf9e8 100644 --- a/tests/test_markup.py +++ b/tests/test_markup.py @@ -5,8 +5,8 @@ Test various Sphinx-specific markup extensions. - :copyright: 2008 by Georg Brandl. - :license: BSD. + :copyright: Copyright 2007-2009 by the Sphinx team, see AUTHORS. + :license: BSD, see LICENSE for details. """ import re @@ -17,13 +17,16 @@ from docutils import frontend, utils, nodes from docutils.parsers import rst from sphinx import addnodes -from sphinx.htmlwriter import HTMLWriter, SmartyPantsHTMLTranslator -from sphinx.latexwriter import LaTeXWriter, LaTeXTranslator +from sphinx.util import texescape +from sphinx.writers.html import HTMLWriter, SmartyPantsHTMLTranslator +from sphinx.writers.latex import LaTeXWriter, LaTeXTranslator def setup_module(): global app, settings, parser + texescape.init() # otherwise done by the latex builder app = TestApp(cleanenv=True) - optparser = frontend.OptionParser(components=(rst.Parser, HTMLWriter, LaTeXWriter)) + optparser = frontend.OptionParser( + components=(rst.Parser, HTMLWriter, LaTeXWriter)) settings = optparser.get_default_values() settings.env = app.builder.env parser = rst.Parser() @@ -77,38 +80,39 @@ def test_inline(): # correct interpretation of code with whitespace _html = ('

    ' 'code   sample

    ') - verify('``code sample``', _html, '\\code{code sample}') - verify(':samp:`code sample`', _html, '\\samp{code sample}') + yield verify, '``code sample``', _html, '\\code{code sample}' + yield verify, ':samp:`code sample`', _html, '\\samp{code sample}' # interpolation of braces in samp and file roles (HTML only) - verify(':samp:`a{b}c`', + yield (verify, ':samp:`a{b}c`', '

    a' - 'bc

    ', + 'b' + 'c

    ', '\\samp{abc}') # interpolation of arrows in menuselection - verify(':menuselection:`a --> b`', + yield (verify, ':menuselection:`a --> b`', u'

    a \N{TRIANGULAR BULLET} b

    ', '\\emph{a \\(\\rightarrow\\) b}') # non-interpolation of dashes in option role - verify_re(':option:`--with-option`', - '

    --with-option

    $', - r'\\emph{\\texttt{--with-option}}$') + yield (verify_re, ':option:`--with-option`', + '

    --with-option

    $', + r'\\emph{\\texttt{-{-}with-option}}$') # verify smarty-pants quotes - verify('"John"', '

    “John”

    ', "``John''") + yield verify, '"John"', '

    “John”

    ', "``John''" # ... but not in literal text - verify('``"John"``', + yield (verify, '``"John"``', '

    ' '"John"

    ', '\\code{"John"}') def test_latex_escaping(): # correct escaping in normal mode - verify(u'Γ\\\\∞$', None, ur'\(\Gamma\)\textbackslash{}\(\infty\)\$') + yield verify, u'Γ\\\\∞$', None, ur'\(\Gamma\)\textbackslash{}\(\infty\)\$' # in verbatim code fragments - verify(u'::\n\n @Γ\\∞$[]', None, + yield (verify, u'::\n\n @Γ\\∞$[]', None, u'\\begin{Verbatim}[commandchars=@\\[\\]]\n' u'@PYGZat[]@(@Gamma@)\\@(@infty@)@$@PYGZlb[]@PYGZrb[]\n' u'\\end{Verbatim}') diff --git a/tests/test_quickstart.py b/tests/test_quickstart.py index a76a1cdfd..ae001eb6b 100644 --- a/tests/test_quickstart.py +++ b/tests/test_quickstart.py @@ -5,8 +5,8 @@ Test the sphinx.quickstart module. - :copyright: 2008 by Georg Brandl. - :license: BSD. + :copyright: Copyright 2007-2009 by the Sphinx team, see AUTHORS. + :license: BSD, see LICENSE for details. """ import sys @@ -70,6 +70,7 @@ def test_do_prompt(): assert d['k5'] == 'no' raises(AssertionError, qs.do_prompt, d, 'k6', 'Q6', validator=qs.boolean) + @with_tempdir def test_quickstart_defaults(tempdir): answers = { @@ -86,29 +87,31 @@ def test_quickstart_defaults(tempdir): ns = {} execfile(conffile, ns) assert ns['extensions'] == [] - assert ns['templates_path'] == ['.templates'] + assert ns['templates_path'] == ['_templates'] assert ns['source_suffix'] == '.rst' assert ns['master_doc'] == 'index' assert ns['project'] == 'Sphinx Test' assert ns['copyright'] == '%s, Georg Brandl' % time.strftime('%Y') assert ns['version'] == '0.1' assert ns['release'] == '0.1' - assert ns['html_static_path'] == ['.static'] + assert ns['html_static_path'] == ['_static'] assert ns['latex_documents'] == [ ('index', 'SphinxTest.tex', 'Sphinx Test Documentation', 'Georg Brandl', 'manual')] - assert (tempdir / '.static').isdir() - assert (tempdir / '.templates').isdir() + assert (tempdir / '_static').isdir() + assert (tempdir / '_templates').isdir() assert (tempdir / 'index.rst').isfile() assert (tempdir / 'Makefile').isfile() + assert (tempdir / 'make.bat').isfile() + @with_tempdir def test_quickstart_all_answers(tempdir): answers = { 'Root path': tempdir, 'Separate source and build': 'y', - 'Name prefix for templates': '_', + 'Name prefix for templates': '.', 'Project name': 'STASI\xe2\x84\xa2', 'Author name': 'Wolfgang Sch\xc3\xa4uble & G. Beckstein', 'Project version': '2.0', @@ -118,7 +121,13 @@ def test_quickstart_all_answers(tempdir): 'autodoc': 'y', 'doctest': 'yes', 'intersphinx': 'no', + 'todo': 'n', + 'coverage': 'no', + 'pngmath': 'N', + 'jsmath': 'no', + 'ifconfig': 'no', 'Create Makefile': 'no', + 'Create Windows command file': 'no', } qs.raw_input = mock_raw_input(answers, needanswer=True) qs.TERM_ENCODING = 'utf-8' @@ -129,7 +138,7 @@ def test_quickstart_all_answers(tempdir): ns = {} execfile(conffile, ns) assert ns['extensions'] == ['sphinx.ext.autodoc', 'sphinx.ext.doctest'] - assert ns['templates_path'] == ['_templates'] + assert ns['templates_path'] == ['.templates'] assert ns['source_suffix'] == '.txt' assert ns['master_doc'] == 'contents' assert ns['project'] == u'STASI™' @@ -137,12 +146,12 @@ def test_quickstart_all_answers(tempdir): time.strftime('%Y') assert ns['version'] == '2.0' assert ns['release'] == '2.0.1' - assert ns['html_static_path'] == ['_static'] + assert ns['html_static_path'] == ['.static'] assert ns['latex_documents'] == [ ('contents', 'STASI.tex', u'STASI™ Documentation', ur'Wolfgang Schäuble \& G. Beckstein', 'manual')] assert (tempdir / 'build').isdir() - assert (tempdir / 'source' / '_static').isdir() - assert (tempdir / 'source' / '_templates').isdir() + assert (tempdir / 'source' / '.static').isdir() + assert (tempdir / 'source' / '.templates').isdir() assert (tempdir / 'source' / 'contents.txt').isfile() diff --git a/tests/test_theming.py b/tests/test_theming.py new file mode 100644 index 000000000..349a9ce4a --- /dev/null +++ b/tests/test_theming.py @@ -0,0 +1,56 @@ +# -*- coding: utf-8 -*- +""" + test_theming + ~~~~~~~~~~~~ + + Test the Theme class. + + :copyright: Copyright 2007-2009 by the Sphinx team, see AUTHORS. + :license: BSD, see LICENSE for details. +""" + +import os +import zipfile + +from util import * + +from sphinx.theming import Theme, ThemeError + + +@with_app(confoverrides={'html_theme': 'ziptheme', + 'html_theme_options.testopt': 'foo'}) +def test_theme_api(app): + cfg = app.config + + # test Theme class API + assert set(Theme.themes.keys()) == \ + set(['basic', 'default', 'sphinxdoc', 'traditional', + 'testtheme', 'ziptheme']) + assert Theme.themes['testtheme'][1] is None + assert isinstance(Theme.themes['ziptheme'][1], zipfile.ZipFile) + + # test Theme instance API + theme = app.builder.theme + assert theme.name == 'ziptheme' + assert theme.themedir_created + themedir = theme.themedir + assert theme.base.name == 'basic' + assert len(theme.get_dirchain()) == 2 + + # direct setting + assert theme.get_confstr('theme', 'stylesheet') == 'custom.css' + # inherited setting + assert theme.get_confstr('options', 'nosidebar') == 'false' + # nonexisting setting + assert theme.get_confstr('theme', 'foobar', 'def') == 'def' + raises(ThemeError, theme.get_confstr, 'theme', 'foobar') + + # options API + raises(ThemeError, theme.get_options, {'nonexisting': 'foo'}) + options = theme.get_options(cfg.html_theme_options) + assert options['testopt'] == 'foo' + assert options['nosidebar'] == 'false' + + # cleanup temp directories + theme.cleanup() + assert not os.path.exists(themedir) diff --git a/tests/util.py b/tests/util.py index fffdcce19..2c9d3176e 100644 --- a/tests/util.py +++ b/tests/util.py @@ -3,8 +3,8 @@ Sphinx test suite utilities ~~~~~~~~~~~~~~~~~~~~~~~~~~~ - :copyright: 2008 by Georg Brandl. - :license: BSD. + :copyright: Copyright 2007-2009 by the Sphinx team, see AUTHORS. + :license: BSD, see LICENSE for details. """ import sys @@ -13,9 +13,14 @@ import StringIO import tempfile import shutil -from functools import wraps +try: + from functools import wraps +except ImportError: + # functools is new in 2.4 + wraps = lambda f: (lambda w: w) -from sphinx import application, builder +from sphinx import application +from sphinx.ext.autodoc import AutoDirective from path import path @@ -25,7 +30,7 @@ from nose import tools __all__ = [ 'test_root', 'raises', 'raises_msg', 'Struct', - 'ListOutput', 'TestApp', 'with_app', + 'ListOutput', 'TestApp', 'with_app', 'gen_with_app', 'path', 'with_tempdir', 'write_file', 'sprint', ] @@ -93,8 +98,10 @@ class TestApp(application.Sphinx): """ def __init__(self, srcdir=None, confdir=None, outdir=None, doctreedir=None, - buildername='html', confoverrides=None, status=None, warning=None, - freshenv=None, confname='conf.py', cleanenv=False): + buildername='html', confoverrides=None, + status=None, warning=None, freshenv=None, + warningiserror=None, tags=None, + confname='conf.py', cleanenv=False): application.CONFIG_FILENAME = confname @@ -130,12 +137,15 @@ class TestApp(application.Sphinx): warning = ListOutput('stderr') if freshenv is None: freshenv = False + if warningiserror is None: + warningiserror = False application.Sphinx.__init__(self, srcdir, confdir, outdir, doctreedir, buildername, confoverrides, status, warning, - freshenv) + freshenv, warningiserror, tags) def cleanup(self, doctrees=False): + AutoDirective._registry.clear() for tree in self.cleanup_trees: shutil.rmtree(tree, True) @@ -149,10 +159,26 @@ def with_app(*args, **kwargs): @wraps(func) def deco(*args2, **kwargs2): app = TestApp(*args, **kwargs) - try: - func(app, *args2, **kwargs2) - finally: - app.cleanup() + func(app, *args2, **kwargs2) + # don't execute cleanup if test failed + app.cleanup() + return deco + return generator + + +def gen_with_app(*args, **kwargs): + """ + Make a TestApp with args and kwargs, pass it to the test and clean up + properly. + """ + def generator(func): + @wraps(func) + def deco(*args2, **kwargs2): + app = TestApp(*args, **kwargs) + for item in func(app, *args2, **kwargs2): + yield item + # don't execute cleanup if test failed + app.cleanup() return deco return generator diff --git a/utils/check_sources.py b/utils/check_sources.py index 0f834fcab..7fe0cbb7d 100755 --- a/utils/check_sources.py +++ b/utils/check_sources.py @@ -7,8 +7,8 @@ Make sure each Python file has a correct file header including copyright and license information. - :copyright: 2006-2008 by Georg Brandl. - :license: GNU GPL, see LICENSE for more details. + :copyright: Copyright 2006-2009 by the Sphinx team, see AUTHORS. + :license: BSD, see LICENSE for details. """ import sys, os, re @@ -30,7 +30,8 @@ def checker(*suffixes, **kwds): name_mail_re = r'[\w ]+(<.*?>)?' -copyright_re = re.compile(r'^ :copyright: 200\d(-200\d)? by %s(, %s)*[,.]$' % +copyright_re = re.compile(r'^ :copyright: Copyright 200\d(-200\d)? ' + r'by %s(, %s)*[,.]$' % (name_mail_re, name_mail_re)) license_re = re.compile(r" :license: (.*?).\n") copyright_2_re = re.compile(r'^ %s(, %s)*[,.]$' % @@ -55,7 +56,7 @@ def check_syntax(fn, lines): def check_style_and_encoding(fn, lines): encoding = 'ascii' for lno, line in enumerate(lines): - if len(line) > 90: + if len(line) > 81: yield lno+1, "line too long" if lno < 2: co = coding_re.search(line) @@ -63,9 +64,9 @@ def check_style_and_encoding(fn, lines): encoding = co.group(1) if line.strip().startswith('#'): continue - m = not_ix_re.search(line) - if m: - yield lno+1, '"' + m.group() + '"' + #m = not_ix_re.search(line) + #if m: + # yield lno+1, '"' + m.group() + '"' if is_const_re.search(line): yield lno+1, 'using == None/True/False' try: @@ -141,7 +142,7 @@ def check_fileheader(fn, lines): yield 0, "no correct copyright info" -@checker('.py', '.html') +@checker('.py', '.html', '.rst') def check_whitespace_and_spelling(fn, lines): for lno, line in enumerate(lines): if "\t" in line: @@ -153,7 +154,7 @@ def check_whitespace_and_spelling(fn, lines): yield lno+1, '"%s" used' % word -bad_tags = ('', '', '', '', '' +bad_tags = ('', '', '' '
    ', '', '', ' not really)" or "") + print "reindented", file, \ + (dryrun and "(dry run => not really)" or "") if not dryrun: if not no_backup: bak = file + ".bak"