Add new setting epub_tocscope for epub builder.

The new setting replaces the old heuristic that was never that good.

doc/config.rst

@@ -916,6 +916,15 @@ the `Dublin Core metadata <http://dublincore.org/>`_.
    a chapter, but can be confusing because it mixes entries of differnet
    depth in one list.  The default value is ``True``.
 
+.. confval:: epub_tocscope
+
+   This setting control the scope of the epub table of contents.  The setting
+   can have the following values:
+
+   * ``'default'`` -- include all toc entries that are not hidden (default)
+   * ``'includehidden'`` -- include all toc entries
+
+   .. versionadded:: 1.2
 
 .. confval:: epub_fix_images
 

sphinx/builders/epub.py

@@ -642,12 +642,13 @@ class EpubBuilder(StandaloneHTMLBuilder):
         """Write the metainfo file toc.ncx."""
         self.info('writing %s file...' % outname)
 
-        doctree = self.env.get_and_resolve_doctree(self.config.master_doc,
-            self, prune_toctrees=False, includehidden=False)
-        refnodes = self.get_refnodes(doctree, [])
-        if refnodes:
+        if self.config.epub_tocscope == 'default':
+            doctree = self.env.get_and_resolve_doctree(self.config.master_doc,
+                self, prune_toctrees=False, includehidden=False)
+            refnodes = self.get_refnodes(doctree, [])
             self.toc_add_files(refnodes)
         else:
+            # 'includehidden'
             refnodes = self.refnodes
         navpoints = self.build_navpoints(refnodes)
         level = max(item['level'] for item in self.refnodes)

sphinx/config.py

@@ -140,6 +140,7 @@ class Config(object):
         epub_exclude_files = ([], 'env'),
         epub_tocdepth = (3, 'env'),
         epub_tocdup = (True, 'env'),
+        epub_tocscope = ('default', 'env'),
         epub_fix_images = (False, 'env'),
         epub_max_image_width = (0, 'env'),
         epub_show_urls = ('inline', 'html'),

sphinx/quickstart.py

@@ -335,6 +335,9 @@ epub_copyright = u'%(copyright_str)s'
 # Allow duplicate toc entries.
 #epub_tocdup = True
 
+# Choose between 'default' and 'includehidden'.
+#epub_tocscope = 'default'
+
 # Fix unsupported image types using the PIL.
 #epub_fix_images = False