diff --git a/CHANGES b/CHANGES index a9bccfea2..e4b5a17ff 100644 --- a/CHANGES +++ b/CHANGES @@ -99,6 +99,21 @@ Bugs fixed * #1345: Fix two bugs with :confval:`nitpick_ignore`; now you don't have to remove the store environment for changes to have effect. +* #1072: In the JS search, fix issues searching for upper-cased words by + lowercasing words before stemming. + +* #1299: Make behavior of the :rst:dir:`math` directive more consistent and + avoid producing empty environments in LaTeX output. + +* #1308: Strip HTML tags from the content of "raw" nodes before feeding it + to the search indexer. + +* #1249: Fix duplicate LaTeX page numbering for manual documents. + +* #1292: In the linkchecker, retry HEAD requests when denied by HTTP 405. + Also make the redirect code apparent and tweak the output a bit to be + more obvious. + Documentation ------------- @@ -1126,4 +1141,4 @@ Previous versions The changelog for versions before 1.0 can be found in the file ``CHANGES.old`` in the source distribution or `at BitBucket -`__. +`__. diff --git a/EXAMPLES b/EXAMPLES index 2c78b1d4f..9ca4468a5 100644 --- a/EXAMPLES +++ b/EXAMPLES @@ -4,7 +4,7 @@ Projects using Sphinx This is an (incomplete) alphabetic list of projects that use Sphinx or are experimenting with using it for their documentation. If you like to be included, please mail to `the Google group -`_. +`_. I've grouped the list into sections to make it easier to find interesting examples. @@ -15,12 +15,12 @@ Documentation using the default theme * APSW: http://apidoc.apsw.googlecode.com/hg/index.html * ASE: https://wiki.fysik.dtu.dk/ase/ * boostmpi: http://documen.tician.de/boostmpi/ -* Calibre: http://calibre-ebook.com/user_manual/ +* Calibre: http://manual.calibre-ebook.com/ * CodePy: http://documen.tician.de/codepy/ * Cython: http://docs.cython.org/ * C\\C++ Python language binding project: http://language-binding.net/index.html * Cormoran: http://cormoran.nhopkg.org/docs/ -* Director: http://packages.python.org/director/ +* Director: http://pythonhosted.org/director/ * Dirigible: http://www.projectdirigible.com/documentation/ * Elemental: http://elemental.googlecode.com/hg/doc/build/html/index.html * F2py: http://f2py.sourceforge.net/docs/ diff --git a/doc/builders.rst b/doc/builders.rst index 1297a08e4..00f4e2231 100644 --- a/doc/builders.rst +++ b/doc/builders.rst @@ -64,13 +64,13 @@ The builder's "name" must be given to the **-b** command-line option of Its name is ``qthelp``. - .. _Qt help: http://doc.trolltech.com/4.6/qthelp-framework.html + .. _Qt help: http://qt-project.org/doc/qt-4.8/qthelp-framework.html .. module:: sphinx.builders.devhelp .. class:: DevhelpBuilder This builder produces the same output as the standalone HTML builder, but - also generates `GNOME Devhelp `__ + also generates `GNOME Devhelp `__ support file that allows the GNOME Devhelp reader to view them. Its name is ``devhelp``. @@ -110,8 +110,8 @@ The builder's "name" must be given to the **-b** command-line option of Note that a direct PDF builder using ReportLab is available in `rst2pdf `_ version 0.12 or greater. You need to add ``'rst2pdf.pdfbuilder'`` to your :confval:`extensions` to enable it, its name is -``pdf``. Refer to the `rst2pdf manual -`_ for details. +``pdf``. Refer to the `rst2pdf manual `_ +for details. .. module:: sphinx.builders.text .. class:: TextBuilder @@ -179,7 +179,7 @@ Note that a direct PDF builder using ReportLab is available in `rst2pdf globalcontext_filename = 'globalcontext.phpdump' searchindex_filename = 'searchindex.phpdump' - .. _PHP serialization: http://pypi.python.org/pypi/phpserialize + .. _PHP serialization: https://pypi.python.org/pypi/phpserialize .. attribute:: implementation diff --git a/doc/config.rst b/doc/config.rst index 78bca929b..181ef2a4a 100644 --- a/doc/config.rst +++ b/doc/config.rst @@ -40,6 +40,8 @@ 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. +.. _conf-tags: + * 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')`` diff --git a/doc/develop.rst b/doc/develop.rst index 95a615cbc..faece78d0 100644 --- a/doc/develop.rst +++ b/doc/develop.rst @@ -6,11 +6,11 @@ Sphinx development Sphinx is a maintained by a group of volunteers. We value every contribution! * The code can be found in a Mercurial repository, at - http://bitbucket.org/birkenfeld/sphinx/. + https://bitbucket.org/birkenfeld/sphinx/. * Issues and feature requests should be raised in the `tracker - `_. + `_. * The mailing list for development is at `Google Groups - `_. + `_. * There is also the #sphinx-doc IRC channel on `freenode `_. @@ -82,24 +82,24 @@ own extensions. .. _gnuplot: http://www.gnuplot.info/ .. _paver: http://www.blueskyonmars.com/projects/paver/ .. _Sword: http://www.crosswire.org/sword/ -.. _Lilypond: http://lilypond.org/web/ +.. _Lilypond: http://lilypond.org/ .. _sdedit: http://sdedit.sourceforge.net/ .. _Trac: http://trac.edgewall.org .. _TracLinks: http://trac.edgewall.org/wiki/TracLinks .. _OmegaT: http://www.omegat.org/ .. _PlantUML: http://plantuml.sourceforge.net/ .. _PyEnchant: http://www.rfk.id.au/software/pyenchant/ -.. _sadisplay: http://bitbucket.org/estin/sadisplay/wiki/Home -.. _blockdiag: http://blockdiag.com/ -.. _seqdiag: http://blockdiag.com/ -.. _actdiag: http://blockdiag.com/ -.. _nwdiag: http://blockdiag.com/ -.. _Google Chart: http://code.google.com/intl/ja/apis/chart/ -.. _Google Maps: http://maps.google.com/ +.. _sadisplay: https://bitbucket.org/estin/sadisplay/wiki/Home +.. _blockdiag: http://blockdiag.com/en/ +.. _seqdiag: http://blockdiag.com/en/ +.. _actdiag: http://blockdiag.com/en/ +.. _nwdiag: http://blockdiag.com/en/ +.. _Google Chart: https://developers.google.com/chart/ +.. _Google Maps: https://maps.google.com/ .. _hyphenator: http://code.google.com/p/hyphenator/ -.. _exceltable: http://packages.python.org/sphinxcontrib-exceltable/ +.. _exceltable: http://pythonhosted.org/sphinxcontrib-exceltable/ .. _YouTube: http://www.youtube.com/ -.. _ClearQuest: http://www-01.ibm.com/software/awdtools/clearquest/ +.. _ClearQuest: http://www-03.ibm.com/software/products/en/clearquest .. _Zope interfaces: http://docs.zope.org/zope.interface/README.html .. _slideshare: http://www.slideshare.net/ .. _TikZ/PGF LaTeX package: http://sourceforge.net/projects/pgf/ diff --git a/doc/devguide.rst b/doc/devguide.rst index 0e3563b81..b23acb1cb 100644 --- a/doc/devguide.rst +++ b/doc/devguide.rst @@ -23,7 +23,7 @@ sphinx-dev #sphinx-doc on irc.freenode.net IRC channel for development questions and user support. -.. _`BitBucket`: http://bitbucket.org +.. _`BitBucket`: https://bitbucket.org/ .. _`Mercurial`: http://mercurial.selenic.com/ @@ -43,7 +43,7 @@ Including or providing a link to the source files involved may help us fix the issue. If possible, try to create a minimal project that produces the error and post that instead. -.. _`issue tracker`: http://bitbucket.org/birkenfeld/sphinx/issues +.. _`issue tracker`: https://bitbucket.org/birkenfeld/sphinx/issues Contributing to Sphinx @@ -126,7 +126,7 @@ These are the basic steps needed to start developing on Sphinx. would close issue #42. - __ https://confluence.atlassian.com/display/BITBUCKET/Automatically+Resolving+Issues+when+Users+Push+Code + __ https://confluence.atlassian.com/display/BITBUCKET/Resolve+issues+automatically+when+users+push+code #. Push changes to your forked repository on BitBucket. :: @@ -190,7 +190,7 @@ identifier and put ``sphinx.po`` in there. Don't forget to update the possible values for :confval:`language` in ``doc/config.rst``. The Sphinx core messages can also be translated on `Transifex -`_. There exists a client tool named ``tx`` in the Python +`_. There exists a client tool named ``tx`` in the Python package "transifex_client", which can be used to pull translations in ``.po`` format from Transifex. To do this, go to ``sphinx/locale`` and then run ``tx pull -f -l LANG`` where LANG is an existing language identifier. It is diff --git a/doc/domains.rst b/doc/domains.rst index 57e7acf31..e8ecf3f05 100644 --- a/doc/domains.rst +++ b/doc/domains.rst @@ -828,17 +828,17 @@ Operation_, and Scala_. .. _sphinx-contrib: https://bitbucket.org/birkenfeld/sphinx-contrib/ -.. _Ada: http://pypi.python.org/pypi/sphinxcontrib-adadomain -.. _CoffeeScript: http://pypi.python.org/pypi/sphinxcontrib-coffee -.. _Common Lisp: http://pypi.python.org/pypi/sphinxcontrib-cldomain -.. _dqn: http://pypi.python.org/pypi/sphinxcontrib-dqndomain -.. _Erlang: http://pypi.python.org/pypi/sphinxcontrib-erlangdomain -.. _Go: http://pypi.python.org/pypi/sphinxcontrib-golangdomain -.. _HTTP: http://pypi.python.org/pypi/sphinxcontrib-httpdomain -.. _Jinja: http://pypi.python.org/pypi/sphinxcontrib-jinjadomain -.. _Lasso: http://pypi.python.org/pypi/sphinxcontrib-lassodomain -.. _MATLAB: http://pypi.python.org/pypi/sphinxcontrib-matlabdomain -.. _Operation: http://pypi.python.org/pypi/sphinxcontrib-operationdomain -.. _PHP: http://pypi.python.org/pypi/sphinxcontrib-phpdomain -.. _Ruby: http://bitbucket.org/birkenfeld/sphinx-contrib/src/default/rubydomain -.. _Scala: http://pypi.python.org/pypi/sphinxcontrib-scaladomain +.. _Ada: https://pypi.python.org/pypi/sphinxcontrib-adadomain +.. _CoffeeScript: https://pypi.python.org/pypi/sphinxcontrib-coffee +.. _Common Lisp: https://pypi.python.org/pypi/sphinxcontrib-cldomain +.. _dqn: https://pypi.python.org/pypi/sphinxcontrib-dqndomain +.. _Erlang: https://pypi.python.org/pypi/sphinxcontrib-erlangdomain +.. _Go: https://pypi.python.org/pypi/sphinxcontrib-golangdomain +.. _HTTP: https://pypi.python.org/pypi/sphinxcontrib-httpdomain +.. _Jinja: https://pypi.python.org/pypi/sphinxcontrib-jinjadomain +.. _Lasso: https://pypi.python.org/pypi/sphinxcontrib-lassodomain +.. _MATLAB: https://pypi.python.org/pypi/sphinxcontrib-matlabdomain +.. _Operation: https://pypi.python.org/pypi/sphinxcontrib-operationdomain +.. _PHP: https://pypi.python.org/pypi/sphinxcontrib-phpdomain +.. _Ruby: https://bitbucket.org/birkenfeld/sphinx-contrib/src/default/rubydomain +.. _Scala: https://pypi.python.org/pypi/sphinxcontrib-scaladomain diff --git a/doc/extensions.rst b/doc/extensions.rst index b2ac37918..334e50392 100644 --- a/doc/extensions.rst +++ b/doc/extensions.rst @@ -68,10 +68,10 @@ maintains a list of those. If you write an extension that you think others will find useful or you think should be included as a part of Sphinx, please write to the project mailing -list (`join here `_). +list (`join here `_). -.. _Wiki at BitBucket: https://www.bitbucket.org/birkenfeld/sphinx/wiki/Home -.. _Sphinx Contrib: https://www.bitbucket.org/birkenfeld/sphinx-contrib +.. _Wiki at BitBucket: https://bitbucket.org/birkenfeld/sphinx/wiki/Home +.. _Sphinx Contrib: https://bitbucket.org/birkenfeld/sphinx-contrib Where to put your own extensions? diff --git a/doc/faq.rst b/doc/faq.rst index ff74be1c8..7aa35d1f1 100644 --- a/doc/faq.rst +++ b/doc/faq.rst @@ -37,7 +37,7 @@ How do I... come through cleanly. ... create HTML slides from Sphinx documents? - See the "Hieroglyph" package at http://github.com/nyergler/hieroglyph. + See the "Hieroglyph" package at https://github.com/nyergler/hieroglyph. For many more extensions and other contributed stuff, see the sphinx-contrib_ repository. @@ -50,7 +50,7 @@ Using Sphinx with... -------------------- Read the Docs - http://readthedocs.org is a documentation hosting service based around Sphinx. + https://readthedocs.org is a documentation hosting service based around Sphinx. They will host sphinx documentation, along with supporting a number of other features including version support, PDF generation, and more. The `Getting Started `_ @@ -62,7 +62,7 @@ Epydoc Doxygen Michael Jones is developing a reST/Sphinx bridge to doxygen called `breathe - `_. + `_. SCons Glenn Hutchings has written a SCons build script to build Sphinx @@ -70,9 +70,9 @@ SCons PyPI Jannis Leidel wrote a `setuptools command - `_ that automatically uploads + `_ that automatically uploads Sphinx documentation to the PyPI package documentation area at - http://packages.python.org/. + http://pythonhosted.org/. GitHub Pages Directories starting with underscores are ignored by default which breaks @@ -139,7 +139,7 @@ The following list gives some hints for the creation of epub files: are often cut at the right margin. The default Courier font (or variant) is quite wide and you can only display up to 60 characters on a line. If you replace it with a narrower font, you can get more characters on a line. You - may even use `FontForge `_ and create + may even use `FontForge `_ and create narrow variants of some free font. In my case I get up to 70 characters on a line. @@ -168,8 +168,8 @@ The following list gives some hints for the creation of epub files: .. _Epubcheck: http://code.google.com/p/epubcheck/ .. _Calibre: http://calibre-ebook.com/ -.. _FBreader: http://www.fbreader.org/ -.. _Bookworm: http://bookworm.oreilly.com/ +.. _FBreader: http://fbreader.org/ +.. _Bookworm: http://oreilly.com/bookworm/index.html .. _texinfo-faq: diff --git a/doc/install.rst b/doc/install.rst index 9c2584208..bf6538722 100644 --- a/doc/install.rst +++ b/doc/install.rst @@ -7,7 +7,7 @@ Since Sphinx is written in the Python language, you need to install Python (the required version is at least 2.5) and Sphinx. Sphinx packages are available on the `Python Package Index -`_. +`_. You can also download a snapshot from the Mercurial development repository: @@ -118,7 +118,7 @@ Install the easy_install command Python has a very useful :command:`easy_install` command which can download and install 3rd-party libraries with a single command. This is provided by the -"setuptools" project: http://pypi.python.org/pypi/setuptools. +"setuptools" project: https://pypi.python.org/pypi/setuptools. To install setuptools, download https://bitbucket.org/pypa/setuptools/raw/bootstrap/ez_setup.py and diff --git a/doc/intro.rst b/doc/intro.rst index d1cab1c84..66d0c58dc 100644 --- a/doc/intro.rst +++ b/doc/intro.rst @@ -28,7 +28,7 @@ This section is intended to collect helpful hints for those wanting to migrate to reStructuredText/Sphinx from other documentation systems. * Gerard Flanagan has written a script to convert pure HTML to reST; it can be - found at the `Python Package Index `_. + found at the `Python Package Index `_. * For converting the old Python docs to Sphinx, a converter was written which can be found at `the Python SVN repository @@ -39,7 +39,7 @@ to reStructuredText/Sphinx from other documentation systems. markup; it is at `Google Code `_. * Christophe de Vienne wrote a tool to convert from Open/LibreOffice documents - to Sphinx: `odt2sphinx `_. + to Sphinx: `odt2sphinx `_. * To convert different markups, `Pandoc `_ is a very helpful tool. diff --git a/doc/invocation.rst b/doc/invocation.rst index 97b1e1b76..f831dc0aa 100644 --- a/doc/invocation.rst +++ b/doc/invocation.rst @@ -279,7 +279,7 @@ The :program:`sphinx-apidoc` script has several options: filesystem to discover packages and modules. You may need it if you want to generate documentation from a source directory managed by `collective.recipe.omelette - `_. + `_. By default, symbolic links are skipped. .. versionadded:: 1.2 diff --git a/doc/markup/misc.rst b/doc/markup/misc.rst index 98ce5621b..b2e9051fd 100644 --- a/doc/markup/misc.rst +++ b/doc/markup/misc.rst @@ -176,8 +176,9 @@ Including content based on tags .. 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. + within :file:`conf.py`, see :ref:`here `) are true. Boolean + expressions, also using parentheses (like ``html and (latex or draft)``) are + supported. The *format* and the *name* of the current builder (``html``, ``latex`` or ``text``) are always set as a tag [#]_. To make the distinction between @@ -185,6 +186,9 @@ Including content based on tags ``builder_``, e.g. the epub builder defines the tags ``html``, ``epub``, ``format_html`` and ``builder_epub``. + These standard tags are set *after* the configuration file is read, so they + are not available there. + .. versionadded:: 0.6 .. versionchanged:: 1.2 Added the name of the builder and the prefixes. diff --git a/sphinx/builders/linkcheck.py b/sphinx/builders/linkcheck.py index c567401c5..6cbe361ba 100644 --- a/sphinx/builders/linkcheck.py +++ b/sphinx/builders/linkcheck.py @@ -15,17 +15,30 @@ import Queue import socket import threading from os import path -from urllib2 import build_opener, unquote, Request +from urllib2 import build_opener, unquote, Request, \ + HTTPError, HTTPRedirectHandler from HTMLParser import HTMLParser, HTMLParseError from docutils import nodes from sphinx.builders import Builder -from sphinx.util.console import purple, red, darkgreen, darkgray +from sphinx.util.console import purple, red, darkgreen, darkgray, \ + darkred, turquoise + + +class RedirectHandler(HTTPRedirectHandler): + """A RedirectHandler that records the redirect code we got.""" + + def redirect_request(self, req, fp, code, msg, headers, newurl): + new_req = HTTPRedirectHandler.redirect_request(self, req, fp, code, + msg, headers, newurl) + req.redirect_code = code + return new_req # create an opener that will simulate a browser user-agent -opener = build_opener() -opener.addheaders = [('User-agent', 'Mozilla/5.0')] +opener = build_opener(RedirectHandler) +opener.addheaders = [('User-agent', 'Mozilla/5.0 (X11; Linux x86_64; rv:25.0) ' + 'Gecko/20100101 Firefox/25.0')] class HeadRequest(Request): @@ -104,18 +117,18 @@ class CheckExternalLinksBuilder(Builder): # check for various conditions without bothering the network if len(uri) == 0 or uri[0] == '#' or \ uri[0:7] == 'mailto:' or uri[0:4] == 'ftp:': - return 'unchecked', '' + return 'unchecked', '', 0 elif not (uri[0:5] == 'http:' or uri[0:6] == 'https:'): - return 'local', '' + return 'local', '', 0 elif uri in self.good: - return 'working', '' + return 'working', '', 0 elif uri in self.broken: - return 'broken', self.broken[uri] + return 'broken', self.broken[uri], 0 elif uri in self.redirected: - return 'redirected', self.redirected[uri] + return 'redirected', self.redirected[uri][0], self.redirected[uri][1] for rex in self.to_ignore: if rex.match(uri): - return 'ignored', '' + return 'ignored', '', 0 if '#' in uri: req_url, hash = uri.split('#', 1) @@ -127,61 +140,82 @@ class CheckExternalLinksBuilder(Builder): try: if hash and self.app.config.linkcheck_anchors: # Read the whole document and see if #hash exists - f = opener.open(Request(req_url), **kwargs) + req = Request(req_url) + f = opener.open(req, **kwargs) found = check_anchor(f, unquote(hash)) f.close() if not found: raise Exception("Anchor '%s' not found" % hash) else: - f = opener.open(HeadRequest(req_url), **kwargs) - f.close() + try: + # try a HEAD request, which should be easier on + # the server and the network + req = HeadRequest(req_url) + f = opener.open(req, **kwargs) + f.close() + except HTTPError, err: + if err.code != 405: + raise + # retry with GET if that fails, some servers + # don't like HEAD requests and reply with 405 + req = Request(req_url) + f = opener.open(req, **kwargs) + f.close() except Exception, err: self.broken[uri] = str(err) - return 'broken', str(err) + return 'broken', str(err), 0 if f.url.rstrip('/') == req_url.rstrip('/'): self.good.add(uri) - return 'working', 'new' + return 'working', 'new', 0 else: new_url = f.url if hash: new_url += '#' + hash - - self.redirected[uri] = new_url - return 'redirected', new_url + code = getattr(req, 'redirect_code', 0) + self.redirected[uri] = (new_url, code) + return 'redirected', new_url, code while True: uri, docname, lineno = self.wqueue.get() if uri is None: break - status, info = check() - self.rqueue.put((uri, docname, lineno, status, info)) + status, info, code = check() + self.rqueue.put((uri, docname, lineno, status, info, code)) def process_result(self, result): - uri, docname, lineno, status, info = result + uri, docname, lineno, status, info, code = result if status == 'unchecked': return if status == 'working' and info != 'new': return if lineno: - self.info('(line %3d) ' % lineno, nonl=1) + self.info('(line %4d) ' % lineno, nonl=1) if status == 'ignored': - self.info(uri + ' - ' + darkgray('ignored')) + self.info(darkgray('-ignored- ') + uri) elif status == 'local': - self.info(uri + ' - ' + darkgray('local')) + self.info(darkgray('-local- ') + uri) self.write_entry('local', docname, lineno, uri) elif status == 'working': - self.info(uri + ' - ' + darkgreen('working')) + self.info(darkgreen('ok ') + uri) elif status == 'broken': - self.info(uri + ' - ' + red('broken: ') + info) + self.info(red('broken ') + uri + red(' - ' + info)) self.write_entry('broken', docname, lineno, uri + ': ' + info) if self.app.quiet: self.warn('broken link: %s' % uri, '%s:%s' % (self.env.doc2path(docname), lineno)) elif status == 'redirected': - self.info(uri + ' - ' + purple('redirected') + ' to ' + info) - self.write_entry('redirected', docname, lineno, uri + ' to ' + info) + text, color = { + 301: ('permanently', darkred), + 302: ('with Found', purple), + 303: ('with See Other', purple), + 307: ('temporarily', turquoise), + 0: ('with unknown code', purple), + }[code] + self.write_entry('redirected ' + text, docname, lineno, + uri + ' to ' + info) + self.info(color('redirect ') + uri + color(' - ' + text + ' to ' + info)) def get_target_uri(self, docname, typ=None): return '' diff --git a/sphinx/domains/c.py b/sphinx/domains/c.py index f9f2e6647..aed5b47e5 100644 --- a/sphinx/domains/c.py +++ b/sphinx/domains/c.py @@ -59,7 +59,12 @@ class CObject(ObjectDescription): # 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')) + stopwords = set(( + 'const', 'void', 'char', 'wchar_t', 'int', 'short', + 'long', 'float', 'double', 'unsigned', 'signed', 'FILE', + 'clock_t', 'time_t', 'ptrdiff_t', 'size_t', 'ssize_t', + 'struct', '_Bool', + )) def _parse_type(self, node, ctype): # add cross-ref nodes for all words diff --git a/sphinx/ext/autosummary/generate.py b/sphinx/ext/autosummary/generate.py index 0640a332a..f45aa0858 100644 --- a/sphinx/ext/autosummary/generate.py +++ b/sphinx/ext/autosummary/generate.py @@ -33,6 +33,21 @@ from sphinx.jinja2glue import BuiltinTemplateLoader from sphinx.util.osutil import ensuredir from sphinx.util.inspect import safe_getattr +# Add documenters to AutoDirective registry +from sphinx.ext.autodoc import add_documenter, \ + ModuleDocumenter, ClassDocumenter, ExceptionDocumenter, DataDocumenter, \ + FunctionDocumenter, MethodDocumenter, AttributeDocumenter, \ + InstanceAttributeDocumenter +add_documenter(ModuleDocumenter) +add_documenter(ClassDocumenter) +add_documenter(ExceptionDocumenter) +add_documenter(DataDocumenter) +add_documenter(FunctionDocumenter) +add_documenter(MethodDocumenter) +add_documenter(AttributeDocumenter) +add_documenter(InstanceAttributeDocumenter) + + def main(argv=sys.argv): usage = """%prog [OPTIONS] SOURCEFILE ...""" p = optparse.OptionParser(usage.strip()) @@ -101,7 +116,7 @@ def generate_autosummary_docs(sources, output_dir=None, suffix='.rst', new_files = [] # write - for name, path, template_name in sorted(items): + for name, path, template_name in sorted(items, key=str): if path is None: # The corresponding autosummary:: directive did not have # a :toctree: option diff --git a/sphinx/ext/mathbase.py b/sphinx/ext/mathbase.py index b7d0d997d..0c5eaf8bc 100644 --- a/sphinx/ext/mathbase.py +++ b/sphinx/ext/mathbase.py @@ -30,11 +30,15 @@ def wrap_displaymath(math, label): parts = math.split('\n\n') ret = [] for i, part in enumerate(parts): + if not part.strip(): + continue if label is not None and i == 0: ret.append('\\begin{split}%s\\end{split}' % part + (label and '\\label{'+label+'}' or '')) else: ret.append('\\begin{split}%s\\end{split}\\notag' % part) + if not ret: + return '' return '\\begin{gather}\n' + '\\\\'.join(ret) + '\n\\end{gather}' diff --git a/sphinx/search/__init__.py b/sphinx/search/__init__.py index 8e26eb259..87377c313 100644 --- a/sphinx/search/__init__.py +++ b/sphinx/search/__init__.py @@ -10,10 +10,9 @@ """ from __future__ import with_statement import re -import itertools import cPickle as pickle -from docutils.nodes import comment, title, Text, NodeVisitor, SkipNode +from docutils.nodes import raw, comment, title, Text, NodeVisitor, SkipNode from sphinx.util import jsdump, rpartition @@ -146,7 +145,16 @@ class WordCollector(NodeVisitor): def dispatch_visit(self, node): if node.__class__ is comment: raise SkipNode - elif node.__class__ is Text: + if node.__class__ is raw: + # Some people might put content in raw HTML that should be searched, + # so we just amateurishly strip HTML tags and index the remaining + # content + nodetext = re.sub(r'(?is)', '', node.astext()) + nodetext = re.sub(r'(?is)', '', nodetext) + nodetext = re.sub(r'<[^<]+?>', '', nodetext) + self.found_words.extend(self.lang.split(nodetext)) + raise SkipNode + if node.__class__ is Text: self.found_words.extend(self.lang.split(node.astext())) elif node.__class__ is title: self.found_title_words.extend(self.lang.split(node.astext())) diff --git a/sphinx/texinputs/sphinxmanual.cls b/sphinx/texinputs/sphinxmanual.cls index 26df488ef..a6b9b3928 100644 --- a/sphinx/texinputs/sphinxmanual.cls +++ b/sphinx/texinputs/sphinxmanual.cls @@ -97,6 +97,7 @@ % \let\py@OldTableofcontents=\tableofcontents \renewcommand{\tableofcontents}{% + \pagenumbering{roman}% \setcounter{page}{1}% \pagebreak% \pagestyle{plain}% @@ -114,7 +115,7 @@ \pagenumbering{arabic}% \@ifundefined{fancyhf}{}{\pagestyle{normal}}% } -\pagenumbering{roman} +\pagenumbering{alph} % This is needed to get the width of the section # area wide enough in the % library reference. Doing it here keeps it the same for all the manuals. diff --git a/sphinx/themes/basic/static/searchtools.js_t b/sphinx/themes/basic/static/searchtools.js_t index 26121366e..523ecaaac 100644 --- a/sphinx/themes/basic/static/searchtools.js_t +++ b/sphinx/themes/basic/static/searchtools.js_t @@ -156,7 +156,7 @@ var Search = { continue; } // stem the word - var word = stemmer.stemWord(tmp[i]).toLowerCase(); + var word = stemmer.stemWord(tmp[i].toLowerCase()); var toAppend; // select the correct list if (word[0] == '-') { diff --git a/sphinx/writers/html.py b/sphinx/writers/html.py index 612496e55..308e1f5bf 100644 --- a/sphinx/writers/html.py +++ b/sphinx/writers/html.py @@ -131,24 +131,40 @@ class HTMLTranslator(BaseTranslator): def visit_desc_parameterlist(self, node): self.body.append('(') self.first_param = 1 + self.optional_param_level = 0 + # How many required parameters are left. + self.required_params_left = sum([isinstance(c, addnodes.desc_parameter) + for c in node.children]) self.param_separator = node.child_text_separator def depart_desc_parameterlist(self, node): self.body.append(')') + # If required parameters are still to come, then put the comma after + # the parameter. Otherwise, put the comma before. This ensures that + # signatures like the following render correctly (see issue #1001): + # + # foo([a, ]b, c[, d]) + # def visit_desc_parameter(self, node): - if not self.first_param: - self.body.append(self.param_separator) - else: + if self.first_param: self.first_param = 0 + elif not self.required_params_left: + self.body.append(self.param_separator) + if self.optional_param_level == 0: + self.required_params_left -= 1 if not node.hasattr('noemph'): self.body.append('') def depart_desc_parameter(self, node): if not node.hasattr('noemph'): self.body.append('') + if self.required_params_left: + self.body.append(self.param_separator) def visit_desc_optional(self, node): + self.optional_param_level += 1 self.body.append('[') def depart_desc_optional(self, node): + self.optional_param_level -= 1 self.body.append(']') def visit_desc_annotation(self, node):