Ticket #13679: trac_13679-single-file.patch

File trac_13679-single-file.patch, 4.9 KB (added by jhpalmieri, 9 years ago)
  • doc/common/builder.py

    # HG changeset patch
    # User J. H. Palmieri <palmieri@math.washington.edu>
    # Date 1351795854 25200
    # Node ID 177730da3474ceb296a468f664ea82ddba7f3fb4
    # Parent  846a2c9deab63a8ed165e23f30828fb6fbc790c8
    Implement 'sage -docbuild file=...'.
    
    diff --git a/doc/common/builder.py b/doc/common/builder.py
    a b  
    132132
    133133    def _output_dir(self, type):
    134134        """
    135         Returns the directory where the output of type type is stored.
     135        Returns the directory where the output of type ``type`` is stored.
    136136        If the directory does not exist, then it will automatically be
    137137        created.
    138138
     
    10221022            print module_name
    10231023       
    10241024
     1025
     1026class SingleFileBuilder(DocBuilder):
     1027    """
     1028    This is the class used to build the documentation for a single
     1029    user-specified file. If the file is called 'foo.py', then the
     1030    documentation is built in ``DOT_SAGE/docbuild/foo/``
     1031    """
     1032    def __init__(self, path):
     1033        """
     1034        INPUT:
     1035           
     1036        - ``path`` - the path to the file for which documentation
     1037          should be built
     1038        """
     1039        self.lang = 'en'
     1040        self.name = 'single_file'
     1041
     1042        path = os.path.abspath(path)
     1043
     1044        # Create ~/.sage/docbuild/ and relevant subdirectories, e.g.,
     1045        # the static and templates directories.
     1046        orig_dir = os.path.join(SAGE_DOC, self.lang, self.name)
     1047        DOT_SAGE = os.environ['DOT_SAGE']
     1048
     1049        module_name = os.path.splitext(os.path.basename(path))[0]
     1050       
     1051        base_dir = os.path.join(DOT_SAGE, 'docbuild', module_name)
     1052        try:
     1053            shutil.rmtree(base_dir)
     1054        except OSError:
     1055            pass
     1056        self.dir = os.path.join(base_dir, 'source')
     1057
     1058        mkdir(self.dir)
     1059        mkdir(os.path.join(self.dir, "static"))
     1060        mkdir(os.path.join(self.dir, "templates"))
     1061        # Write self.dir/conf.py
     1062        conf = """# -*- coding: utf-8 -*-
     1063
     1064import sys, os
     1065sys.path.append(os.environ['SAGE_DOC'])
     1066sys.path.append('%s')
     1067from common.conf import *
     1068project = u'Documentation for %s'
     1069release = 'unknown'
     1070name = u'%s'
     1071html_title = project
     1072html_short_title = project
     1073htmlhelp_basename = name
     1074
     1075latex_domain_indices = False
     1076latex_documents = [
     1077  ('index', name + '.tex', u'Documentation for %s',
     1078   u'unknown', 'manual'),
     1079]
     1080""" % (self.dir, module_name, module_name, module_name)
     1081        conffile = open(os.path.join(self.dir, 'conf.py'), 'w')
     1082        conffile.write(conf)
     1083        conffile.close()
     1084
     1085        # Write self.dir/index.rst
     1086        module_name = os.path.splitext(os.path.basename(path))[0]
     1087        index = """
     1088.. automodule:: %s
     1089   :members:
     1090   :undoc-members:
     1091   :show-inheritance:
     1092
     1093""" % module_name
     1094        indexfile = open(os.path.join(self.dir, 'index.rst'), 'w')
     1095        title = 'Docs for file %s' % path
     1096        indexfile.write(title + '\n')
     1097        indexfile.write('='*len(title) + "\n\n")
     1098        indexfile.write('.. This file has been autogenerated.\n\n')
     1099        indexfile.write(index)
     1100        indexfile.close()
     1101
     1102        # Create link from original file to self.dir. Note that we
     1103        # append self.dir to sys.path in conf.py. This is reasonably
     1104        # safe (but not perfect), since we just created self.dir.
     1105        os.symlink(path, os.path.join(self.dir, os.path.basename(path)))
     1106
     1107    def _output_dir(self, type):
     1108        """
     1109        Returns the directory where the output of type type is stored.
     1110        If the directory does not exist, then it will automatically be
     1111        created.
     1112        """
     1113        base_dir = os.path.split(self.dir)[0]
     1114        d = os.path.join(base_dir, "output", type)
     1115        mkdir(d)
     1116        return d
     1117
     1118    def _doctrees_dir(self):
     1119        """
     1120        Returns the directory where the doctrees are stored.  If the
     1121        directory does not exist, then it will automatically be
     1122        created.
     1123        """
     1124        return self._output_dir('doctrees')
     1125
     1126
    10251127def get_builder(name):
    10261128    """
    10271129    Returns an appropriate *Builder object for the document ``name``.
     
    10361138        return ReferenceSubBuilder(name)
    10371139    elif name.endswith('website'):
    10381140        return WebsiteBuilder(name)
     1141    elif name.startswith('file='):
     1142        path = name[5:]
     1143        return SingleFileBuilder(path)
    10391144    elif name in get_documents() or name in AllBuilder().get_all_documents():
    10401145        return DocBuilder(name)
    10411146    else:
     
    11301235    if 'reference' in docs:
    11311236        s+= "Other valid document names take the form 'reference/DIR', where\n"
    11321237        s+= "DIR is a subdirectory of SAGE_ROOT/devel/sage/doc/en/reference/.\n"
    1133         s+= "This builds just the specified part of the reference manual.\n"
     1238        s+= "This builds just the specified part of the reference manual.\n\n"
     1239    s += "DOCUMENT may also have the form 'file=/path/to/foo.py', which builds\n"
     1240    s += "the documentation for the specified file.\n"
    11341241    return s
    11351242
    11361243def get_formats():