Merge pull request #2926 from shibukawa/feature/epub-vertical

Epub3Builder supports vertical writing mode

CHANGES

@@ -47,6 +47,7 @@ Incompatible changes
 * `html_translator_class` is now deprecated.
   Use `Sphinx.set_translator()` API instead.
 * Drop python 3.3 support
+* Drop epub3 builder's ``epub3_page_progression_direction`` option (use ``epub3_writing_mode``).
 
 Features added
 --------------
@@ -113,6 +114,7 @@ Features added
 * #646: ``option`` directive support '.' character as a part of options
 * Add document about kindlegen and fix document structure for it.
 * #2474: Add ``intersphinx_timeout`` option to ``sphinx.ext.intersphinx``
+* #2926: EPUB3 builder supports vertical mode (``epub3_writing_mode`` option)
 
 Bugs fixed
 ----------

doc/config.rst

@@ -1460,6 +1460,30 @@ the `Dublin Core metadata <http://dublincore.org/>`_.
 
    .. versionadded:: 1.2
 
+.. confval:: epub3_writing_mode
+
+   It specifies writing direction. It can accept ``'horizontal'`` (default) and
+   ``'vertical'``
+
+   .. list-table::
+      :header-rows: 1
+      :stub-columns: 1
+
+      - * ``epub3_writing_mode``
+        * ``'horizontal'``
+        * ``'vertical'``
+      - * writing-mode [#]_
+        * ``horizontal-tb``
+        * ``vertical-rl``
+      - * page progression
+        * left to right
+        * right to left
+      - * iBook's Scroll Theme support
+        * scroll-axis is vertical.
+        * scroll-axis is horizontal.
+
+   .. [#] https://developer.mozilla.org/en-US/docs/Web/CSS/writing-mode
+
 .. confval:: epub3_page_progression_direction
 
    The global direction in which the content flows.
@@ -1471,6 +1495,9 @@ the `Dublin Core metadata <http://dublincore.org/>`_.
 
    .. versionadded:: 1.4
 
+   .. deprecated:: 1.5
+      Use ``epub3_writing_mode``.
+
 .. _latex-options:
 
 Options for LaTeX output

sphinx/builders/epub3.py

@@ -54,7 +54,7 @@ PACKAGE_DOC_TEMPLATE = u'''\
 <?xml version="1.0" encoding="UTF-8"?>
 <package xmlns="http://www.idpf.org/2007/opf" version="3.0" xml:lang="%(lang)s"
  unique-identifier="%(uid)s"
- prefix="ibooks:http://vocabulary.itunes.apple.com/rdf/ibooks/vocabulary-extensions-1.0/">
+ prefix="ibooks: http://vocabulary.itunes.apple.com/rdf/ibooks/vocabulary-extensions-1.0/">
   <metadata xmlns:opf="http://www.idpf.org/2007/opf"
         xmlns:dc="http://purl.org/dc/elements/1.1/">
     <dc:language>%(lang)s</dc:language>
@@ -70,6 +70,7 @@ PACKAGE_DOC_TEMPLATE = u'''\
     <meta property="ibooks:version">%(version)s</meta>
     <meta property="ibooks:specified-fonts">true</meta>
     <meta property="ibooks:binding">true</meta>
+    <meta property="ibooks:scroll-axis">%(ibook_scroll_axis)s</meta>
   </metadata>
   <manifest>
     <item id="ncx" href="toc.ncx" media-type="application/x-dtbncx+xml" />
@@ -110,6 +111,13 @@ class Epub3Builder(EpubBuilder):
     content_template = PACKAGE_DOC_TEMPLATE
     doctype = DOCTYPE
 
+    # Warning deprecated option
+    def init(self):
+        if self.config.epub3_page_progression_direction:
+            self.warn('epub3_page_progression_direction option is deprecated'
+                      ' from 1.5. Use epub3_writing_mode instead of this.')
+        super(Epub3Builder, self).init()
+
     # Finish by building the epub file
     def handle_finish(self):
         """Create the metainfo files and finally the epub."""
@@ -129,12 +137,41 @@ class Epub3Builder(EpubBuilder):
             files, spine, guide)
         metadata['description'] = self.esc(self.config.epub3_description)
         metadata['contributor'] = self.esc(self.config.epub3_contributor)
-        metadata['page_progression_direction'] = self.esc(
-            self.config.epub3_page_progression_direction) or 'default'
+        metadata['page_progression_direction'] = self._page_progression_direction()
+        metadata['ibook_scroll_axis'] = self._ibook_scroll_axis()
         metadata['date'] = self.esc(datetime.utcnow().strftime("%Y-%m-%dT%H:%M:%SZ"))
         metadata['version'] = self.esc(self.config.version)
         return metadata
 
+    def _page_progression_direction(self):
+        if self.config.epub3_writing_mode == 'horizontal':
+            page_progression_direction = 'ltr'
+        elif self.config.epub3_writing_mode == 'vertical':
+            page_progression_direction = 'rtl'
+        else:
+            page_progression_direction = 'default'
+        return page_progression_direction
+
+    def _ibook_scroll_axis(self):
+        if self.config.epub3_writing_mode == 'horizontal':
+            scroll_axis = 'vertical'
+        elif self.config.epub3_writing_mode == 'vertical':
+            scroll_axis = 'horizontal'
+        else:
+            scroll_axis = 'default'
+        return scroll_axis
+
+    def _css_writing_mode(self):
+        if self.config.epub3_writing_mode == 'vertical':
+            editing_mode = 'vertical-rl'
+        else:
+            editing_mode = 'horizontal-tb'
+        return editing_mode
+
+    def prepare_writing(self, docnames):
+        super(Epub3Builder, self).prepare_writing(docnames)
+        self.globalcontext['theme_writing_mode'] = self._css_writing_mode()
+
     def new_navlist(self, node, level, has_child):
         """Create a new entry in the toc from the node at given level."""
         # XXX Modifies the node
@@ -232,4 +269,5 @@ def setup(app):
 
     app.add_config_value('epub3_description', '', 'epub3', string_classes)
     app.add_config_value('epub3_contributor', 'unknown', 'epub3', string_classes)
-    app.add_config_value('epub3_page_progression_direction', 'ltr', 'epub3', string_classes)
+    app.add_config_value('epub3_writing_mode', 'horizontal', 'epub3', string_classes)
+    app.add_config_value('epub3_page_progression_direction', '', 'epub3', string_classes)

sphinx/themes/epub/static/epub.css_t

@@ -11,6 +11,17 @@
 
 /* -- main layout ----------------------------------------------------------- */
 
+{% if theme_writing_mode is defined %}
+body{
+  writing-mode: {{ theme_writing_mode }};
+  line-break: normal;
+  -epub-writing-mode: {{ theme_writing_mode }};
+  -webkit-writing-mode: {{ theme_writing_mode }};
+  -epub-line-break: normal;
+  -webkit-line-break: normal;
+}
+{% endif %}
+
 div.clearer {
     clear: both;
 }