From a26a714202bd7d4241145ee894a63197d9a9e796 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C3=A9bastien=20Barth=C3=A9lemy?= Date: Mon, 31 Aug 2009 16:32:14 +0200 Subject: [PATCH 01/22] - removed sphinx.setup_command.BuildDoc.conf_file_name that seems useless - added version/release/today option to sphinx.setup_command.BuildDoc --- sphinx/setup_command.py | 17 ++++++++++++++--- 1 file changed, 14 insertions(+), 3 deletions(-) diff --git a/sphinx/setup_command.py b/sphinx/setup_command.py index a33b4ee65..ea2caa676 100644 --- a/sphinx/setup_command.py +++ b/sphinx/setup_command.py @@ -31,15 +31,19 @@ class BuildDoc(Command): ('source-dir=', 's', 'Source directory'), ('build-dir=', None, 'Build directory'), ('builder=', 'b', 'The builder to use. Defaults to "html"'), - ] + ('version=', None, 'The short X.Y version'), + ('release=', None, 'The full version, including alpha/beta/rc tags'), + ('today=', None, 'hum... 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 finalize_options(self): if self.source_dir is None: @@ -70,9 +74,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: From cedd39573fd5baad107e8a68a5b1b3662f6a779d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C3=A9bastien=20Barth=C3=A9lemy?= Date: Thu, 10 Sep 2009 16:25:48 +0200 Subject: [PATCH 02/22] added project option and improved doc. --- sphinx/setup_command.py | 37 +++++++++++++++++++++++++++++++++++-- 1 file changed, 35 insertions(+), 2 deletions(-) diff --git a/sphinx/setup_command.py b/sphinx/setup_command.py index ea2caa676..746af6c00 100644 --- a/sphinx/setup_command.py +++ b/sphinx/setup_command.py @@ -22,7 +22,39 @@ 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`:: + + 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}, + 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,9 +63,10 @@ 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, 'hum... today??')] + ('today=', None, 'How to format the current date, used as the replacement for |today|')] boolean_options = ['fresh-env', 'all-files'] From 97fea89ac22122fd7745db49d98f43e4b860f27a Mon Sep 17 00:00:00 2001 From: roland Date: Wed, 6 Jan 2010 18:14:48 +0100 Subject: [PATCH 03/22] Include full toctree in get_toc. See also http://bitbucket.org/rolmei/sphinx-epub/issue/2/missing-files-in-spine --- sphinx/builders/epub.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/sphinx/builders/epub.py b/sphinx/builders/epub.py index 57e2dff9a..e22b15201 100644 --- a/sphinx/builders/epub.py +++ b/sphinx/builders/epub.py @@ -188,7 +188,8 @@ class EpubBuilder(StandaloneHTMLBuilder): def get_toc(self): """Get the total table of contents, containg the master_doc and pre and post files not managed by sphinx""" - 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, From 1ab64574367d65fa8238a7c284592c61993bbd5c Mon Sep 17 00:00:00 2001 From: Roland Meister Date: Thu, 7 Jan 2010 18:01:11 +0100 Subject: [PATCH 04/22] Increased toctree level. Some documents are deeply nested. --- sphinx/builders/epub.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sphinx/builders/epub.py b/sphinx/builders/epub.py index e22b15201..07f13ffeb 100644 --- a/sphinx/builders/epub.py +++ b/sphinx/builders/epub.py @@ -172,7 +172,7 @@ class EpubBuilder(StandaloneHTMLBuilder): 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({ From fa1f187c8434304217354a074ab4021b16640bd3 Mon Sep 17 00:00:00 2001 From: Roland Meister Date: Sat, 9 Jan 2010 11:12:36 +0100 Subject: [PATCH 05/22] Code cleanup: add space after comma. --- sphinx/builders/epub.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/sphinx/builders/epub.py b/sphinx/builders/epub.py index e5157d2dd..2d096a116 100644 --- a/sphinx/builders/epub.py +++ b/sphinx/builders/epub.py @@ -177,7 +177,7 @@ class EpubBuilder(StandaloneHTMLBuilder): if isinstance(doctree, nodes.reference): classes = doctree.parent.attributes['classes'] level = 1 - for l in range(8,0,-1): # or range(1,8)? + for l in range(8, 0, -1): # or range(1, 8)? if (_toctree_template % l) in classes: level = l result.append({ @@ -357,7 +357,7 @@ class EpubBuilder(StandaloneHTMLBuilder): if file in self.ignored_files: 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 = [] From 8b95f651925498b26dde7a7c69de4f9f97ce390f Mon Sep 17 00:00:00 2001 From: Roland Meister Date: Sat, 9 Jan 2010 11:13:10 +0100 Subject: [PATCH 06/22] Removed comment about reversed. Reversed exists since Python 2.4 and is ok for sphinx. --- sphinx/builders/epub.py | 1 - 1 file changed, 1 deletion(-) diff --git a/sphinx/builders/epub.py b/sphinx/builders/epub.py index 2d096a116..e78f807ee 100644 --- a/sphinx/builders/epub.py +++ b/sphinx/builders/epub.py @@ -204,7 +204,6 @@ class EpubBuilder(StandaloneHTMLBuilder): self.env.titles[self.config.master_doc], [] ))), }) - # XXX: is reversed ok? for file, text in reversed(self.config.epub_pre_files): self.refnodes.insert(0, { 'level': 1, From 0a1f09c9cf103061e6edf1dd78ce2298b1072941 Mon Sep 17 00:00:00 2001 From: Roland Meister Date: Sat, 9 Jan 2010 11:19:41 +0100 Subject: [PATCH 07/22] Added the epub_tocdepth configuration option. --- doc/config.rst | 6 ++++++ sphinx/builders/epub.py | 2 ++ sphinx/config.py | 1 + sphinx/quickstart.py | 3 +++ 4 files changed, 12 insertions(+) diff --git a/doc/config.rst b/doc/config.rst index e4693d848..50aacc4e9 100644 --- a/doc/config.rst +++ b/doc/config.rst @@ -701,6 +701,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/sphinx/builders/epub.py b/sphinx/builders/epub.py index e78f807ee..0e4529e5c 100644 --- a/sphinx/builders/epub.py +++ b/sphinx/builders/epub.py @@ -355,6 +355,8 @@ 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)) elif node['level'] == level + 1: diff --git a/sphinx/config.py b/sphinx/config.py index 5fe3f63f4..e7e05169b 100644 --- a/sphinx/config.py +++ b/sphinx/config.py @@ -112,6 +112,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/quickstart.py b/sphinx/quickstart.py index faea2c2ed..a7b80dd55 100644 --- a/sphinx/quickstart.py +++ b/sphinx/quickstart.py @@ -254,6 +254,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 = ''' From 791d1a757e827b2521fbc92080d7f1325e6b11d6 Mon Sep 17 00:00:00 2001 From: Roland Meister Date: Sat, 9 Jan 2010 11:23:53 +0100 Subject: [PATCH 08/22] Removed the collapse_text method. Docutils astext method already does the right thing. --- sphinx/builders/epub.py | 20 ++------------------ 1 file changed, 2 insertions(+), 18 deletions(-) diff --git a/sphinx/builders/epub.py b/sphinx/builders/epub.py index 0e4529e5c..5bcbb8b75 100644 --- a/sphinx/builders/epub.py +++ b/sphinx/builders/epub.py @@ -156,20 +156,6 @@ 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 @@ -183,7 +169,7 @@ class EpubBuilder(StandaloneHTMLBuilder): 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: @@ -200,9 +186,7 @@ class EpubBuilder(StandaloneHTMLBuilder): 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()) }) for file, text in reversed(self.config.epub_pre_files): self.refnodes.insert(0, { From 257321e79ecb491375d586247d7eea90e04dcc66 Mon Sep 17 00:00:00 2001 From: Roland Meister Date: Sat, 9 Jan 2010 11:25:13 +0100 Subject: [PATCH 09/22] Fixed comment for toctree depth. --- sphinx/builders/epub.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sphinx/builders/epub.py b/sphinx/builders/epub.py index 5bcbb8b75..b3ac42424 100644 --- a/sphinx/builders/epub.py +++ b/sphinx/builders/epub.py @@ -159,7 +159,7 @@ class EpubBuilder(StandaloneHTMLBuilder): 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 From 77f02290ee1c1cf379704fc92719f5602fdd9196 Mon Sep 17 00:00:00 2001 From: Roland Meister Date: Sat, 9 Jan 2010 11:33:58 +0100 Subject: [PATCH 10/22] Use rsplit instead of split in insert_subnav. --- sphinx/builders/epub.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sphinx/builders/epub.py b/sphinx/builders/epub.py index b3ac42424..5104a8955 100644 --- a/sphinx/builders/epub.py +++ b/sphinx/builders/epub.py @@ -321,7 +321,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) From 0ec66c2d3f56fe535c70e667c284e876f5f5489a Mon Sep 17 00:00:00 2001 From: Roland Meister Date: Sat, 9 Jan 2010 12:17:16 +0100 Subject: [PATCH 11/22] Fix the dtb:depth meta parameter in toc.ncx. --- sphinx/builders/epub.py | 1 + 1 file changed, 1 insertion(+) diff --git a/sphinx/builders/epub.py b/sphinx/builders/epub.py index 5104a8955..77b9603b1 100644 --- a/sphinx/builders/epub.py +++ b/sphinx/builders/epub.py @@ -383,6 +383,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)) From a880aa8f7009318730bff0dfd1d330e7807ceb19 Mon Sep 17 00:00:00 2001 From: Roland Meister Date: Sun, 10 Jan 2010 21:14:19 +0100 Subject: [PATCH 12/22] Added transform for visible links. --- doc/builders.rst | 5 +++++ sphinx/builders/epub.py | 25 +++++++++++++++++++++++++ sphinx/themes/epub/static/epub.css | 13 +++++++++++++ 3 files changed, 43 insertions(+) diff --git a/doc/builders.rst b/doc/builders.rst index e8dccc430..ff40783a5 100644 --- a/doc/builders.rst +++ b/doc/builders.rst @@ -71,6 +71,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/sphinx/builders/epub.py b/sphinx/builders/epub.py index 77b9603b1..4d042353f 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 @@ -111,6 +112,29 @@ _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 = ' [%s]' % uri + idx = ref.parent.index(ref) + 1 + link = nodes.inline(uri, uri) + link['classes'].append('link-target') + ref.parent.insert(idx, link) + + # The epub publisher class EpubBuilder(StandaloneHTMLBuilder): @@ -137,6 +161,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, {} 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; From 46047b60bf834b8a9d41020938b504b51cadf662 Mon Sep 17 00:00:00 2001 From: Roland Meister Date: Tue, 12 Jan 2010 22:09:02 +0100 Subject: [PATCH 13/22] Moved string constants to module level. --- sphinx/builders/epub.py | 18 +++++++++++++----- 1 file changed, 13 insertions(+), 5 deletions(-) diff --git a/sphinx/builders/epub.py b/sphinx/builders/epub.py index 4d042353f..44f5eb083 100644 --- a/sphinx/builders/epub.py +++ b/sphinx/builders/epub.py @@ -23,6 +23,9 @@ from sphinx.builders.html import StandaloneHTMLBuilder # (Fragment) templates from which the metainfo files content.opf, toc.ncx, # mimetype, and META-INF/container.xml are created. +# 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 +102,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', @@ -128,11 +135,12 @@ class VisibleLinksTransform(Transform): uri = ref.get('refuri', '') if ( uri.startswith('http:') or uri.startswith('https:') or \ uri.startswith('ftp:') ) and uri not in ref.astext(): - uri = ' [%s]' % uri - idx = ref.parent.index(ref) + 1 - link = nodes.inline(uri, uri) - link['classes'].append('link-target') - ref.parent.insert(idx, link) + 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 From 96bfbdcc778dc81ce174ddee1058dc3813953f62 Mon Sep 17 00:00:00 2001 From: Roland Meister Date: Tue, 12 Jan 2010 22:19:05 +0100 Subject: [PATCH 14/22] Code cleanup: removed comment; consistent use of single quote in string constants. --- sphinx/builders/epub.py | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/sphinx/builders/epub.py b/sphinx/builders/epub.py index 44f5eb083..d17593dfa 100644 --- a/sphinx/builders/epub.py +++ b/sphinx/builders/epub.py @@ -306,11 +306,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), From 531c27c89ab9c5ff27187d639eec887a23f072e5 Mon Sep 17 00:00:00 2001 From: Roland Meister Date: Fri, 15 Jan 2010 20:49:49 +0100 Subject: [PATCH 15/22] Fixed one more invalid char for make_id. --- sphinx/builders/epub.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sphinx/builders/epub.py b/sphinx/builders/epub.py index d17593dfa..04de91094 100644 --- a/sphinx/builders/epub.py +++ b/sphinx/builders/epub.py @@ -177,7 +177,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.""" From a515165be65130bc59726d5ae4a29e582a55ee9c Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Wed, 17 Feb 2010 10:38:59 +0100 Subject: [PATCH 16/22] Update Jinja2 requirement. --- CHANGES | 2 ++ setup.py | 2 +- 2 files changed, 3 insertions(+), 1 deletion(-) diff --git a/CHANGES b/CHANGES index 92381acc3..46eaf9c35 100644 --- a/CHANGES +++ b/CHANGES @@ -1,6 +1,8 @@ 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. 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.' From b2c79111f88851cebd9bb8403d7135cfe26b0f53 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Fri, 19 Feb 2010 10:45:04 +0100 Subject: [PATCH 17/22] #331: Fix output for enumerated lists with start values in LaTeX. --- CHANGES | 2 ++ sphinx/writers/latex.py | 2 ++ 2 files changed, 4 insertions(+) diff --git a/CHANGES b/CHANGES index 2db62edb4..6ee492305 100644 --- a/CHANGES +++ b/CHANGES @@ -1,6 +1,8 @@ Release 0.6.5 (in development) ============================== +* #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/sphinx/writers/latex.py b/sphinx/writers/latex.py index 14e9bc059..517d8d86d 100644 --- a/sphinx/writers/latex.py +++ b/sphinx/writers/latex.py @@ -734,6 +734,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' ) From b9dd04176f074e097a6b61e2da5776287e189859 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Fri, 19 Feb 2010 19:58:35 +0100 Subject: [PATCH 18/22] pygments_style for HTML is selected by the theme. --- doc/config.rst | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/doc/config.rst b/doc/config.rst index 2e96a749c..7c5256146 100644 --- a/doc/config.rst +++ b/doc/config.rst @@ -271,9 +271,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, From b81b7a046328dff1cac28b9b35920f4636a8465f Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Sun, 21 Feb 2010 21:46:07 +0100 Subject: [PATCH 19/22] Remove docs for autosummary features that are not actually in 0.6. --- doc/ext/autosummary.rst | 98 ----------------------------------------- 1 file changed, 98 deletions(-) diff --git a/doc/ext/autosummary.rst b/doc/ext/autosummary.rst index 9d75cb0cb..7b5e5b6b9 100644 --- a/doc/ext/autosummary.rst +++ b/doc/ext/autosummary.rst @@ -85,18 +85,6 @@ The :mod:`sphinx.ext.autosummary` extension does this in two parts: sphinx.environment.BuildEnvironment sphinx.util.relative_uri - * You can specify a custom template with the ``template`` option. - For example, :: - - .. autosummary:: - :template: mytemplate.rst - - sphinx.environment.BuildEnvironment - - would use the template :file:`mytemplate.rst` in your - :confval:`templates_path` to generate the pages for all entries - listed. See `Customizing templates`_ below. - :program:`sphinx-autogen` -- generate autodoc stub pages -------------------------------------------------------- @@ -134,89 +122,3 @@ also use this new config value: The new files will be placed in the directories specified in the ``:toctree:`` options of the directives. - - -Customizing templates ---------------------- - -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.) - -.. note:: - - If you find yourself spending much time tailoring the stub templates, this - may indicate that it's a better idea to write custom narrative documentation - instead. - -Autosummary uses the following template files: - -- :file:`autosummary/base.rst` -- fallback template -- :file:`autosummary/module.rst` -- template for modules -- :file:`autosummary/class.rst` -- template for classes -- :file:`autosummary/function.rst` -- template for functions -- :file:`autosummary/attribute.rst` -- template for class attributes -- :file:`autosummary/method.rst` -- template for class methods - -The following variables available in the templates: - -.. data:: name - - Name of the documented object, excluding the module and class parts. - -.. data:: objname - - Name of the documented object, excluding the module parts. - -.. data:: fullname - - Full name of the documented object, including module and class parts. - -.. data:: module - - Name of the module the documented object belongs to. - -.. data:: class - - Name of the class the documented object belongs to. Only available for - methods and attributes. - -.. data:: underline - - A string containing ``len(full_name) * '='``. - -.. data:: members - - List containing names of all members of the module or class. Only available - for modules and classes. - -.. data:: functions - - List containing names of "public" functions in the module. Here, "public" - here means that the name does not start with an underscore. Only available - for modules. - -.. data:: classes - - List containing names of "public" classes in the module. Only available for - modules. - -.. data:: exceptions - - List containing names of "public" exceptions in the module. Only available - for modules. - -.. data:: methods - - List containing names of "public" methods in the class. Only available for - classes. - -.. data:: attributes - - List containing names of "public" attributes in the class. Only available - for classes. - -.. note:: - - You can use the :dir:`autosummary` directive in the stub pages. - Stub pages are generated also based on these directives. From 750c3622fd66efc7980f14cc54ad719a4d2cf840 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Sun, 21 Feb 2010 21:57:58 +0100 Subject: [PATCH 20/22] Add some versionadded tags. --- doc/ext/autosummary.rst | 4 ++++ 1 file changed, 4 insertions(+) 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.) From fab92b215afa61ffa17a12919a3bd5192adba754 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Sun, 21 Feb 2010 22:16:06 +0100 Subject: [PATCH 21/22] Added ``autodoc_default_flags`` config value, which can be used to select default flags for all autodoc directives. --- CHANGES | 3 +++ doc/ext/autodoc.rst | 18 ++++++++++++++++++ sphinx/ext/autodoc.py | 13 +++++++++++++ 3 files changed, 34 insertions(+) diff --git a/CHANGES b/CHANGES index 671d71b37..2b1220320 100644 --- a/CHANGES +++ b/CHANGES @@ -8,6 +8,9 @@ Release 1.0 (in development) * 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 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/sphinx/ext/autodoc.py b/sphinx/ext/autodoc.py index d3d19dcf5..81c3f6a44 100644 --- a/sphinx/ext/autodoc.py +++ b/sphinx/ext/autodoc.py @@ -1098,6 +1098,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 +1124,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 +1189,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') From 686824997dffd30b689f0abc5f3df8997149acc4 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Sun, 21 Feb 2010 22:59:53 +0100 Subject: [PATCH 22/22] In autodoc, allow customizing the signature of an object via autodoc-process-signature where the built-in mechanism fails. --- CHANGES | 3 +++ sphinx/ext/autodoc.py | 18 ++++++++---------- tests/test_autodoc.py | 5 +++-- 3 files changed, 14 insertions(+), 12 deletions(-) diff --git a/CHANGES b/CHANGES index 6ee492305..a9d4824d7 100644 --- a/CHANGES +++ b/CHANGES @@ -1,6 +1,9 @@ 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 diff --git a/sphinx/ext/autodoc.py b/sphinx/ext/autodoc.py index 2123692b5..ec0a993b4 100644 --- a/sphinx/ext/autodoc.py +++ b/sphinx/ext/autodoc.py @@ -365,9 +365,13 @@ class Documenter(object): args = "(%s)" % self.args else: # try to introspect the signature - args = self.format_args() - if args is None: - return '' + 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 result = self.env.app.emit_firstresult( @@ -644,12 +648,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) @@ -849,7 +848,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 diff --git a/tests/test_autodoc.py b/tests/test_autodoc.py index 73394bf22..e0845b67a 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'