fix CHANGES and document

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>
@@ -150,7 +150,7 @@ class Epub3Builder(EpubBuilder):
             page_progression_direction = 'rtl'
         else:
             page_progression_direction = 'default'
-        return self.esc(page_progression_direction)
+        return page_progression_direction
 
     def _ibook_scroll_axis(self):
         if self.config.epub3_writing_mode == 'horizontal':
@@ -159,7 +159,7 @@ class Epub3Builder(EpubBuilder):
             scroll_axis = 'horizontal'
         else:
             scroll_axis = 'default'
-        return self.esc(scroll_axis)
+        return scroll_axis
 
     def _css_writing_mode(self):
         if self.config.epub3_writing_mode == 'vertical':