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/15] - 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/15] 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/15] 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/15] 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/15] 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/15] 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/15] 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/15] 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/15] 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/15] 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/15] 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/15] 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/15] 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/15] 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/15] 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."""