Merge branch 'u/jhpalmieri/sphinx-single-file' of git://trac.sagemath…

….org/sage into develop

src/doc/common/builder.py

@@ -155,7 +155,7 @@ def __init__(self, name, lang='en'):
 
     def _output_dir(self, type):
         """
-        Returns the directory where the output of type type is stored.
+        Returns the directory where the output of type ``type`` is stored.
         If the directory does not exist, then it will automatically be
         created.
 
@@ -1058,6 +1058,109 @@ def print_included_modules(self):
             print module_name
 
 
+
+class SingleFileBuilder(DocBuilder):
+    """
+    This is the class used to build the documentation for a single
+    user-specified file. If the file is called 'foo.py', then the
+    documentation is built in ``DOT_SAGE/docbuild/foo/``
+    """
+    def __init__(self, path):
+        """
+        INPUT:
+
+        - ``path`` - the path to the file for which documentation
+          should be built
+        """
+        self.lang = 'en'
+        self.name = 'single_file'
+
+        path = os.path.abspath(path)
+
+        # Create ~/.sage/docbuild/ and relevant subdirectories, e.g.,
+        # the static and templates directories.
+        orig_dir = os.path.join(SAGE_DOC, self.lang, self.name)
+        DOT_SAGE = os.environ['DOT_SAGE']
+
+        module_name = os.path.splitext(os.path.basename(path))[0]
+        latex_name = module_name.replace('_', r'\_')
+
+        base_dir = os.path.join(DOT_SAGE, 'docbuild', module_name)
+        try:
+            shutil.rmtree(base_dir)
+        except OSError:
+            pass
+        self.dir = os.path.join(base_dir, 'source')
+
+        mkdir(self.dir)
+        mkdir(os.path.join(self.dir, "static"))
+        mkdir(os.path.join(self.dir, "templates"))
+        # Write self.dir/conf.py
+        conf = """# -*- coding: utf-8 -*-
+
+import sys, os
+sys.path.append(os.environ['SAGE_DOC'])
+sys.path.append('%s')
+from common.conf import *
+project = u'Documentation for %s'
+release = 'unknown'
+name = u'%s'
+html_title = project
+html_short_title = project
+htmlhelp_basename = name
+
+latex_domain_indices = False
+latex_documents = [
+  ('index', name + '.tex', u'Documentation for %s',
+   u'unknown', 'manual'),
+]
+""" % (self.dir, module_name, module_name, latex_name)
+        conffile = open(os.path.join(self.dir, 'conf.py'), 'w')
+        conffile.write(conf)
+        conffile.close()
+
+        # Write self.dir/index.rst
+        module_name = os.path.splitext(os.path.basename(path))[0]
+        index = """
+.. automodule:: %s
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+""" % module_name
+        indexfile = open(os.path.join(self.dir, 'index.rst'), 'w')
+        title = 'Docs for file %s' % path
+        indexfile.write(title + '\n')
+        indexfile.write('='*len(title) + "\n\n")
+        indexfile.write('.. This file has been autogenerated.\n\n')
+        indexfile.write(index)
+        indexfile.close()
+
+        # Create link from original file to self.dir. Note that we
+        # append self.dir to sys.path in conf.py. This is reasonably
+        # safe (but not perfect), since we just created self.dir.
+        os.symlink(path, os.path.join(self.dir, os.path.basename(path)))
+
+    def _output_dir(self, type):
+        """
+        Returns the directory where the output of type type is stored.
+        If the directory does not exist, then it will automatically be
+        created.
+        """
+        base_dir = os.path.split(self.dir)[0]
+        d = os.path.join(base_dir, "output", type)
+        mkdir(d)
+        return d
+
+    def _doctrees_dir(self):
+        """
+        Returns the directory where the doctrees are stored.  If the
+        directory does not exist, then it will automatically be
+        created.
+        """
+        return self._output_dir('doctrees')
+
+
 def get_builder(name):
     """
     Returns an appropriate *Builder object for the document ``name``.
@@ -1072,6 +1175,11 @@ def get_builder(name):
         return ReferenceSubBuilder(name)
     elif name.endswith('website'):
         return WebsiteBuilder(name)
+    elif name.startswith('file='):
+        path = name[5:]
+        if path.endswith('.sage') or path.endswith('.pyx'):
+            raise NotImplementedError('Building documentation for a single file only works for Python files.')
+        return SingleFileBuilder(path)
     elif name in get_documents() or name in AllBuilder().get_all_documents():
         return DocBuilder(name)
     else:
@@ -1167,6 +1275,8 @@ def help_documents(s=u""):
         s+= "Other valid document names take the form 'reference/DIR', where\n"
         s+= "DIR is a subdirectory of SAGE_DOC/en/reference/.\n"
         s+= "This builds just the specified part of the reference manual.\n"
+    s += "DOCUMENT may also have the form 'file=/path/to/FILE', which builds\n"
+    s += "the documentation for the specified file.\n"
     return s
 
 def get_formats():