From e9f5d9666557678b9dbdbc4330cfe1c09bdafc58 Mon Sep 17 00:00:00 2001 From: Yoshiki Shibukawa Date: Sat, 16 Jul 2016 00:11:25 +0900 Subject: [PATCH 1/5] fix make clean abort when build dir contains files like .DS_Store. --- CHANGES | 2 +- sphinx/make_mode.py | 5 ++--- sphinx/util/osutil.py | 7 +++++++ 3 files changed, 10 insertions(+), 4 deletions(-) diff --git a/CHANGES b/CHANGES index bdabdc16a..7c09119b1 100644 --- a/CHANGES +++ b/CHANGES @@ -5,7 +5,7 @@ Bugs fixed ---------- * applehelp: Sphinx crashes if ``hiutil`` or ``codesign`` commands not found - +* Fix ``make clean`` abort issue when build dir contains regular files like ``DS_Store``. Release 1.4.5 (released Jul 13, 2016) ===================================== diff --git a/sphinx/make_mode.py b/sphinx/make_mode.py index 67ba9e1e1..75c5ab8b2 100644 --- a/sphinx/make_mode.py +++ b/sphinx/make_mode.py @@ -18,13 +18,12 @@ from __future__ import print_function import os import sys -import shutil from os import path from subprocess import call import sphinx from sphinx.util.console import bold, blue -from sphinx.util.osutil import cd +from sphinx.util.osutil import cd, rmtree proj_name = os.getenv('SPHINXPROJ', '') @@ -75,7 +74,7 @@ class Make(object): return 1 print("Removing everything under %r..." % self.builddir) for item in os.listdir(self.builddir): - shutil.rmtree(self.builddir_join(item)) + rmtree(self.builddir_join(item)) def build_help(self): print(bold("Sphinx v%s" % sphinx.__display_version__)) diff --git a/sphinx/util/osutil.py b/sphinx/util/osutil.py index 585dc6104..b416a8c1f 100644 --- a/sphinx/util/osutil.py +++ b/sphinx/util/osutil.py @@ -213,3 +213,10 @@ def cd(target_dir): yield finally: os.chdir(cwd) + + +def rmtree(path): + if os.path.isdir(path): + shutil.rmtree(path) + else: + os.remove(path) From 06a861703d0faf48618f22f09cec0e85ae5c0f82 Mon Sep 17 00:00:00 2001 From: Yoshiki Shibukawa Date: Sun, 17 Jul 2016 09:53:04 +0900 Subject: [PATCH 2/5] Reduce epub checker warnings/errors for epub3 builder. Fix DOCTYPE to html5 and change extension from .html to .xhtml. Sphinx's documents result: before: 95 warnings& 1238 errors after: 623 errors --- doc/conf.py | 2 +- sphinx/builders/epub.py | 15 +++++++++++---- sphinx/builders/epub3.py | 4 ++++ sphinx/themes/epub/layout.html | 3 +-- 4 files changed, 17 insertions(+), 7 deletions(-) diff --git a/doc/conf.py b/doc/conf.py index 753ffab4c..f3bf569f8 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -47,7 +47,7 @@ epub_fix_images = False epub_max_image_width = 0 epub_show_urls = 'inline' epub_use_index = False -epub_guide = (('toc', 'contents.html', u'Table of Contents'),) +epub_guide = (('toc', 'contents.xhtml', u'Table of Contents'),) latex_documents = [('contents', 'sphinx.tex', 'Sphinx Documentation', 'Georg Brandl', 'manual', 1)] diff --git a/sphinx/builders/epub.py b/sphinx/builders/epub.py index faa587a17..67b349fc7 100644 --- a/sphinx/builders/epub.py +++ b/sphinx/builders/epub.py @@ -113,7 +113,7 @@ COVER_TEMPLATE = u'''\ ''' -COVERPAGE_NAME = u'epub-cover.html' +COVERPAGE_NAME = u'epub-cover.xhtml' FILE_TEMPLATE = u'''\ +''' + LINK_TARGET_TEMPLATE = u' [%(uri)s]' FOOTNOTE_LABEL_TEMPLATE = u'#%d' @@ -143,7 +147,7 @@ GUIDE_TITLES = { } MEDIA_TYPES = { - '.html': 'application/xhtml+xml', + '.xhtml': 'application/xhtml+xml', '.css': 'text/css', '.png': 'image/png', '.gif': 'image/gif', @@ -198,6 +202,7 @@ class EpubBuilder(StandaloneHTMLBuilder): spine_template = SPINE_TEMPLATE guide_template = GUIDE_TEMPLATE toctree_template = TOCTREE_TEMPLATE + doctype = DOCTYPE link_target_template = LINK_TARGET_TEMPLATE css_link_target_class = CSS_LINK_TARGET_CLASS guide_titles = GUIDE_TITLES @@ -207,7 +212,8 @@ class EpubBuilder(StandaloneHTMLBuilder): def init(self): StandaloneHTMLBuilder.init(self) # the output files for epub must be .html only - self.out_suffix = '.html' + self.out_suffix = '.xhtml' + self.link_suffix = '.xhtml' self.playorder = 0 self.tocid = 0 @@ -277,7 +283,7 @@ class EpubBuilder(StandaloneHTMLBuilder): """ refnodes.insert(0, { 'level': 1, - 'refuri': self.esc(self.config.master_doc + '.html'), + 'refuri': self.esc(self.config.master_doc + self.out_suffix), 'text': ssp(self.esc( self.env.titles[self.config.master_doc].astext())) }) @@ -481,6 +487,7 @@ class EpubBuilder(StandaloneHTMLBuilder): """ if pagename.startswith('genindex'): self.fix_genindex(addctx['genindexentries']) + addctx['doctype'] = self.doctype StandaloneHTMLBuilder.handle_page(self, pagename, addctx, templatename, outfilename, event_arg) diff --git a/sphinx/builders/epub3.py b/sphinx/builders/epub3.py index 0fd347735..c39d16f78 100644 --- a/sphinx/builders/epub3.py +++ b/sphinx/builders/epub3.py @@ -82,6 +82,9 @@ PACKAGE_DOC_TEMPLATE = u'''\ ''' +DOCTYPE = u''' +''' + # The epub3 publisher @@ -99,6 +102,7 @@ class Epub3Builder(EpubBuilder): navlist_template = NAVLIST_TEMPLATE navlist_indent = NAVLIST_INDENT content_template = PACKAGE_DOC_TEMPLATE + doctype = DOCTYPE # Finish by building the epub file def handle_finish(self): diff --git a/sphinx/themes/epub/layout.html b/sphinx/themes/epub/layout.html index bdbcec21d..541fcdba5 100644 --- a/sphinx/themes/epub/layout.html +++ b/sphinx/themes/epub/layout.html @@ -10,8 +10,7 @@ {%- extends "basic/layout.html" %} {%- block doctype -%} - +{{ doctype }} {%- endblock -%} {# add only basic navigation links #} {% block sidebar1 %}{% endblock %} From 62ed395f5c8c1d2afdf4d23bfae5ca48acf2dd3f Mon Sep 17 00:00:00 2001 From: Yoshiki Shibukawa Date: Sun, 17 Jul 2016 10:17:39 +0900 Subject: [PATCH 3/5] suppress search feature on epub result --- CHANGES | 5 +++++ sphinx/builders/epub.py | 3 +++ 2 files changed, 8 insertions(+) diff --git a/CHANGES b/CHANGES index 7c09119b1..348f0023b 100644 --- a/CHANGES +++ b/CHANGES @@ -6,6 +6,11 @@ Bugs fixed * applehelp: Sphinx crashes if ``hiutil`` or ``codesign`` commands not found * Fix ``make clean`` abort issue when build dir contains regular files like ``DS_Store``. +* Reduce epubcheck warnings/errors: + + * Fix DOCTYPE to html5 + * Change extension from .html to .xhtml. + * Disable search page on epub results Release 1.4.5 (released Jul 13, 2016) ===================================== diff --git a/sphinx/builders/epub.py b/sphinx/builders/epub.py index 67b349fc7..f0aa97277 100644 --- a/sphinx/builders/epub.py +++ b/sphinx/builders/epub.py @@ -189,6 +189,9 @@ class EpubBuilder(StandaloneHTMLBuilder): # don't add sidebar etc. embedded = True + # don't generate search index or include search page + search = False + mimetype_template = MIMETYPE_TEMPLATE container_template = CONTAINER_TEMPLATE toc_template = TOC_TEMPLATE From 702004acfcd7e28c451b40e810847d3c23afff60 Mon Sep 17 00:00:00 2001 From: Yoshiki Shibukawa Date: Tue, 19 Jul 2016 23:15:35 +0900 Subject: [PATCH 4/5] fix document download roles. download roles works only on html. --- doc/ext/example_google.rst | 4 +++- doc/ext/example_numpy.rst | 4 +++- 2 files changed, 6 insertions(+), 2 deletions(-) diff --git a/doc/ext/example_google.rst b/doc/ext/example_google.rst index 06508082c..a06f161b9 100644 --- a/doc/ext/example_google.rst +++ b/doc/ext/example_google.rst @@ -9,7 +9,9 @@ Example Google Style Python Docstrings :ref:`example_numpy` -Download: :download:`example_google.py ` +.. only:: builder_html + + Download: :download:`example_google.py ` .. literalinclude:: example_google.py :language: python diff --git a/doc/ext/example_numpy.rst b/doc/ext/example_numpy.rst index a3b41613e..38d3439c8 100644 --- a/doc/ext/example_numpy.rst +++ b/doc/ext/example_numpy.rst @@ -9,7 +9,9 @@ Example NumPy Style Python Docstrings :ref:`example_google` -Download: :download:`example_numpy.py ` +.. only:: builder_html + + Download: :download:`example_numpy.py ` .. literalinclude:: example_numpy.py :language: python From b7b1ac1c4d47c9a0305e03250f58e75b9b16deff Mon Sep 17 00:00:00 2001 From: Yoshiki Shibukawa Date: Tue, 19 Jul 2016 23:35:49 +0900 Subject: [PATCH 5/5] add preferred instruction to download role description --- doc/markup/inline.rst | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/doc/markup/inline.rst b/doc/markup/inline.rst index 0e825b66a..ae47f820d 100644 --- a/doc/markup/inline.rst +++ b/doc/markup/inline.rst @@ -200,6 +200,12 @@ Referencing downloadable files The ``example.py`` file will be copied to the output directory, and a suitable link generated to it. + Not to show unavailable download links, you should wrap whole paragraphs that + have this role:: + + .. only:: builder_html + + See :download:`this example script <../example.py>`. Cross-referencing figures by figure number ------------------------------------------