diff --git a/CHANGES b/CHANGES index 92381acc3..03ee55b47 100644 --- a/CHANGES +++ b/CHANGES @@ -1,11 +1,16 @@ Release 1.0 (in development) ============================ +* Sphinx now requires Jinja2 version 2.2 or greater. + * Added ``needs_sphinx`` config value and ``Sphinx.require_sphinx`` application API function. * Added single-file HTML builder. +* Added ``autodoc_default_flags`` config value, which can be used + to select default flags for all autodoc directives. + * Added ``tab-width`` option to ``literalinclude`` directive. * The ``html_sidebars`` config value can now contain patterns as @@ -84,6 +89,11 @@ Release 1.0 (in development) Release 0.6.5 (in development) ============================== +* In autodoc, allow customizing the signature of an object where + the built-in mechanism fails. + +* #331: Fix output for enumerated lists with start values in LaTeX. + * Make the ``start-after`` and ``end-before`` options to the ``literalinclude`` directive work correctly if not used together. diff --git a/doc/builders.rst b/doc/builders.rst index 1c2bd39f2..1c207574a 100644 --- a/doc/builders.rst +++ b/doc/builders.rst @@ -81,6 +81,11 @@ The builder's "name" must be given to the **-b** command-line option of details about it. For definition of the epub format, have a look at ``_ or ``_. + Some ebook readers do not show the link targets of references. Therefore + this builder adds the targets after the link when necessary. The display + of the URLs can be customized by adding CSS rules for the class + ``link-target``. + Its name is ``epub``. .. module:: sphinx.builders.latex diff --git a/doc/config.rst b/doc/config.rst index 92542f8ce..6d0563e09 100644 --- a/doc/config.rst +++ b/doc/config.rst @@ -308,9 +308,8 @@ Project information .. confval:: pygments_style - The style name to use for Pygments highlighting of source code. Default is - ``'sphinx'``, which is a builtin style designed to match Sphinx' default - style. + The style name to use for Pygments highlighting of source code. The default + style is selected by the theme for HTML output, and ``'sphinx'`` otherwise. .. versionchanged:: 0.3 If the value is a fully-qualified name of a custom Pygments style class, @@ -708,6 +707,12 @@ the `Dublin Core metadata `_. A list of files that are generated/copied in the build directory but should not be included in the epub file. The default value is ``[]``. +.. confval:: epub_tocdepth + + The depth of the table of contents in the file :file:`toc.ncx`. It should + be an integer greater than zero. The default value is 3. Note: A deeply + nested table of contents may be difficult to navigate. + .. _latex-options: diff --git a/doc/ext/autodoc.rst b/doc/ext/autodoc.rst index b4b4b3f31..4098d7113 100644 --- a/doc/ext/autodoc.rst +++ b/doc/ext/autodoc.rst @@ -228,6 +228,24 @@ There are also new config values that you can set: .. versionadded:: 0.6 +.. confval:: autodoc_default_flags + + This value is a list of autodoc directive flags that should be automatically + applied to all autodoc directives. The supported flags are ``'members'``, + ``'undoc-members'``, ``'inherited-members'`` and ``'show-inheritance'``. + + If you set one of these flags in this config value, you can use a negated + form, :samp:`'no-{flag}'`, in an autodoc directive, to disable it once. + For example, if ``autodoc_default_flags`` is set to ``['members', + 'undoc-members']``, and you write a directive like this:: + + .. automodule:: foo + :no-undoc-members: + + the directive will be interpreted as if only ``:members:`` was given. + + .. versionadded:: 1.0 + Docstring preprocessing ----------------------- diff --git a/doc/ext/autosummary.rst b/doc/ext/autosummary.rst index 20b688c1f..8193bc529 100644 --- a/doc/ext/autosummary.rst +++ b/doc/ext/autosummary.rst @@ -97,6 +97,8 @@ The :mod:`sphinx.ext.autosummary` extension does this in two parts: :confval:`templates_path` to generate the pages for all entries listed. See `Customizing templates`_ below. + .. versionadded:: 1.0 + :program:`sphinx-autogen` -- generate autodoc stub pages -------------------------------------------------------- @@ -142,6 +144,8 @@ also use this new config value: Customizing templates --------------------- +.. versionadded:: 1.0 + You can customize the stub page templates, in a similar way as the HTML Jinja templates, see :ref:`templating`. (:class:`~sphinx.application.TemplateBridge` is not supported.) diff --git a/setup.py b/setup.py index aedfb8e78..6a46e6d61 100644 --- a/setup.py +++ b/setup.py @@ -40,7 +40,7 @@ A development egg can be found `here `_. ''' -requires = ['Pygments>=0.8', 'Jinja2>=2.1', 'docutils>=0.4'] +requires = ['Pygments>=0.8', 'Jinja2>=2.2', 'docutils>=0.4'] if sys.version_info < (2, 4): print 'ERROR: Sphinx requires at least Python 2.4 to run.' diff --git a/sphinx/builders/epub.py b/sphinx/builders/epub.py index 6694c8afd..9767391e0 100644 --- a/sphinx/builders/epub.py +++ b/sphinx/builders/epub.py @@ -16,6 +16,7 @@ from os import path import zipfile from docutils import nodes +from docutils.transforms import Transform from sphinx.builders.html import StandaloneHTMLBuilder from sphinx.util.osutil import EEXIST @@ -23,6 +24,9 @@ from sphinx.util.osutil import EEXIST # (Fragment) templates from which the metainfo files content.opf, toc.ncx, # mimetype, and META-INF/container.xml are created. +# This template section also defines strings that are embedded in the html +# output but that may be customized by (re-)setting module attributes, +# e.g. from conf.py. _mimetype_template = 'application/epub+zip' # no EOL! @@ -99,6 +103,10 @@ _spine_template = u'''\ _toctree_template = u'toctree-l%d' +_link_target_template = u' [%(uri)s]' + +_css_link_target_class = u'link-target' + _media_types = { '.html': 'application/xhtml+xml', '.css': 'text/css', @@ -112,6 +120,30 @@ _media_types = { } +# The transform to show link targets + +class VisibleLinksTransform(Transform): + """ + Add the link target of referances to the text, unless it is already + present in the description. + """ + + # This transform must run after the references transforms + default_priority = 680 + + def apply(self): + for ref in self.document.traverse(nodes.reference): + uri = ref.get('refuri', '') + if ( uri.startswith('http:') or uri.startswith('https:') or \ + uri.startswith('ftp:') ) and uri not in ref.astext(): + uri = _link_target_template % {'uri': uri} + if uri: + idx = ref.parent.index(ref) + 1 + link = nodes.inline(uri, uri) + link['classes'].append(_css_link_target_class) + ref.parent.insert(idx, link) + + # The epub publisher class EpubBuilder(StandaloneHTMLBuilder): @@ -138,6 +170,7 @@ class EpubBuilder(StandaloneHTMLBuilder): # the output files for epub must be .html only self.out_suffix = '.html' self.playorder = 0 + self.app.add_transform(VisibleLinksTransform) def get_theme_config(self): return self.config.epub_theme, {} @@ -145,7 +178,7 @@ class EpubBuilder(StandaloneHTMLBuilder): # generic support functions def make_id(self, name): """Replace all characters not allowed for (X)HTML ids.""" - return name.replace('/', '_') + return name.replace('/', '_').replace(' ', '') def esc(self, name): """Replace all characters not allowed in text an attribute values.""" @@ -157,34 +190,20 @@ class EpubBuilder(StandaloneHTMLBuilder): name = name.replace('\'', ''') return name - def collapse_text(self, doctree, result): - """Remove all HTML markup and return only the text nodes.""" - for c in doctree.children: - if isinstance(c, nodes.Text): - try: - # docutils 0.4 and 0.5: Text is a UserString subclass - result.append(c.data) - except AttributeError: - # docutils 0.6: Text is a unicode subclass - result.append(c) - else: - result = self.collapse_text(c, result) - return result - def get_refnodes(self, doctree, result): """Collect section titles, their depth in the toc and the refuri.""" # XXX: is there a better way than checking the attribute - # toctree-l[1-6] on the parent node? + # toctree-l[1-8] on the parent node? if isinstance(doctree, nodes.reference): classes = doctree.parent.attributes['classes'] level = 1 - for l in range(5,0,-1): # or range(1,6)? + for l in range(8, 0, -1): # or range(1, 8)? if (_toctree_template % l) in classes: level = l result.append({ 'level': level, 'refuri': self.esc(doctree['refuri']), - 'text': self.esc(''.join(self.collapse_text(doctree, []))) + 'text': self.esc(doctree.astext()) }) else: for elem in doctree.children: @@ -195,16 +214,14 @@ class EpubBuilder(StandaloneHTMLBuilder): """Get the total table of contents, containg the master_doc and pre and post files not managed by sphinx. """ - doctree = self.env.get_and_resolve_doctree(self.config.master_doc, self) + doctree = self.env.get_and_resolve_doctree(self.config.master_doc, + self, prune_toctrees=False) self.refnodes = self.get_refnodes(doctree, []) self.refnodes.insert(0, { 'level': 1, 'refuri': self.esc(self.config.master_doc + '.html'), - 'text': self.esc(''.join(self.collapse_text( - self.env.titles[self.config.master_doc], [] - ))), + 'text': self.esc(self.env.titles[self.config.master_doc].astext()) }) - # XXX: is reversed ok? for file, text in reversed(self.config.epub_pre_files): self.refnodes.insert(0, { 'level': 1, @@ -290,11 +307,10 @@ class EpubBuilder(StandaloneHTMLBuilder): for fn in files: filename = path.join(root, fn)[olen:] if filename in self.ignored_files: - # self.warn("ignoring %s" % filename) continue ext = path.splitext(filename)[-1] if ext not in _media_types: - self.warn("unknown mimetype for %s, ignoring" % filename) + self.warn('unknown mimetype for %s, ignoring' % filename) continue projectfiles.append(_file_template % { 'href': self.esc(filename), @@ -338,7 +354,7 @@ class EpubBuilder(StandaloneHTMLBuilder): """Insert nested navpoints for given node. The node and subnav are already rendered to text. """ - nlist = node.split('\n') + nlist = node.rsplit('\n', 1) nlist.insert(-1, subnav) return '\n'.join(nlist) @@ -356,8 +372,10 @@ class EpubBuilder(StandaloneHTMLBuilder): file = node['refuri'].split('#')[0] if file in self.ignored_files: continue + if node['level'] > self.config.epub_tocdepth: + continue if node['level'] == level: - navlist.append(self.new_navpoint(node,level)) + navlist.append(self.new_navpoint(node, level)) elif node['level'] == level + 1: navstack.append(navlist) navlist = [] @@ -398,6 +416,7 @@ class EpubBuilder(StandaloneHTMLBuilder): navpoints = self.build_navpoints(self.refnodes) level = max(item['level'] for item in self.refnodes) + level = min(level, self.config.epub_tocdepth) f = codecs.open(path.join(outdir, outname), 'w', 'utf-8') try: f.write(_toc_template % self.toc_metadata(level, navpoints)) diff --git a/sphinx/config.py b/sphinx/config.py index a77957777..b81958df5 100644 --- a/sphinx/config.py +++ b/sphinx/config.py @@ -117,6 +117,7 @@ class Config(object): epub_pre_files = ([], 'env'), epub_post_files = ([], 'env'), epub_exclude_files = ([], 'env'), + epub_tocdepth = (3, 'env'), # LaTeX options latex_documents = ([], None), diff --git a/sphinx/ext/autodoc.py b/sphinx/ext/autodoc.py index d3d19dcf5..1be4a7059 100644 --- a/sphinx/ext/autodoc.py +++ b/sphinx/ext/autodoc.py @@ -377,7 +377,12 @@ class Documenter(object): args = "(%s)" % self.args else: # try to introspect the signature - args = self.format_args() + try: + args = self.format_args() + except Exception, err: + self.directive.warn('error while formatting arguments for ' + '%s: %s' % (self.fullname, err)) + args = None retann = self.retann @@ -663,12 +668,7 @@ class Documenter(object): self.add_line(u'', '') # 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 = '' + sig = self.format_signature() # generate the directive header and options, if applicable self.add_directive_header(sig) @@ -868,7 +868,6 @@ class ClassDocumenter(ModuleLevelDocumenter): 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 @@ -1098,6 +1097,10 @@ class AutoDirective(Directive): # a registry of type -> getattr function _special_attrgetters = {} + # flags that can be given in autodoc_default_flags + _default_flags = set(['members', 'undoc-members', 'inherited-members', + 'show-inheritance']) + # standard docutils directive settings has_content = True required_arguments = 1 @@ -1120,6 +1123,14 @@ class AutoDirective(Directive): # find out what documenter to call objtype = self.name[4:] doc_class = self._registry[objtype] + # add default flags + for flag in self._default_flags: + if flag not in doc_class.option_spec: + continue + negated = self.options.pop('no-' + flag, 'not given') is None + if flag in self.env.config.autodoc_default_flags and \ + not negated: + self.options[flag] = None # process the options with the selected documenter's option_spec self.genopt = Options(assemble_option_dict( self.options.items(), doc_class.option_spec)) @@ -1177,6 +1188,7 @@ def setup(app): app.add_config_value('autoclass_content', 'class', True) app.add_config_value('autodoc_member_order', 'alphabetic', True) + app.add_config_value('autodoc_default_flags', [], True) app.add_event('autodoc-process-docstring') app.add_event('autodoc-process-signature') app.add_event('autodoc-skip-member') diff --git a/sphinx/quickstart.py b/sphinx/quickstart.py index d3f67bb1f..f38d653ae 100644 --- a/sphinx/quickstart.py +++ b/sphinx/quickstart.py @@ -258,6 +258,9 @@ latex_documents = [ # A list of files that should not be packed into the epub file. #epub_exclude_files = [] + +# The depth of the table of contents in toc.ncx. +#epub_tocdepth = 3 ''' INTERSPHINX_CONFIG = ''' diff --git a/sphinx/setup_command.py b/sphinx/setup_command.py index d569b031c..d4f873488 100644 --- a/sphinx/setup_command.py +++ b/sphinx/setup_command.py @@ -22,7 +22,41 @@ from sphinx.util.console import darkred, nocolor, color_terminal class BuildDoc(Command): - """Distutils command to build Sphinx documentation.""" + """Distutils command to build Sphinx documentation. + + The Sphinx build can then be triggered from distutils, and some Sphinx + options can be set in ``setup.py`` or ``setup.cfg`` instead of Sphinx own + configuration file. + + For instance, from `setup.py`:: + + # this is only necessary when not using setuptools/distribute + from sphinx.setup_command import BuildDoc + cmdclass = {'build_sphinx': BuildDoc} + + name = 'My project' + version = 1.2 + release = 1.2.0 + setup( + name=name, + author='Bernard Montgomery', + version=release, + cmdclass={'build_sphinx': BuildDoc}, + # these are optional and override conf.py settings + command_options={ + 'build_sphinx': { + 'project': ('setup.py', name), + 'version': ('setup.py', version), + 'release': ('setup.py', release)}}, + ) + + Or add this section in ``setup.cfg``:: + + [build_sphinx] + project = 'My project' + version = 1.2 + release = 1.2.0 + """ description = 'Build Sphinx documentation' user_options = [ @@ -31,15 +65,22 @@ class BuildDoc(Command): ('source-dir=', 's', 'Source directory'), ('build-dir=', None, 'Build directory'), ('builder=', 'b', 'The builder to use. Defaults to "html"'), - ] + ('project=', None, 'The documented project\'s name'), + ('version=', None, 'The short X.Y version'), + ('release=', None, 'The full version, including alpha/beta/rc tags'), + ('today=', None, 'How to format the current date, used as the ' + 'replacement for |today|'), + ] boolean_options = ['fresh-env', 'all-files'] def initialize_options(self): self.fresh_env = self.all_files = False self.source_dir = self.build_dir = None - self.conf_file_name = 'conf.py' self.builder = 'html' + self.version = '' + self.release = '' + self.today = '' def _guess_source_dir(self): for guess in ('doc', 'docs'): @@ -74,9 +115,16 @@ class BuildDoc(Command): status_stream = StringIO() else: status_stream = sys.stdout + confoverrides = {} + if self.version: + confoverrides['version'] = self.version + if self.release: + confoverrides['release'] = self.release + if self.today: + confoverrides['today'] = self.today app = Sphinx(self.source_dir, self.source_dir, self.builder_target_dir, self.doctree_dir, - self.builder, {}, status_stream, + self.builder, confoverrides, status_stream, freshenv=self.fresh_env) try: diff --git a/sphinx/themes/epub/static/epub.css b/sphinx/themes/epub/static/epub.css index f941b79a6..c6320c8c0 100644 --- a/sphinx/themes/epub/static/epub.css +++ b/sphinx/themes/epub/static/epub.css @@ -420,6 +420,19 @@ div.footer a { text-decoration: underline; } +/* -- link-target ----------------------------------------------------------- */ + +.link-target { + font-size: 80%; +} + +table .link-target { + /* Do not show links in tables, there is not enough space */ + display: none; +} + +/* -- font-face ------------------------------------------------------------- */ + @font-face { font-family: "LiberationNarrow"; font-style: normal; diff --git a/sphinx/writers/latex.py b/sphinx/writers/latex.py index f756dbcc3..948f5118d 100644 --- a/sphinx/writers/latex.py +++ b/sphinx/writers/latex.py @@ -741,6 +741,8 @@ class LaTeXTranslator(nodes.NodeVisitor): def visit_enumerated_list(self, node): self.body.append('\\begin{enumerate}\n' ) + if 'start' in node: + self.body.append('\\setcounter{enumi}{%d}\n' % (node['start'] - 1)) def depart_enumerated_list(self, node): self.body.append('\\end{enumerate}\n' ) diff --git a/tests/test_autodoc.py b/tests/test_autodoc.py index b505b06ae..58bdfaef4 100644 --- a/tests/test_autodoc.py +++ b/tests/test_autodoc.py @@ -169,8 +169,9 @@ def test_format_signature(): 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(TypeError, formatsig, 'function', 'int', int, None, None) + # test exception handling (exception is caught and args is '') + assert formatsig('function', 'int', int, None, None) == '' + del _warnings[:] # test processing by event handler assert formatsig('method', 'bar', H.foo1, None, None) == '42'