From 229c5cfa3bb1defcb33f8f5e900382cfa300309f Mon Sep 17 00:00:00 2001
From: Yoshiki Shibukawa <shibukawa.yoshiki@dena.jp>
Date: Sun, 26 Feb 2017 21:51:03 +0900
Subject: [PATCH] Add warning messages for required EPUB3 metadata

---
 CHANGES                  |  2 ++
 doc/config.rst           |  2 +-
 sphinx/builders/epub3.py | 41 +++++++++++++++++++++++++++++++++++++++-
 tests/test_build_epub.py |  2 +-
 4 files changed, 44 insertions(+), 3 deletions(-)

diff --git a/CHANGES b/CHANGES
index 601a1932b..f91dc0cc8 100644
--- a/CHANGES
+++ b/CHANGES
@@ -71,6 +71,8 @@ Features added
   (refs: #3416)
 * Use for LuaLaTeX same default settings as for XeLaTeX (i.e. ``fontspec`` and
   ``polyglossia``). (refs: #3070, #3466)
+* #3463: Add warning messages for required EPUB3 metadata. Add default value to
+  ``epub_description`` to avoid warning like other settings.
 
 Bugs fixed
 ----------
diff --git a/doc/config.rst b/doc/config.rst
index ea3eead7a..05a25b107 100644
--- a/doc/config.rst
+++ b/doc/config.rst
@@ -1289,7 +1289,7 @@ the `Dublin Core metadata <http://dublincore.org/>`_.
 
 .. confval:: epub_description
 
-   The description of the document. The default value is ``''``.
+   The description of the document. The default value is ``'unknown'``.
 
    .. versionadded:: 1.4
 
diff --git a/sphinx/builders/epub3.py b/sphinx/builders/epub3.py
index 646ed61ac..0107e3da9 100644
--- a/sphinx/builders/epub3.py
+++ b/sphinx/builders/epub3.py
@@ -65,6 +65,7 @@ class Epub3Builder(EpubBuilder):
     def handle_finish(self):
         # type: () -> None
         """Create the metainfo files and finally the epub."""
+        self.validate_config_value()
         self.get_toc()
         self.build_mimetype(self.outdir, 'mimetype')
         self.build_container(self.outdir, 'META-INF/container.xml')
@@ -73,6 +74,44 @@ class Epub3Builder(EpubBuilder):
         self.build_toc(self.outdir, 'toc.ncx')
         self.build_epub(self.outdir, self.config.epub_basename + '.epub')
 
+    def validate_config_value(self):
+        # <package> lang attribute, dc:language
+        if not self.app.config.epub_language:
+            self.app.warn(
+                'conf value "epub_language" (or "language") '
+                'should not be empty for EPUB3')
+        # <package> unique-identifier attribute
+        if not self.app.config.epub_uid:
+            self.app.warn('conf value "epub_uid" should not be empty for EPUB3')
+        # dc:title
+        if not self.app.config.epub_title:
+            self.app.warn(
+                'conf value "epub_title" (or "html_title") '
+                'should not be empty for EPUB3')
+        # dc:creator
+        if not self.app.config.epub_author:
+            self.app.warn('conf value "epub_author" should not be empty for EPUB3')
+        # dc:contributor
+        if not self.app.config.epub_contributor:
+            self.app.warn('conf value "epub_contributor" should not be empty for EPUB3')
+        # dc:description
+        if not self.app.config.epub_description:
+            self.app.warn('conf value "epub_description" should not be empty for EPUB3')
+        # dc:publisher
+        if not self.app.config.epub_publisher:
+            self.app.warn('conf value "epub_publisher" should not be empty for EPUB3')
+        # dc:rights
+        if not self.app.config.epub_copyright:
+            self.app.warn(
+                'conf value "epub_copyright" (or "copyright")'
+                'should not be empty for EPUB3')
+        # dc:identifier
+        if not self.app.config.epub_identifier:
+            self.app.warn('conf value "epub_identifier" should not be empty for EPUB3')
+        # meta ibooks:version
+        if not self.app.config.version:
+            self.app.warn('conf value "version" should not be empty for EPUB3')
+
     def content_metadata(self):
         # type: () -> Dict
         """Create a dictionary with all metadata for the content.opf
@@ -179,7 +218,7 @@ def setup(app):
     app.setup_extension('sphinx.builders.epub')
     app.add_builder(Epub3Builder)
 
-    app.add_config_value('epub_description', '', 'epub3', string_classes)
+    app.add_config_value('epub_description', 'unknown', 'epub3', string_classes)
     app.add_config_value('epub_contributor', 'unknown', 'epub3', string_classes)
     app.add_config_value('epub_writing_mode', 'horizontal', 'epub3',
                          ENUM('horizontal', 'vertical'))
diff --git a/tests/test_build_epub.py b/tests/test_build_epub.py
index 0c9a4a60c..cf0e2857a 100644
--- a/tests/test_build_epub.py
+++ b/tests/test_build_epub.py
@@ -84,7 +84,7 @@ def test_build_epub(app):
     metadata = opf.find("./idpf:metadata")
     assert metadata.find("./dc:language").text == 'en'
     assert metadata.find("./dc:title").text == 'Python  documentation'
-    assert metadata.find("./dc:description").text is None
+    assert metadata.find("./dc:description").text == 'unknown'
     assert metadata.find("./dc:creator").text == 'unknown'
     assert metadata.find("./dc:contributor").text == 'unknown'
     assert metadata.find("./dc:publisher").text == 'unknown'