Merge pull request #4354 from stephenfin/builder-success-message

Add 'Builder.epilog' attribute

doc/extdev/builderapi.rst

@@ -15,6 +15,7 @@ Builder API
 
    .. autoattribute:: name
    .. autoattribute:: format
+   .. autoattribute:: epilog
    .. autoattribute:: supported_image_types
 
    These methods are predefined and will be called from the application:

sphinx/application.py

@@ -338,6 +338,13 @@ def build(self, force_all=False, filenames=None):
                                  (status, self._warncount)))
             else:
                 logger.info(bold(__('build %s.') % status))
+
+            if self.statuscode == 0 and self.builder.epilog:
+                logger.info('')
+                logger.info(self.builder.epilog % {
+                    'outdir': path.relpath(self.outdir),
+                    'project': self.config.project
+                })
         except Exception as err:
             # delete the saved env to force a fresh build next time
             envfile = path.join(self.doctreedir, ENV_PICKLE_FILENAME)

sphinx/builders/__init__.py

@@ -54,6 +54,11 @@ class Builder(object):
     name = ''  # type: unicode
     #: The builder's output format, or '' if no document output is produced.
     format = ''  # type: unicode
+    #: The message emitted upon successful build completion. This can be a
+    #: printf-style template string with the following keys: ``outdir``,
+    #: ``project``
+    epilog = ''  # type: unicode
+
     # default translator class for the builder.  This will be overrided by
     # ``app.set_translator()``.
     default_translator_class = None  # type: nodes.NodeVisitor

sphinx/builders/applehelp.py

@@ -75,6 +75,10 @@ class AppleHelpBuilder(StandaloneHTMLBuilder):
     on the ``hiutil`` command line tool.
     """
     name = 'applehelp'
+    epilog = ('The help book is in %(outdir)s.\n'
+              'Note that won\'t be able to view it unless you put it in '
+              '~/Library/Documentation/Help or install it in your application '
+              'bundle.')
 
     # don't copy the reST source
     copysource = False

sphinx/builders/changes.py

@@ -38,6 +38,7 @@ class ChangesBuilder(Builder):
     Write a summary with all versionadded/changed directives.
     """
     name = 'changes'
+    epilog = 'The overview file is in %(outdir)s.'
 
     def init(self):
         # type: () -> None

sphinx/builders/devhelp.py

@@ -43,6 +43,10 @@ class DevhelpBuilder(StandaloneHTMLBuilder):
     Builder that also outputs GNOME Devhelp file.
     """
     name = 'devhelp'
+    epilog = ('To view the help file:\n'
+              '$ mkdir -p $HOME/.local/share/devhelp/%(project)s\n'
+              '$ ln -s %(outdir)s $HOME/.local/share/devhelp/%(project)s\n'
+              '$ devhelp')
 
     # don't copy the reST source
     copysource = False

sphinx/builders/dummy.py

@@ -21,6 +21,8 @@
 
 class DummyBuilder(Builder):
     name = 'dummy'
+    epilog = 'The dummy builder generates no files.'
+
     allow_parallel = True
 
     def init(self):

sphinx/builders/epub3.py

@@ -63,6 +63,7 @@ class Epub3Builder(_epub_base.EpubBuilder):
     an epub file.
     """
     name = 'epub'
+    epilog = 'The ePub file is in %(outdir)s.'
 
     supported_remote_images = False
     template_dir = path.join(package_dir, 'templates', 'epub3')

sphinx/builders/gettext.py

@@ -214,6 +214,7 @@ class MessageCatalogBuilder(I18nBuilder):
     Builds gettext-style message catalogs (.pot files).
     """
     name = 'gettext'
+    epilog = 'The message catalogs are in %(outdir)s.'
 
     def init(self):
         # type: () -> None

sphinx/builders/html.py

@@ -153,6 +153,8 @@ class StandaloneHTMLBuilder(Builder):
     """
     name = 'html'
     format = 'html'
+    epilog = 'The HTML pages are in %(outdir)s.'
+
     copysource = True
     allow_parallel = True
     out_suffix = '.html'
@@ -1066,6 +1068,8 @@ class SingleFileHTMLBuilder(StandaloneHTMLBuilder):
     HTML page.
     """
     name = 'singlehtml'
+    epilog = 'The HTML page is in %(outdir)s.'
+
     copysource = False
 
     def get_outdated_docs(self):  # type: ignore
@@ -1328,12 +1332,14 @@ class PickleHTMLBuilder(SerializingHTMLBuilder):
     """
     A Builder that dumps the generated HTML into pickle files.
     """
+    name = 'pickle'
+    epilog = 'You can now process the pickle files in %(outdir)s.'
+
     implementation = pickle
     implementation_dumps_unicode = False
     additional_dump_args = (pickle.HIGHEST_PROTOCOL,)
     indexer_format = pickle
     indexer_dumps_unicode = False
-    name = 'pickle'
     out_suffix = '.fpickle'
     globalcontext_filename = 'globalcontext.pickle'
     searchindex_filename = 'searchindex.pickle'
@@ -1347,11 +1353,13 @@ class JSONHTMLBuilder(SerializingHTMLBuilder):
     """
     A builder that dumps the generated HTML into JSON files.
     """
+    name = 'json'
+    epilog = 'You can now process the JSON files in %(outdir)s.'
+
     implementation = jsonimpl
     implementation_dumps_unicode = True
     indexer_format = jsonimpl
     indexer_dumps_unicode = True
-    name = 'json'
     out_suffix = '.fjson'
     globalcontext_filename = 'globalcontext.json'
     searchindex_filename = 'searchindex.json'

sphinx/builders/htmlhelp.py

@@ -174,6 +174,8 @@ class HTMLHelpBuilder(StandaloneHTMLBuilder):
     index files.  Adapted from the original Doc/tools/prechm.py.
     """
     name = 'htmlhelp'
+    epilog = ('You can now run HTML Help Workshop with the .htp file in '
+              '%(outdir)s.')
 
     # don't copy the reST source
     copysource = False

sphinx/builders/latex.py

@@ -49,6 +49,12 @@ class LaTeXBuilder(Builder):
     """
     name = 'latex'
     format = 'latex'
+    epilog = 'The LaTeX files are in %(outdir)s.'
+    if os.name == 'posix':
+        epilog += ("\nRun 'make' in that directory to run these through "
+                   "(pdf)latex\n"
+                   "(use `make latexpdf' here to do that automatically).")
+
     supported_image_types = ['application/pdf', 'image/png', 'image/jpeg']
     supported_remote_images = False
     default_translator_class = LaTeXTranslator

sphinx/builders/linkcheck.py

@@ -90,6 +90,8 @@ class CheckExternalLinksBuilder(Builder):
     Checks for broken external links.
     """
     name = 'linkcheck'
+    epilog = ('Look for any errors in the above output or in '
+              '%(outdir)s/output.txt')
 
     def init(self):
         # type: () -> None

sphinx/builders/manpage.py

@@ -40,6 +40,8 @@ class ManualPageBuilder(Builder):
     """
     name = 'man'
     format = 'man'
+    epilog = 'The manual pages are in %(outdir)s.'
+
     default_translator_class = ManualPageTranslator
     supported_image_types = []  # type: List[unicode]
 

sphinx/builders/qthelp.py

@@ -108,6 +108,11 @@ class QtHelpBuilder(StandaloneHTMLBuilder):
     Builder that also outputs Qt help project, contents and index files.
     """
     name = 'qthelp'
+    epilog = ('You can now run "qcollectiongenerator" with the .qhcp '
+              'project file in %(outdir)s, like this:\n'
+              '$ qcollectiongenerator %(outdir)s/%(project)s.qhcp\n'
+              'To view the help file:\n'
+              '$ assistant -collectionFile %(outdir)s/%(project)s.qhc')
 
     # don't copy the reST source
     copysource = False

sphinx/builders/texinfo.py

@@ -9,6 +9,7 @@
     :license: BSD, see LICENSE for details.
 """
 
+import os
 from os import path
 
 from docutils import nodes
@@ -97,6 +98,12 @@ class TexinfoBuilder(Builder):
     """
     name = 'texinfo'
     format = 'texinfo'
+    epilog = 'The Texinfo files are in %(outdir)s.'
+    if os.name == 'posix':
+        epilog += ("\nRun 'make' in that directory to run these through "
+                   "makeinfo\n"
+                   "(use 'make info' here to do that automatically).")
+
     supported_image_types = ['image/png', 'image/jpeg',
                              'image/gif']
     default_translator_class = TexinfoTranslator

sphinx/builders/text.py

@@ -31,6 +31,8 @@
 class TextBuilder(Builder):
     name = 'text'
     format = 'text'
+    epilog = 'The text files are in %(outdir)s.'
+
     out_suffix = '.txt'
     allow_parallel = True
     default_translator_class = TextTranslator

sphinx/builders/xml.py

@@ -35,6 +35,8 @@ class XMLBuilder(Builder):
     """
     name = 'xml'
     format = 'xml'
+    epilog = 'The XML files are in %(outdir)s.'
+
     out_suffix = '.xml'
     allow_parallel = True
 
@@ -108,6 +110,8 @@ class PseudoXMLBuilder(XMLBuilder):
     """
     name = 'pseudoxml'
     format = 'pseudoxml'
+    epilog = 'The pseudo-XML files are in %(outdir)s.'
+
     out_suffix = '.pseudoxml'
 
     _writer_class = PseudoXMLWriter

sphinx/ext/coverage.py

@@ -50,8 +50,12 @@ def compile_regex_list(name, exps):
 
 
 class CoverageBuilder(Builder):
-
+    """
+    Evaluates coverage of code in the documentation.
+    """
     name = 'coverage'
+    epilog = ('Testing of coverage in the sources finished, look at the '
+              'results in %(outdir)s/python.txt.')
 
     def init(self):
         # type: () -> None

sphinx/ext/doctest.py

@@ -271,6 +271,8 @@ class DocTestBuilder(Builder):
     Runs test snippets in the documentation.
     """
     name = 'doctest'
+    epilog = ('Testing of doctests in the sources finished, look at the '
+              'results in %(outdir)s/output.txt.')
 
     def init(self):
         # type: () -> None