Ticket #6495: trac_6495_output_filter.patch

doc/common/builder.py

@@ -94 +94 @@
             # WEBSITESPHINXOPTS is either empty or " -A hide_pdf_links=1 "
             options += WEBSITESPHINXOPTS
 
-        build_command = 'sphinx-build'
+        build_command = 'python '+os.path.join(SAGE_DOC, 'common', 'custom-sphinx-build.py')
         build_command += ' -b %s -d %s %s %s %s'%(type, self._doctrees_dir(),
                                                   options, self.dir,
                                                   output_dir)
-        logger.warning(build_command)
+        logger.debug(build_command)
         subprocess.call(build_command, shell=True)
 
-        logger.warning("Build finished.  The built documents can be found in %s", output_dir)
+        logger.info("Build finished and can be found in %s", 
+                    output_dir.replace(SAGE_DOC+'/', ''))
         
     f.is_output_format = True
     return f

doc/common/conf.py

@@ -116 +116 @@
     refpath = 'output/html/en/reference/'
     if not app.srcdir.endswith('reference'):
         app.config.intersphinx_mapping[get_doc_abspath(refpath)] = get_doc_abspath(refpath+'objects.inv')
+
 pythonversion = sys.version.split(' ')[0]
 # Python and Sage trac ticket shortcuts. For example, :trac:`7549` .
 
@@ -609 +610 @@
     app.connect('autodoc-process-docstring', process_dollars)
     app.connect('autodoc-process-docstring', process_inherited)
     app.connect('autodoc-skip-member', skip_member)
-
+    
     # When building the standard docs, app.srcdir is set to SAGE_DOC +
     # 'LANGUAGE/DOCNAME', but when doing introspection, app.srcdir is
     # set to a temporary directory.  We don't want to use intersphinx,
@@ -625 +626 @@
         app.connect('builder-inited', set_intersphinx_mappings)
         app.connect('builder-inited', sphinx.ext.intersphinx.load_mappings)
         app.connect('builder-inited', nitpick_patch_config)
-        # Minimize GAP/libGAP RAM usage when we build the docs
-        from sage.interfaces.gap import set_gap_memory_pool_size
-        set_gap_memory_pool_size(0)  # will be rounded up to 1M
 

new file doc/common/custom-sphinx-build.py

@@ +1 @@
+"""
+This is Sage's version of the sphinx-build script
+
+Enhancements are:
+
+* import the Sage library to access the docstrings, otherwise doc
+  buliding doesn't work.
+
+* redirect stdout to our own logger, and remove some unwanted chatter.
+"""
+
+import os
+import sys
+import re
+
+
+
+useless_chatter = (
+    re.compile('^Running Sphinx v'),
+    re.compile('^loading intersphinx inventory from '),
+    re.compile('^Compiling a sub-document'),
+    )
+
+
+class SageSphinxLogger(object):
+    """
+    This implements the file object interface to serve as sys.stdout
+    replacement.
+    """
+    ansi_color = re.compile(r'\x1b\[[0-9;]*m')
+    prefix_len = 9
+
+    def __init__(self, stream, prefix):
+        self._stream = stream
+        prefix = prefix[0:self.prefix_len]
+        prefix = ('[{0:'+str(self.prefix_len)+'}]').format(prefix)
+        self._prefix = prefix
+
+    def _filter_out(self, line):
+        line = re.sub(self.ansi_color, '', line)
+        for regex in useless_chatter:
+            if regex.match(line) is not None:
+                return True
+        return False
+
+    def _log_line(self, line):
+        if self._filter_out(line):
+            return
+        self._stream.write(self._prefix + ' ' + line + '\n')
+        self._stream.flush()
+        
+    _line_buffer = ''
+    
+    def _write(self, string):
+        self._line_buffer += string
+        lines = self._line_buffer.splitlines()
+        for i, line in enumerate(lines):
+            last = (i == len(lines)-1)
+            if last and not self._line_buffer.endswith('\n'):
+                self._line_buffer = line
+                return
+            self._log_line(line)
+        self._line_buffer = ''
+                
+
+    # file object interface follows
+
+    closed = False
+    encoding = None
+    mode = 'w'
+    name = '<log>'
+    newlines = None
+    softspace = 0
+
+    def isatty(self):
+        return True
+
+    def close(self):
+        if self._line_buffer != '':
+            self._log_line(self._line_buffer)
+            self._line_buffer = ''
+
+    def flush(self):
+        self._stream.flush()
+        
+    def write(self, str):
+        self._write(str)
+        
+    def writelines(self, sequence):
+        for line in sequence:
+            self.write(line)
+    
+
+output_dir = sys.argv[-1]
+sys.stdout = SageSphinxLogger(sys.stdout, os.path.basename(output_dir))
+
+
+
+# pull in the Sage library
+import sage.all
+
+# Minimize GAP/libGAP RAM usage when we build the docs
+from sage.interfaces.gap import set_gap_memory_pool_size
+set_gap_memory_pool_size(0)  # will be rounded up to 1M
+
+if __name__ == '__main__':
+    from sphinx.cmdline import main
+    sys.exit(main(sys.argv))
+