Ticket #6495: trac_6495-other-parts.patch

.hgignore

@@ -59 +59 @@
 doc/output/
 doc/en/reference/sage/
 doc/en/reference/sagenb/
+doc/en/reference/.*/sage/
+doc/en/reference/.*/sagenb/

MANIFEST.in

@@ -33 +33 @@
 include doc/fr/a_tour_of_sage/sin_plot.png
 include doc/tr/a_tour_of_sage/eigen_plot.png
 include doc/tr/a_tour_of_sage/sin_plot.png
-graft   doc/en/reference/media
+graft   doc/en/reference/*/media
 graft   doc/en/thematic_tutorials/media
 graft   doc/en/prep/media
 prune   doc/en/reference/sage

doc/common/build_options.py

@@ -17 +17 @@
 #Note that this needs to have the doctrees dir    
 ALLSPHINXOPTS   = SPHINXOPTS + " " + PAPEROPTS + " "
 WEBSITESPHINXOPTS = ""
+
+# Number of threads to use for parallel-building the documentation.
+NUM_THREADS = int(os.environ.get('SAGE_NUM_THREADS', 1))

doc/common/builder.py

@@ -11 +11 @@
 from sage.misc.cachefunc import cached_method
 from sage.misc.misc import sage_makedirs as mkdir
 
-# Read options
+# Load the options, including
+#     SAGE_DOC, LANGUAGES, SPHINXOPTS, PAPER, OMIT,
+#     PAPEROPTS, ALLSPHINXOPTS, NUM_THREADS, WEBSITESPHINXOPTS
+# from build_options.py.
 execfile(os.path.join(os.getenv('SAGE_ROOT'), 'devel', 'sage', 'doc', 'common' , 'build_options.py'))
 
 ##########################################
@@ -61 +64 @@
         raise shutil.Error(errors)
 
 
+##########################################
+#      Parallel Building Ref Manual      #
+##########################################
+def build_ref_doc(args):
+    doc = args[0]
+    lang = args[1]
+    format = args[2]
+    kwds = args[3]
+    args = args[4:]
+    getattr(ReferenceSubBuilder(doc, lang), format)(*args, **kwds)
 
 ##########################################
 #             Builders                   #
 ##########################################
+
 def builder_helper(type):
     """
     Returns a function which builds the documentation for
@@ -103 +117 @@
 
         - ``lang`` - (default "en") the language of the document.
         """
-        if '/' in name:
-            lang, name = name.split(os.path.sep)
-        self.name = name
+        doc = name.split(os.path.sep)
+
+        if doc[0] in LANGUAGES:
+            lang = doc[0]
+            doc.pop(0)
+
+        self.name = os.path.join(*doc)
         self.lang = lang
-        self.dir = os.path.join(SAGE_DOC, lang, name)
+        self.dir = os.path.join(SAGE_DOC, self.lang, self.name)
 
         #Make sure the .static and .templates directories are there
         mkdir(os.path.join(self.dir, "static"))
@@ -126 +144 @@
             sage: b._output_dir('html')
             '.../devel/sage/doc/output/html/en/tutorial'
         """
+        if type == "inventory": # put inventories in the html tree
+            type = "html"
         d = os.path.join(SAGE_DOC, "output", type, self.lang, self.name)
         mkdir(d)
         return d
@@ -156 +176 @@
             sage: import os, sys; sys.path.append(os.environ['SAGE_DOC']+'/common/'); import builder
             sage: b = builder.DocBuilder('tutorial')
             sage: b._output_formats()
-            ['changes', 'html', 'htmlhelp', 'json', 'latex', 'linkcheck', 'pickle', 'web']
+            ['changes', 'html', 'htmlhelp', 'inventory', 'json', 'latex', 'linkcheck', 'pickle', 'web']
 
         """
         #Go through all the attributes of self and check to
@@ -208 +228 @@
     latex = builder_helper('latex')
     changes = builder_helper('changes')
     linkcheck = builder_helper('linkcheck')
+    # import the customized builder for object.inv files
+    inventory = builder_helper('inventory')
+
+##########################################
+#      Parallel Building Ref Manual      #
+##########################################
+def build_other_doc(args):
+    document = args[0]
+    name = args[1]
+    kwds = args[2]
+    args = args[3:]
+    logger.warning("\nBuilding %s.\n" % document)
+    getattr(get_builder(document), name)(*args, **kwds)
 
 class AllBuilder(object):
     """
@@ -228 +261 @@
         This is the function which goes through all of the documents
         and does the actual building.
         """
-        for document in self.get_all_documents():
+        import time
+        start = time.time()
+        docs = self.get_all_documents()
+        refs = [x for x in docs if x.endswith('reference')]
+        others = [x for x in docs if not x.endswith('reference')]
+        # Build the reference manual twice to resolve references.  That is,
+        # build once with the inventory builder to construct the intersphinx
+        # inventory files, and then build the second time for real.  So the
+        # first build should be as fast as possible;
+        logger.warning("\nBuilding reference manual, first pass.\n")
+        global ALLSPHINXOPTS
+        ALLSPHINXOPTS += ' -Q -D multidoc_first_pass=1'
+        for document in refs:
+            getattr(get_builder(document), 'inventory')(*args, **kwds)
+        logger.warning("Building reference manual, second pass.\n")
+        ALLSPHINXOPTS = ALLSPHINXOPTS.replace(
+            'multidoc_first_pass=1', 'multidoc_first_pass=0')
+        ALLSPHINXOPTS = ALLSPHINXOPTS.replace('-Q', '-q') + ' '
+        for document in refs:
             getattr(get_builder(document), name)(*args, **kwds)
 
+        # build the other documents in parallel
+        from multiprocessing import Pool
+        pool = Pool(NUM_THREADS)
+        L = [(doc, name, kwds) + args for doc in others]
+        # map_async, with get to provide a timeout, handles
+        # KeyboardInterrupt correctly. apply_async does not, so don't
+        # use it.
+        pool.map_async(build_other_doc, L).get(99999)
+        pool.close()
+        pool.join()
+        logger.warning("Elapsed time: %.1f seconds."%(time.time()-start))
+        logger.warning("Done building the documentation!")
+
     def get_all_documents(self):
         """
         Returns a list of all of the documents. A document is a directory within one of 
@@ -261 +325 @@
 
         return documents
 
+
 class WebsiteBuilder(DocBuilder):
     def html(self):
         """
         After we've finished building the website index page, we copy
-        everything one directory up.
+        everything one directory up.  Then we call
+        :meth:`create_html_redirects`.
         """
         DocBuilder.html(self)
         html_output_dir = self._output_dir('html')
@@ -273 +339 @@
                  os.path.realpath(os.path.join(html_output_dir, '..')),
                  ignore_errors=False)
 
+        self.create_html_redirects()
+
+    def create_html_redirects(self):
+        """
+        Writes a number of small HTML files; these are files which
+        used to contain the main content of the reference manual
+        before before splitting the manual into multiple
+        documents. After the split, those files have moved, so in each
+        old location, write a file which redirects to the new version.
+        (This is so old URLs to pieces of the reference manual still
+        open the correct files.)
+        """
+        # The simple html template which will cause a redirect to the
+        # correct file
+        html_template = """<html><head>
+            <meta HTTP-EQUIV="REFRESH" content="0; url=%s">
+            </head><body></body></html>"""
+
+        reference_dir = os.path.abspath(os.path.join(self._output_dir('html'),
+                                                     '..', 'reference'))
+        reference_builder = ReferenceBuilder('reference')
+        refdir = os.path.join(os.environ['SAGE_DOC'], 'en', 'reference')
+        for document in reference_builder.get_all_documents(refdir):
+            #path is the directory above reference dir
+            path = os.path.abspath(os.path.join(reference_dir, '..'))
+
+            # the name of the subdocument
+            document_name = document.split('/')[1]
+
+            # the sage directory within a subdocument, for example
+            # /path/to/.../output/html/en/reference/algebras/sage
+            sage_directory = os.path.join(path, document, 'sage')
+
+            # Walk through all of the files in the sage_directory
+            for dirpath, dirnames, filenames in os.walk(sage_directory):
+                # a string like reference/algebras/sage/algebras
+                short_path = dirpath[len(path)+1:]
+
+                # a string like sage/algebras
+                shorter_path = os.path.join(*short_path.split(os.sep)[2:])
+                
+                #Make the shorter path directory
+                try:
+                    os.makedirs(os.path.join(reference_dir, shorter_path))
+                except OSError:
+                    pass
+                
+                for filename in filenames:
+                    if not filename.endswith('html'):
+                        continue
+
+                    # the name of the html file we are going to create
+                    redirect_filename = os.path.join(reference_dir, shorter_path, filename)
+
+                    # the number of levels up we need to use in the relative url
+                    levels_up = len(shorter_path.split(os.sep))
+
+                    # the relative url that we will redirect to
+                    redirect_url = "/".join(['..']*levels_up + [document_name, shorter_path, filename])
+
+                    # write the html file which performs the redirect
+                    with open(redirect_filename, 'w') as f:
+                        f.write(html_template % redirect_url)
+                
+
     def clean(self):
         """
         When we clean the output for the website index, we need to
@@ -292 +423 @@
 
         DocBuilder.clean(self)
 
-class ReferenceBuilder(DocBuilder):
+
+class ReferenceBuilder(AllBuilder):
     """
-    This the class used to build the reference manual.  It is
+    This class builds the reference manual.  It uses DocBuilder to
+    build the top-level page and ReferenceSubBuilder for each
+    sub-component.
+    """
+    def __init__(self, name, lang='en'):
+        """
+        Records the reference manual's name, in case it's not
+        identical to 'reference'.
+        """
+        AllBuilder.__init__(self)
+        doc = name.split(os.path.sep)
+
+        if doc[0] in LANGUAGES:
+            lang = doc[0]
+            doc.pop(0)
+
+        self.name = doc[0]
+        self.lang = lang
+
+    def _output_dir(self, type, lang='en'):
+        """
+        Returns the directory where the output of type type is stored.
+        If the directory does not exist, then it will automatically be
+        created.
+
+        EXAMPLES::
+
+            sage: import os, sys; sys.path.append(os.environ['SAGE_DOC']+'/common/'); import builder
+            sage: b = builder.ReferenceBuilder('reference')
+            sage: b._output_dir('html')
+            '.../devel/sage/doc/output/html/en/reference'
+        """
+        if type == "inventory": # put inventories in the html tree
+            type = "html"
+        d = os.path.join(SAGE_DOC, "output", type, lang, self.name)
+        mkdir(d)
+        return d
+
+    def _wrapper(self, format, *args, **kwds):
+        """
+        Builds reference manuals.  For each language, it builds the
+        top-level document and its components.
+        """
+        for lang in LANGUAGES:
+            refdir = os.path.join(SAGE_DOC, lang, self.name)
+            if not os.path.exists(refdir):
+                continue
+            output_dir = self._output_dir(format, lang)
+            from multiprocessing import Pool
+            pool = Pool(NUM_THREADS)
+            L = [(doc, lang, format, kwds) + args for doc in self.get_all_documents(refdir)]
+            # (See comment in AllBuilder._wrapper about using map_async
+            # instead of apply_async.)
+            pool.map_async(build_ref_doc, L).get(99999)
+            pool.close()
+            pool.join()
+            # The html refman must be build at the end to ensure correct
+            # merging of indexes and inventories.
+            getattr(DocBuilder(self.name, lang), format)(*args, **kwds)
+
+            # PDF: we need to build master index file which lists all
+            # of the PDF file.  So we create an html file, based on
+            # the file index.html from the "website" target.
+            if format == 'pdf':
+                import re
+                # First build the website page.  (This only takes a
+                # few seconds.)
+                getattr(get_builder('website'), 'html')()
+                # Copy the relevant pieces of
+                # output/html/en/website/_static to output_dir.
+                # (Don't copy all of _static to save some space: we
+                # don't need all of the MathJax stuff, and in
+                # particular we don't need the fonts.)
+                website_dir = os.path.join(SAGE_DOC, 'output', 'html',
+                                           'en', 'website')
+                static_files = ['COPYING.txt', 'basic.css', 'blank.gif',
+                         'default.css', 'doctools.js', 'favicon.ico',
+                         'file.png', 'jquery.js', 'minus.png',
+                         'pdf.png', 'plus.png', 'pygments.css',
+                         'sage.css', 'sageicon.png', 'sagelogo.png',
+                         'searchtools.js', 'sidebar.js', 'underscore.js']
+                mkdir(os.path.join(output_dir, '_static'))
+                for f in static_files:
+                    try:
+                        shutil.copyfile(os.path.join(website_dir, '_static', f),
+                                        os.path.join(output_dir, '_static', f))
+                    except IOError: # original file does not exist
+                        pass
+                # Now modify website's index.html page and write it
+                # to output_dir.
+                f = open(os.path.join(website_dir, 'index.html'))
+                html = f.read().replace('Documentation', 'Reference')
+                f.close()
+                html_output_dir = os.path.dirname(website_dir)
+                html = html.replace('http://www.sagemath.org',
+                                    os.path.join(html_output_dir, 'index.html'))
+                # From index.html, we want the preamble and the tail.
+                html_end_preamble = html.find('<h1>Sage Reference')
+                html_bottom = html.rfind('</table>') + len('</table>')
+                # For the content, we modify doc/en/reference/index.rst,
+                # which has two parts: the body and the table of contents.
+                f = open(os.path.join(SAGE_DOC, lang, 'reference', 'index.rst'))
+                rst = f.read()
+                f.close()
+                # Replace rst links with html links.  There are two forms:
+                #
+                #   `blah`__    followed by __ LINK
+                #
+                #   :doc:`blah <module/index>`
+                #
+                # Change the first form to
+                #
+                #   <a href="LINK">blah</a>
+                #
+                # Change the second form to
+                #
+                #   <a href="module/module.pdf">blah <img src="_static/pdf.png" /></a>
+                #
+                rst = re.sub('`([^`]*)`__\.\n\n__ (.*)',
+                                  r'<a href="\2">\1</a>.', rst)
+                rst = re.sub(r':doc:`([^<]*?)\s+<(.*)/index>`',
+                             r'<a href="\2/\2.pdf">\1 <img src="_static/pdf.png" /></a>',
+                             rst)
+                # Get rid of todolist and miscellaneous rst markup.
+                rst = rst.replace('.. toctree::', '')
+                rst = rst.replace(':maxdepth: 2', '')
+                rst = rst.replace('todolist', '')
+                start = rst.find('=\n') + 1
+                end = rst.find('Table of Contents')
+                # Body: add paragraph <p> markup.
+                rst_body = rst[start:end]
+                rst_body = rst_body.replace('\n\n', '</p>\n<p>')
+                start = rst.find('Table of Contents') + 2*len('Table of Contents') + 1
+                # Don't include the indices.
+                end = rst.find('Indices and Tables')
+                # TOC: change * to <li>, change rst headers to html headers.
+                rst_toc = rst[start:end]
+                rst_toc = rst_toc.replace('*', '<li>')
+                rst_toc = re.sub('\n([A-Z][a-zA-Z, ]*)\n-*\n',
+                             '</ul>\n\n\n<h2>\\1</h2>\n\n<ul>\n', rst_toc)
+                # Now write the file.
+                new_index = open(os.path.join(output_dir, 'index.html'), 'w')
+                new_index.write(html[:html_end_preamble])
+                new_index.write('<h1>' + rst[:rst.find('\n')] +
+                                ' (PDF version)'+ '</h1>')
+                new_index.write(rst_body)
+                new_index.write('<h2>Table of Contents</h2>\n\n<ul>')
+                new_index.write(rst_toc)
+                new_index.write('</ul>\n\n')
+                new_index.write(html[html_bottom:])
+                new_index.close()
+                logger.warning('''
+PDF documents have been created in subdirectories of
+
+  %s
+
+Alternatively, you can open
+
+  %s
+
+for a webpage listing all of the documents.''' % (output_dir,
+                                                 os.path.join(output_dir,
+                                                              'index.html')))
+
+    def get_all_documents(self, refdir):
+        """
+        Returns a list of all reference manual components to build.
+        We add a component name if it's a subdirectory of the manual's
+        directory and contains a file named 'index.rst'.
+
+        EXAMPLES::
+
+            sage: import os, sys; sys.path.append(os.environ['SAGE_DOC']+'/common/'); import builder
+            sage: b = builder.ReferenceBuilder('reference')
+            sage: refdir = os.path.join(os.environ['SAGE_DOC'], 'en', b.name)
+            sage: b.get_all_documents(refdir)
+            ['reference/algebras', 'reference/arithgroup', ..., 'reference/tensor']
+        """
+        documents = []
+
+        for doc in os.listdir(refdir):
+            if os.path.exists(os.path.join(refdir, doc, 'index.rst')):
+                documents.append(os.path.join(self.name, doc))
+
+        return sorted(documents)
+
+
+class ReferenceSubBuilder(DocBuilder):
+    """
+    This class builds sub-components of the reference manual.  It is
     resposible for making sure the auto generated ReST files for the
     Sage library are up to date.
 
@@ -424 +745 @@
         except IOError as err:
             logger.debug("Failed to open Sphinx environment: %s", err)
             pass
-                                           
+
     def update_mtimes(self):
         """
         Updates the modification times for ReST files in the Sphinx
@@ -593 +914 @@
 
             sage: import os, sys; sys.path.append(os.environ['SAGE_DOC']+'/common/'); import builder
             sage: import builder
-            sage: builder.ReferenceBuilder("reference").auto_rest_filename("sage.combinat.partition")
+            sage: builder.ReferenceSubBuilder("reference").auto_rest_filename("sage.combinat.partition")
             '.../devel/sage/doc/en/reference/sage/combinat/partition.rst'
         """
         return self.dir + os.path.sep + module_name.replace('.',os.path.sep) + '.rst'
@@ -705 +1026 @@
 
 def get_builder(name):
     """
-    Returns a either a AllBuilder or DocBuilder object depending
-    on whether ``name`` is 'all' or not.  These are the objects
-    which do all the real work in building the documentation.
+    Returns an appropriate *Builder object for the document ``name``.
+    DocBuilder and its subclasses do all the real work in building the
+    documentation.
     """
     if name == 'all':
         return AllBuilder()
     elif name.endswith('reference'):
         return ReferenceBuilder(name)
+    elif 'reference' in name:
+        return ReferenceSubBuilder(name)
     elif name.endswith('website'):
         return WebsiteBuilder(name)
     elif name in get_documents() or name in AllBuilder().get_all_documents():
@@ -802 +1125 @@
     shortcut 'all' for all documents, available to the Sage
     documentation builder.
     """
+    docs = get_documents()
     s += "DOCUMENTs:\n"
-    s += format_columns(get_documents() + ['all  (!)'])
-    s += "(!) Builds everything.\n"
+    s += format_columns(docs + ['all  (!)'])
+    s += "(!) Builds everything.\n\n"
+    if 'reference' in docs:
+        s+= "Other valid document names take the form 'reference/DIR', where\n"
+        s+= "DIR is a subdirectory of SAGE_ROOT/devel/sage/doc/en/reference/.\n"
+        s+= "This builds just the specified part of the reference manual.\n"
     return s
 
 def get_formats():

doc/common/conf.py

@@ -19 +19 @@
 
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = ['sage_autodoc',  'sphinx.ext.graphviz',
+extensions = ['inventory_builder', 'multidocs',
+              'sage_autodoc',  'sphinx.ext.graphviz',
               'sphinx.ext.inheritance_diagram', 'sphinx.ext.todo',
               'sphinx.ext.extlinks']
 # We do *not* fully initialize intersphinx since we call it by hand
@@ -124 +125 @@
     'trac': ('http://trac.sagemath.org/%s', 'trac ticket #'),
     'wikipedia': ('http://en.wikipedia.org/wiki/%s', 'Wikipedia article ')}
 
+# By default document are not master.
+multidocs_is_master = True
+
 # Options for HTML output
 # -----------------------
 
@@ -213 +217 @@
 # If false, no module index is generated.
 #html_use_modindex = True
 
+# A list of prefixes that are ignored for sorting the Python module index ( if
+# this is set to ['foo.'], then foo.bar is shown under B, not F). Works only
+# for the HTML builder currently.
+modindex_common_prefix = ['sage.']
+
 # If false, no index is generated.
 #html_use_index = True
 

new file doc/common/inventory_builder.py

@@ +1 @@
+# -*- coding: utf-8 -*-
+"""
+    inventory builder
+    ~~~~~~~~~~~~~~~~~
+
+    A customized HTML builder which only generates intersphinx "object.inv"
+    inventory files and pickle files. The documentation files are not written.
+"""
+from sphinx.builders.html import StandaloneHTMLBuilder
+from sphinx.util.console import bold
+
+class InventoryBuilder(StandaloneHTMLBuilder):
+    """
+    A customized HTML builder which only generates intersphinx "object.inv"
+    inventory files and pickle files. The documentation files are not written.
+    """
+    name = "inventory"
+
+    def write_doc(self, docname, doctree):
+        """
+        Don't write any doc
+        """
+
+    def finish(self):
+        """
+        Only write the inventory files.
+        """
+        self.write_buildinfo()
+        self.dump_inventory()
+
+    def removed_method_error(self):
+        """
+        Raise an error if this method is called.
+
+        This is just for making sure that some writer methods are indeed
+        deactivated.
+        """
+        raise RuntimeError, "This function shouldn't be called in \"%s\" builder"%(self.name)
+
+    copy_image_files = removed_method_error
+    copy_download_files = removed_method_error
+    copy_static_files = removed_method_error
+    handle_finish = removed_method_error
+
+def setup(app):
+    app.add_builder(InventoryBuilder)
+

new file doc/common/multidocs.py

@@ +1 @@
+# -*- coding: utf-8 -*-
+"""
+    multi documentation in Sphinx
+    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+    The goal of this extension is to manage a multi documentation in Sphinx.
+    To be able to compile Sage's huge documentation in parallel, the
+    documentation is cut into a bunch of independent documentations called
+    "subdocs", which are compiled separately. There is a master document which
+    points to all the subdocs. The intersphinx extension ensures that the
+    cross-link between the subdocs are correctly resolved. However some work
+    is needed to build a global index. This is the goal of multidocs.
+
+    More precisely this extension ensures the correct merging of
+    - the todo list if this extension is activated;
+    - the python indexes;
+    - the list of python modules;
+    - the javascript index;
+    - the citations.
+"""
+import cPickle, os, sys
+import sphinx
+from sphinx.util.console import bold
+
+
+CITE_FILENAME = 'citations.pickle'
+
+
+def merge_environment(app, env):
+    """
+    Merges the following attributes of the sub-docs environment into the main
+    environment:
+    - todo_all_todos              # ToDo's
+    - indexentries                # global python index
+    - all_docs                    # needed by the js index
+    - citations                   # citations
+
+    - domaindata['py']['modules'] # list of python modules
+    """
+    app.info(bold('Merging environment/index files...'))
+    for curdoc in app.env.config.multidocs_subdoc_list:
+        app.info("    %s:"%curdoc, nonl=1)
+        docenv = get_env(app, curdoc)
+        if docenv is not None:
+            fixpath = lambda path: os.path.join(curdoc, path)
+            app.info(" %s todos, %s index, %s citations"%(
+                    len(docenv.todo_all_todos),
+                    len(docenv.indexentries),
+                    len(docenv.citations)
+                    ), nonl=1)
+
+            # merge the todo links
+            for dct in docenv.todo_all_todos:
+                dct['docname']=fixpath(dct['docname'])
+            env.todo_all_todos += docenv.todo_all_todos
+            # merge the html index links
+            newindex = {}
+            for ind in docenv.indexentries:
+                if ind.startswith('sage/'):
+                    newind = fixpath(ind)
+                    newindex[newind] = docenv.indexentries[ind]
+                else:
+                    newindex[ind] = docenv.indexentries[ind]
+            env.indexentries.update(newindex)
+            # merge the all_docs links, needed by the js index
+            newalldoc = {}
+            for ind in docenv.all_docs:
+                newalldoc[fixpath(ind)]=docenv.all_docs[ind]
+            env.all_docs.update(newalldoc)
+            # needed by env.check_consistency (sphinx.environement, line 1734)
+            for ind in newalldoc:
+                env.metadata[ind] = {}
+            # merge the citations
+            newcite = {}
+            for ind, (path, tag) in docenv.citations.iteritems():
+                # TODO: Warn on conflicts
+                newcite[ind]=(fixpath(path), tag)
+            env.citations.update(newcite)
+            # merge the py:module indexes
+            newmodules = {}
+            for ind,(modpath,v1,v2,v3) in (
+                docenv.domaindata['py']['modules'].iteritems()):
+                newmodules[ind] = (fixpath(modpath),v1,v2,v3)
+            env.domaindata['py']['modules'].update(newmodules)
+            app.info(", %s modules"%(len(newmodules)))
+    app.info('... done (%s todos, %s index, %s citations, %s modules)'%(
+            len(env.todo_all_todos),
+            len(env.indexentries),
+            len(env.citations),
+            len(env.domaindata['py']['modules'])))
+    write_citations(app, env.citations)
+
+def get_env(app, curdoc):
+    """
+    Get the environment of a sub-doc from the pickle
+    """
+    from sphinx.application import ENV_PICKLE_FILENAME
+    filename = os.path.join(
+        app.env.doctreedir, curdoc, ENV_PICKLE_FILENAME)
+    try:
+        f = open(filename, 'rb')
+    except IOError:
+        app.info("")
+        app.warn("Unable to fetch %s "%filename)
+        return None
+    docenv = cPickle.load(f)
+    f.close()
+    return docenv
+
+def merge_js_index(app):
+    """
+    Merge the JS indexes of the sub-docs into the main JS index
+    """
+    app.info('')
+    app.info(bold('Merging js index files...'))
+    mapping = app.builder.indexer._mapping
+    for curdoc in app.env.config.multidocs_subdoc_list:
+        app.info("    %s:"%curdoc, nonl=1)
+        fixpath = lambda path: os.path.join(curdoc, path)
+        index = get_js_index(app, curdoc)
+        if index is not None:
+            # merge the mappings
+            app.info(" %s js index entries"%(len(index._mapping)))
+            for (ref, locs) in index._mapping.iteritems():
+                newmapping = set(map(fixpath, locs))
+                if ref in mapping:
+                    newmapping = mapping[ref] | newmapping
+                mapping[unicode(ref)] = newmapping
+            # merge the titles
+            titles = app.builder.indexer._titles
+            for (res, title) in index._titles.iteritems():
+                titles[fixpath(res)] = title
+            # TODO: merge indexer._objtypes, indexer._objnames as well
+
+            # Setup source symbolic links
+            dest = os.path.join(app.outdir, "_sources", curdoc)
+            if not os.path.exists(dest):
+                os.symlink(os.path.join("..", curdoc, "_sources"), dest)
+    app.info('... done (%s js index entries)'%(len(mapping)))
+    app.info(bold('Writing js search indexes...'), nonl=1)
+    return [] # no extra page to setup
+
+def get_js_index(app, curdoc):
+    """
+    Get the JS index of a sub-doc from the file
+    """
+    from sphinx.search import IndexBuilder, languages
+    # FIXME: find the correct lang
+    indexer = IndexBuilder(app.env, 'en',
+                           app.config.html_search_options)
+    indexfile = os.path.join(app.outdir, curdoc, 'searchindex.js')
+    try:
+        f = open(indexfile, 'rb')
+    except IOError:
+        app.info("")
+        app.warn("Unable to fetch %s "%indexfile)
+        return None
+    indexer.load(f, sphinx.search.js_index)
+    f.close()
+    return indexer
+
+
+mustbefixed = ['search', 'genindex', 'genindex-all'
+               'py-modindex', 'searchindex.js']
+def fix_path_html(app, pagename, templatename, ctx, event_arg):
+    """
+    Fixes the context so that the files
+    - search.html
+    - genindex.html
+    - py-modindex.html
+    point to the right place, that is in
+        reference/
+    instead of
+        reference/subdocument
+    """
+    # sphinx/builder/html.py line 702
+    # def pathto(otheruri, resource=False,
+    #            baseuri=self.get_target_uri(pagename)):
+    old_pathto = ctx['pathto']
+    def sage_pathto(otheruri, *args, **opts):
+        if otheruri in mustbefixed:
+            otheruri = os.path.join("..", otheruri)
+        return old_pathto(otheruri, *args, **opts)
+    ctx['pathto'] = sage_pathto
+
+
+def write_citations(app, citations):
+    """
+    Pickle the citation in a file
+    """
+    import cPickle
+    file = open(os.path.join(app.outdir, CITE_FILENAME), 'wb')
+    cPickle.dump(citations, file)
+    file.close()
+    app.info("Saved pickle file: %s"%CITE_FILENAME)
+
+
+def fetch_citation(app, env):
+    """
+    Fetch the global citation index from the refman to allow for cross
+    references.
+    """
+    app.builder.info(bold('loading cross citations... '), nonl=1)
+    filename = os.path.join(app.outdir, '..', CITE_FILENAME)
+    if not os.path.exists(filename):
+        return
+    import cPickle
+    file = open(filename, 'rb')
+    try:
+        cache = cPickle.load(file)
+    except:
+        app.warn("Cache file '%s' is corrupted; ignoring it..."% filename)
+        return
+    else:
+        app.builder.info("done (%s citations)."%len(cache))
+    finally:
+        file.close()
+    cite = env.citations
+    for ind, (path, tag) in cache.iteritems():
+        if ind not in cite: # don't override local citation
+            cite[ind]=(os.path.join("..", path), tag)
+
+def init_subdoc(app):
+    """
+    Init the merger depending on if we are compiling a subdoc or the master
+    doc itself.
+    """
+    if app.config.multidocs_is_master:
+        app.info(bold("Compiling the master document"))
+        app.connect('env-updated', merge_environment)
+        app.connect('html-collect-pages', merge_js_index)
+        if app.config.multidocs_subdoc_list:
+            # Master file with indexes computed by merging indexes:
+            # Monkey patch index fetching to silence warning about broken index
+            def load_indexer(docnames):
+                app.builder.info(bold('Skipping loading of indexes'), nonl=1)
+            app.builder.load_indexer = load_indexer
+
+    else:
+        app.info(bold("Compiling a sub-document"))
+        app.connect('env-updated', fetch_citation)
+        app.connect('html-page-context', fix_path_html)
+
+        # Monkey patch copy_static_files to make a symlink to "../"
+        def link_static_files():
+            """
+            Instead of copying static files, make a link to the master static file.
+            See sphinx/builder/html.py line 536::
+
+                class StandaloneHTMLBuilder(Builder):
+                [...]
+                    def copy_static_files(self):
+                    [...]
+            """
+            app.builder.info(bold('linking _static directory.'))
+            static_dir = os.path.join(app.builder.outdir, '_static')
+            master_static_dir = os.path.join('..', '_static')
+            if not os.path.isdir(static_dir):
+                os.symlink(master_static_dir, static_dir)
+
+        app.builder.copy_static_files = link_static_files
+
+    if app.config.multidoc_first_pass == 1:
+        app.config.intersphinx_mapping = {}
+
+
+def setup(app):
+    app.add_config_value('multidocs_is_master', True, True)
+    app.add_config_value('multidocs_subdoc_list', [], True)
+    app.add_config_value('multidoc_first_pass', 0, False)   # 1 = deactivate the loading of the inventory
+    app.connect('builder-inited', init_subdoc)

doc/common/themes/sage/layout.html

@@ -7 +7 @@
     {% if pathto(master_doc).endswith('.html') %}
       <a href="{{ '../' + pathto(master_doc) }}"><img src="{{ pathto('_static/sagelogo.png', 1) }}" style="vertical-align: middle" title="Sage Logo"></a>
     {% else %}
-      <a href="{{ '../' + pathto(master_doc) + 'index.html' }}"><img src="{{ pathto('_static/sagelogo.png', 1) }}" style="vertical-align: middle" title="Sage Logo"></a>
+      <a href="{{ '../' + pathto(master_doc, 1) + '.html' }}"><img src="{{ pathto('_static/sagelogo.png', 1) }}" style="vertical-align: middle" title="Sage Logo"></a>
     {% endif %}
   {% endif %}
   {{ super() }}

new file doc/common/themes/sageref/layout.html

@@ +1 @@
+{% extends "basic/layout.html" %}
+
+{% block rootrellink %}
+  {% if docstitle.startswith('Sage Documentation') %}
+    <a href="http://www.sagemath.org"><img src="{{ pathto('_static/sagelogo.png', 1) }}" style="vertical-align: middle" title="Sage Logo"></a>
+  {% else %}
+    {% if pathto(master_doc).endswith('.html') %}
+      <a href="{{ '../../' + pathto(master_doc) }}"><img src="{{ pathto('_static/sagelogo.png', 1) }}" style="vertical-align: middle" title="Sage Logo"></a>
+    {% else %}
+      <a href="{{ '../../' + pathto(master_doc,1) + '.html' }}"><img src="{{ pathto('_static/sagelogo.png', 1) }}" style="vertical-align: middle" title="Sage Logo"></a>
+      <a href="{{ '../' + 'index.html' }}"> Sage Reference Manual </a> &raquo;
+    {% endif %}
+  {% endif %}
+  {{ super() }}
+{% endblock %}
+
+{% block extrahead %}
+    <link rel="icon" href="{{ pathto('_static/sageicon.png', 1) }}" type="image/x-icon" />
+{% endblock %}
+
+{%- block footer %}
+    {{ super() }}
+    <script type="text/javascript">
+/*global jQuery, window */
+/* Sphinx sidebar toggle.  Putting this code at the end of the body
+ * enables the toggle for the live, static, and offline docs.  Note:
+ * sage.misc.html.math_parse() eats jQuery's dollar-sign shortcut. */
+var jq = jQuery;  
+jq(document).ready(function () {
+    var bar, bod, bg, fg, key, tog, wid_old, wid_new, resize, get_state, set_state;
+    bod = jq('div.bodywrapper');
+    bar = jq('div.sphinxsidebar');
+    tog = jq('<div class="sphinxsidebartoggle"></div>');
+    
+    /* Delayed resize helper.  Not perfect but good enough. */
+    resize = function () {
+        setTimeout(function () {
+            tog.height(bod.height());
+        }, 100);
+    };
+    jq(window).resize(function () {
+        resize();
+    });
+    
+    /* Setup and add the toggle. See Sphinx v0.5.1 default.css. */
+    fg = jq('div.sphinxsidebar p a').css('color') || 'rgb(152, 219, 204)';
+    bg = jq('div.document').css('background-color') || 'rgb(28, 78, 99)';
+    wid_old = '230px';
+    wid_new = '5px';
+    tog.css('background-color', bg)
+        .css('border-width', '0px')
+        .css('border-right', wid_new + ' ridge ' + bg)
+        .css('cursor', 'pointer')
+        .css('position', 'absolute')
+        .css('left', '-' + wid_new)
+        .css('top', '0px')
+        .css('width', wid_new);
+    bod.css('position', 'relative');
+    bod.prepend(tog);
+    resize();
+    
+    /* Cookie helpers. */
+    key = 'sphinxsidebar=';
+    set_state = function (s) {
+        var date = new Date();
+        /* Expiry in 7 days. */
+        date.setTime(date.getTime() + (7 * 24 * 3600 * 1000));
+        document.cookie = key + encodeURIComponent(s) + '; expires=' +
+            date.toUTCString() + '; path=/';
+    };
+    get_state = function () {
+        var i, c, crumbs = document.cookie.split(';');
+        for (i = 0; i < crumbs.length; i += 1) {
+            c = crumbs[i].replace(/^\s+/, '');
+            if (c.indexOf(key) === 0) {
+                return decodeURIComponent(c.substring(key.length, c.length));
+            }
+        }
+        return null;
+    };
+    
+    /* Event handlers. */
+    tog.mouseover(function (ev) {
+        tog.css('border-right-color', fg);
+    }).mouseout(function (ev) {
+        tog.css('border-right-color', bg);
+    }).click(function (ev) {
+        if (bod.hasClass('wide')) {
+            bod.removeClass('wide');
+            bod.css('margin-left', wid_old);
+            bar.css('width', wid_old);
+            bar.show();
+            set_state('visible');
+        } else {
+            set_state('hidden');
+            bar.hide();
+            bar.css('width', '0px');
+            bod.css('margin-left', wid_new);
+            bod.addClass('wide');
+        }
+        resize();
+    });
+    
+    /* Hide the normally visible sidebar? */
+    if (get_state() === 'hidden') {
+        tog.trigger('click');
+    } else {
+        set_state('visible');
+    }
+});
+    </script>
+{%- endblock %}
+
+<!-- This macro block for the sidebar is heavily borrowed from the basic -->
+<!-- theme of Sphinx 0.6.3. In particular, we borrowed from the file -->
+<!-- themes/basic/layout.html distributed with Sphinx 0.6.3. -->
+{%- macro sidebar() %}
+      {%- if not embedded %}{% if not theme_nosidebar|tobool %}
+      <div class="sphinxsidebar">
+        <div class="sphinxsidebarwrapper">
+          {%- block sidebarlogo %}
+          {%- if logo %}
+            <p class="logo"><a href="{{ pathto(master_doc) }}">
+              <img class="logo" src="{{ pathto('_static/' + logo, 1) }}" alt="Logo"/>
+            </a></p>
+          {%- endif %}
+          {%- endblock %}
+          {%- block sidebartoc %}
+          {%- if display_toc %}
+            <h3><a href="{{ pathto(master_doc) }}">{{ _('Table Of Contents') }}</a></h3>
+            {{ toc }}
+          {%- endif %}
+          {%- endblock %}
+          {%- block sidebarrel %}
+          {%- if prev %}
+            <h4>{{ _('Previous topic') }}</h4>
+            <p class="topless"><a href="{{ prev.link|e }}"
+                                  title="{{ _('previous chapter') }}">{{ prev.title }}</a></p>
+          {%- endif %}
+          {%- if next %}
+            <h4>{{ _('Next topic') }}</h4>
+            <p class="topless"><a href="{{ next.link|e }}"
+                                  title="{{ _('next chapter') }}">{{ next.title }}</a></p>
+          {%- endif %}
+          {%- endblock %}
+          {%- block sidebarsourcelink %}
+          {%- if show_source and has_source and sourcename %}
+            <h3>{{ _('This Page') }}</h3>
+            <ul class="this-page-menu">
+              <li><a href="{{ pathto('_sources/' + sourcename, true)|e }}"
+                     rel="nofollow">{{ _('Show Source') }}</a></li>
+            </ul>
+          {%- endif %}
+          {%- endblock %}
+          {%- if customsidebar %}
+          {% include customsidebar %}
+          {%- endif %}
+          {%- block sidebarsearch %}
+          {%- if pagename != "search" %}
+          <div id="searchbox" style="display: none">
+            <h3>{{ _('Quick search') }}</h3>
+              <form class="search" action="{{ pathto('search') }}" method="get">
+                <input type="text" name="q" size="18" />
+                <!-- The shading of the "Go" button should be consistent -->
+                <!-- with the colour of the header and footer. See the file -->
+                <!-- doc/common/themes/sage/theme.conf for colours used by -->
+                <!-- the Sage theme. -->
+                <input type="submit" style="background-color: #B8B9F6" value="{{ _('Go') }}" />
+                <input type="hidden" name="check_keywords" value="yes" />
+                <input type="hidden" name="area" value="default" />
+              </form>
+              <p class="searchtip" style="font-size: 90%">
+              {{ _('Enter search terms or a module, class or function name.') }}
+              </p>
+          </div>
+          <script type="text/javascript">$('#searchbox').show(0);</script>
+          {%- endif %}
+          {%- endblock %}
+        </div>
+      </div>
+      {%- endif %}{% endif %}
+{%- endmacro %}

new file doc/common/themes/sageref/static/mathjax_sage.js_t

@@ +1 @@
+MathJax.Hub.Config({
+  imageFont: null,
+  tex2jax: {
+    inlineMath: [['$','$'],['\\(','\\)']],
+    processEscapes: true,
+  },
+  styles: {
+    ".MathJax .mo, .MathJax .mi": {
+      color: "inherit ! important"
+    }
+  },
+  TeX: {
+    Macros: {
+     {{ theme_mathjax_macros|join(',\n') }}
+    }
+  }
+});
+
+// This path is a little funny because we have to load our local
+// config file as '../mathjax_sage' in the theme conf.py
+MathJax.Ajax.loadComplete("[MathJax]/config/../mathjax_sage.js")

new file doc/common/themes/sageref/static/sage.css_t

@@ +1 @@
+/**
+ * Sage stylesheet theme. This stylesheet is heavily borrowed from the
+ * Sphinx stylesheet default theme distributed as the file
+ * themes/default/static/default.css_t in Sphinx 0.6.3.
+ */
+
+@import url("basic.css");
+
+/* -- page layout ----------------------------------------------------------- */
+
+body {
+    font-family: {{ theme_bodyfont }};
+    font-size: 100%;
+    background-color: {{ theme_footerbgcolor }};
+    color: #000;
+    margin: 0;
+    padding: 0;
+}
+
+div.document {
+    background-color: {{ theme_sidebarbgcolor }};
+}
+
+div.documentwrapper {
+    float: left;
+    width: 100%;
+}
+
+div.bodywrapper {
+    margin: 0 0 0 230px;
+}
+
+div.body {
+    background-color: {{ theme_bgcolor }};
+    color: {{ theme_textcolor }};
+    padding: 0 20px 30px 20px;
+}
+
+{%- if theme_rightsidebar|tobool %}
+div.bodywrapper {
+    margin: 0 230px 0 0;
+}
+{%- endif %}
+
+div.footer {
+    color: {{ theme_footertextcolor }};
+    width: 100%;
+    padding: 9px 0 9px 0;
+    text-align: center;
+    font-size: 75%;
+}
+
+div.footer a {
+    color: {{ theme_footertextcolor }};
+    text-decoration: underline;
+}
+
+div.related {
+    background-color: {{ theme_relbarbgcolor }};
+    line-height: 30px;
+    color: {{ theme_relbartextcolor }};
+}
+
+div.related a {
+    color: {{ theme_relbarlinkcolor }};
+}
+
+div.sphinxsidebar {
+    {%- if theme_stickysidebar|tobool %}
+    top: 30px;
+    margin: 0;
+    position: fixed;
+    overflow: auto;
+    height: 100%;
+    {%- endif %}
+    {%- if theme_rightsidebar|tobool %}
+    float: right;
+    {%- if theme_stickysidebar|tobool %}
+    right: 0;
+    {%- endif %}
+    {%- endif %}
+}
+
+{%- if theme_stickysidebar|tobool %}
+/* this is nice, but it it leads to hidden headings when jumping
+   to an anchor */
+/*
+div.related {
+    position: fixed;
+}
+
+div.documentwrapper {
+    margin-top: 30px;
+}
+*/
+{%- endif %}
+
+div.sphinxsidebar h3 {
+    font-family: {{ theme_headfont }};
+    color: {{ theme_sidebartextcolor }};
+    font-size: 1.4em;
+    font-weight: normal;
+    margin: 0;
+    padding: 0;
+}
+
+div.sphinxsidebar h3 a {
+    color: {{ theme_sidebartextcolor }};
+}
+
+div.sphinxsidebar h4 {
+    font-family: {{ theme_headfont }};
+    color: {{ theme_sidebartextcolor }};
+    font-size: 1.3em;
+    font-weight: normal;
+    margin: 5px 0 0 0;
+    padding: 0;
+}
+
+div.sphinxsidebar p {
+    color: {{ theme_sidebartextcolor }};
+}
+
+div.sphinxsidebar p.topless {
+    margin: 5px 10px 10px 10px;
+}
+
+div.sphinxsidebar ul {
+    margin: 10px;
+    padding: 0;
+    color: {{ theme_sidebartextcolor }};
+}
+
+div.sphinxsidebar a {
+    color: {{ theme_sidebarlinkcolor }};
+}
+
+div.sphinxsidebar input {
+    border: 1px solid {{ theme_sidebarlinkcolor }};
+    font-family: sans-serif;
+    font-size: 1em;
+}
+
+/* -- body styles ----------------------------------------------------------- */
+
+a {
+    color: {{ theme_linkcolor }};
+    text-decoration: none;
+}
+
+a:hover {
+    text-decoration: underline;
+}
+
+div.body p, div.body dd, div.body li {
+    text-align: justify;
+    line-height: 130%;
+}
+
+div.body h1,
+div.body h2,
+div.body h3,
+div.body h4,
+div.body h5,
+div.body h6 {
+    font-family: {{ theme_headfont }};
+    background-color: {{ theme_headbgcolor }};
+    font-weight: normal;
+    color: {{ theme_headtextcolor }};
+    border-bottom: 1px solid #ccc;
+    margin: 20px -20px 10px -20px;
+    padding: 3px 0 3px 10px;
+}
+
+div.body h1 { margin-top: 0; font-size: 200%; }
+div.body h2 { font-size: 160%; }
+div.body h3 { font-size: 140%; }
+div.body h4 { font-size: 120%; }
+div.body h5 { font-size: 110%; }
+div.body h6 { font-size: 100%; }
+
+a.headerlink {
+    color: {{ theme_headlinkcolor }};
+    font-size: 0.8em;
+    padding: 0 4px 0 4px;
+    text-decoration: none;
+}
+
+a.headerlink:hover {
+    background-color: {{ theme_headlinkcolor }};
+    color: white;
+}
+
+div.body p, div.body dd, div.body li {
+    text-align: justify;
+    line-height: 130%;
+}
+
+div.admonition p.admonition-title + p {
+    display: inline;
+}
+
+div.note {
+    background-color: #eee;
+    border: 1px solid #ccc;
+}
+
+div.seealso {
+    background-color: #ffc;
+    border: 1px solid #ff6;
+}
+
+div.topic {
+    background-color: #eee;
+}
+
+div.warning {
+    background-color: #ffe4e4;
+    border: 1px solid #f66;
+}
+
+p.admonition-title {
+    display: inline;
+}
+
+p.admonition-title:after {
+    content: ":";
+}
+
+/**
+ * Code block.
+ * The border colour should be a darker shade of the background colour.
+ * The hex code #E8D898 used below is a pale, light grayish amber.
+ */
+pre {
+    padding: 5px;
+    background-color: {{ theme_codebgcolor }};
+    color: {{ theme_codetextcolor }};
+    line-height: 120%;
+    border: 1px solid #E8D898;
+    border-left: none;
+    border-right: none;
+}
+
+/**
+ * Commands or code within text. The hex code #EAEAF8 used below is a
+ * pale, light grayish blue.
+ */
+tt {
+    background-color: #EAEAF8;
+    padding: 0 1px 0 1px;
+    font-size: 0.95em;
+}

new file doc/common/themes/sageref/theme.conf

@@ +1 @@
+[theme]
+inherit = default
+stylesheet = sage.css
+pygments_style = sphinx
+
+[options]
+# Custom Sage theme options
+
+# MathJax settings filled in by conf.py
+mathjax_macros =
+
+# Sphinx default theme options
+
+#nosidebar = false
+#rightsidebar = false
+#stickysidebar = false
+
+# Background color for the footer line: pale, light grayish blue (CSS color):
+footerbgcolor    = #B8B9F6
+# Text color for the footer line: black (CSS color): 
+footertextcolor  = #000000
+# Background color for the sidebar: light bluish gray (CSS color): 
+sidebarbgcolor   = #EAEAF8
+# Text color for the sidebar: black (CSS color): 
+sidebartextcolor = #000000
+# Link color for the sidebar: dark blue (CSS color): 
+sidebarlinkcolor = #090999
+# Background color for the relation bar: pale, light grayish blue (CSS color): 
+relbarbgcolor    = #B8B9F6
+# Text color for the relation bar: black (CSS color): 
+relbartextcolor  = #000000
+# Link color for the relation bar: dark blue (CSS color): 
+relbarlinkcolor  = #090999
+# Body background color (CSS color):
+#bgcolor          = #ffffff
+# Body text color: black (CSS color): 
+textcolor        = #000000
+# Background color for headings: light bluish gray (CSS color): 
+headbgcolor      = #EAEAF8
+# Text color for headings (CSS color):
+#headtextcolor    = #20435c
+# Link color for headings (CSS color):
+#headlinkcolor    = #c60f0f
+# Body link color: dark greenish blue (CSS color): 
+linkcolor        = #45529B
+# Background color for code blocks: very pale yellow (CSS color): 
+codebgcolor      = #FFFFE5
+# Default text color for code blocks, if not set differently by the highlighting style (CSS color):
+#codetextcolor    = #333333
+
+# Font for normal text (CSS font-family):
+#bodyfont = sans-serif
+# Font for headings (CSS font-family):
+#headfont = 'Trebuchet MS', sans-serif

doc/en/reference/arithgroup/index.rst

@@ -1 @@
-Arithmetic Subgroups of `{\rm SL}_2(\ZZ)`
-================================================
+Arithmetic Subgroups of `{\rm SL}_2({\bf Z})`
+=============================================
 
 This chapter describes the basic functionality for finite index subgroups of
 the modular group `{\rm SL}_2(\ZZ)`.

doc/en/reference/conf.py

@@ -15 +15 @@
 sys.path.append(os.environ['SAGE_DOC'])
 from common.conf import *
 
+# settings for the intersphinx extension:
+
+ref_src = os.path.join(SAGE_DOC, 'en', 'reference')
+ref_out = os.path.join(SAGE_DOC, 'output', 'html', 'en', 'reference')
+intersphinx_mapping[ref_out] = None
+
+for doc in os.listdir(ref_src):
+    if os.path.exists(os.path.join(ref_src, doc, 'index.rst')):
+        intersphinx_mapping[os.path.join(ref_out, doc)] = None
+
 # General information about the project.
 project = u"Sage Reference Manual"
 name = "reference"
@@ -50 +60 @@
 
 #Ignore all .rst in the _sage subdirectory
 exclude_trees = exclude_trees + ['_sage']
+
+multidocs_is_master = True
+
+# List of subdocs
+multidocs_subdoc_list = [
+    'algebras',
+    'arithgroup',
+    'calculus',
+    'categories',
+    'cmd',
+    'coding',
+    'coercion',
+    'combinat',
+    'constants',
+    'cryptography',
+    'databases',
+    'finance',
+    'function_fields',
+    'functions',
+    'games',
+    'geometry',
+    'graphs',
+    'groups',
+    'hecke',
+    'history_and_license',
+    'homology',
+    'interfaces',
+    'lfunctions',
+    'libs',
+    'logic',
+    'matrices',
+    'misc',
+    'modabvar',
+    'modfrm',
+    'modmisc',
+    'modsym',
+    'modules',
+    'monoids',
+    'notebook',
+    'number_fields',
+    'numerical',
+    'padics',
+    'parallel',
+    'plane_curves',
+    'plot3d',
+    'plotting',
+    'polynomial_rings',
+    'power_series',
+    'probability',
+    'quadratic_forms',
+    'quat_algebras',
+    'rings',
+    'rings_numerical',
+    'rings_standard',
+    'schemes',
+    'semirings',
+    'stats',
+    'structure',
+    'tensor'
+    ]
+
+# List of directories, relative to source directory, that shouldn't be
+# searched for source files.
+exclude_trees += multidocs_subdoc_list + [
+    'sage', 'sagenb', 'options'
+    ]

new file doc/en/reference/conf_sub.py

@@ +1 @@
+# -*- coding: utf-8 -*-
+#
+# Sage documentation build configuration file, created by
+# sphinx-quickstart on Thu Aug 21 20:15:55 2008.
+#
+# This file is execfile()d with the current directory set to its containing dir.
+#
+# The contents of this file are pickled, so don't put values in the namespace
+# that aren't pickleable (module imports are okay, they're removed automatically).
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+import sys, os
+sys.path.append(os.environ['SAGE_DOC'])
+from common.conf import *
+
+# settings for the intersphinx extension:
+
+ref_src = os.path.join(SAGE_DOC, 'en', 'reference')
+ref_out = os.path.join(SAGE_DOC, 'output', 'html', 'en', 'reference')
+intersphinx_mapping[ref_out] = None
+
+for doc in os.listdir(ref_src):
+    if os.path.exists(os.path.join(ref_src, doc, 'index.rst')):
+        intersphinx_mapping[os.path.join(ref_out, doc)] = None
+
+# We use the main document's title, if we can find it.
+rst_file = open('index.rst', 'r')
+rst_lines = rst_file.read().splitlines()
+rst_file.close()
+
+title = u''
+for i in xrange(len(rst_lines)):
+    if rst_lines[i].startswith('==') and i > 0:
+        title = rst_lines[i-1].strip()
+        break
+
+# Otherwise, we use this directory's name.
+name = os.path.basename(os.path.abspath('.'))
+if not title:
+    title = name.capitalize()
+title = title.replace(u'`', u'$')
+
+# General information about the project.
+project = u'Sage Reference Manual: ' + title
+
+# The name for this set of Sphinx documents.  If None, it defaults to
+# "<project> v<release> documentation".
+html_title = u'Sage Reference Manual v' + release + ': ' + title
+
+# A shorter title for the navigation bar.  Default is the same as html_title.
+html_short_title = title
+
+# HTML theme (e.g., 'default', 'sphinxdoc').  The pages for the
+# reference manual use a custom theme, a slight variant on the 'sage'
+# theme, to set the links in the top line.
+html_theme = 'sageref'
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = name
+
+# Grouping the document tree into LaTeX files. List of tuples (source
+# start file, target name, title, author, document class
+# [howto/manual]).
+latex_documents = [
+('index', name + '.tex', project, u'The Sage Development Team', 'manual')
+]
+
+#Ignore all .rst in the _sage subdirectory
+exclude_trees = exclude_trees + ['_sage']
+
+multidocs_is_master = False

new file doc/en/reference/footer.txt

@@ +1 @@
+Indices and Tables
+==================
+
+* `Index <../genindex.html>`_
+* `Module Index <../py-modindex.html>`_
+* `Search Page <../search.html>`_

doc/en/reference/games/index.rst

@@ -2 +2 @@
 =====
 
 Sage includes a sophisticated Sudoku solver.  It also has a
-Rubik's cube solver (see :ref:`Rubik's Cube Group <sec-rubik>`).
+Rubik's cube solver (see
+`Rubik's Cube Group <../groups/sage/groups/perm_gps/cubegroup.html>`_).
 
 .. toctree::
    :maxdepth: 2

doc/en/reference/hecke/index.rst

@@ -3 +3 @@
 
 This chapter describes the basic functionality for modules over Hecke
 algebras, including decompositions, degeneracy maps and so on. For specific
-examples of Hecke algebras that use this functionality see :ref:`ch:modsym` and
-:ref:`ch:modular`.
+examples of Hecke algebras that use this functionality see `Modular
+Symbols <../modsym/index.html>`_ and `Modular Forms
+<../modfrm/index.html>`_.
 
 .. toctree::
    :maxdepth: 2

doc/en/reference/index.rst

@@ -1 @@
-.. Sage Reference Manual documentation master file, created by sphinx-quickstart on Sun Sep 28 03:34:37 2008.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
-
-.. _ch:intro:
-
 Welcome to Sage's Reference Manual!
 =================================================
 
@@ -20 +14 @@
 Sage, and should produce exactly the same output as in this manual,
 except for line breaks.
 
-The Sage command line is briefly described in :ref:`ch:cmdline`, which
-lists the command line options. For more details about the command
-line, see the Sage tutorial.
+The Sage command line is briefly described in :doc:`The Sage Command Line 
+<cmd/index>`, which lists the command line options. For more
+details about the command line, see the Sage tutorial.
 
-The Sage graphical user interface is described in
-:ref:`ch:notebook`. This graphical user interface is unusual in that
-it operates via your web browser. It provides you with Sage worksheets
-that you can edit and evaluate, which contain scalable typeset
-mathematics and beautiful antialiased images.
+The Sage graphical user interface is described in :doc:`The Sage Notebook 
+<notebook/index>`. This graphical user interface is unusual in
+that it operates via your web browser. It provides you with Sage
+worksheets that you can edit and evaluate, which contain scalable
+typeset mathematics and beautiful antialiased images.
 
 This work is licensed under a `Creative Commons Attribution-Share Alike
 3.0 License`__.
@@ -37 +31 @@
 
 Enjoy Sage!
 
+Table of Contents
+=================
+
+* :doc:`The Sage Command Line <cmd/index>`
+* :doc:`The Sage Notebook <notebook/index>`
+
+Calculus, Plotting
+------------------
+
+* :doc:`Symbolic Calculus <calculus/index>`
+* :doc:`Constants <constants/index>`
+* :doc:`Functions <functions/index>`
+* :doc:`2D Graphics <plotting/index>`
+* :doc:`3D Graphics <plot3d/index>`
+
+Combinatorics, Discrete Mathematics
+-----------------------------------
+
+* :doc:`Combinatorics <combinat/index>`
+* :doc:`Graph Theory <graphs/index>`
+
+Structures, Coercion, Categories
+--------------------------------
+
+* :doc:`Basic Structures <structure/index>`
+* :doc:`Coercion <coercion/index>`
+* :doc:`Category Theory and Categories <categories/index>`
+
+Rings, Fields, Algebras
+-----------------------
+
+* :doc:`General Rings, Ideals, and Morphisms <rings/index>`
+* :doc:`Standard Commutative Rings <rings_standard/index>`
+* :doc:`Fixed and Arbitrary Precision Numerical Fields <rings_numerical/index>`
+* :doc:`Algebraic Number Fields <number_fields/index>`
+* :doc:`Function Fields <function_fields/index>`
+* :doc:`p-Adics <padics/index>`
+* :doc:`Polynomial Rings <polynomial_rings/index>`
+* :doc:`Power Series Rings <power_series/index>`
+* :doc:`Standard Semirings <semirings/index>`
+* :doc:`Algebras <algebras/index>`
+* :doc:`Quaternion Algebras <quat_algebras/index>`
+
+Groups, Monoids, Matrices, Modules
+----------------------------------
+
+* :doc:`Groups <groups/index>`
+* :doc:`Monoids <monoids/index>`
+* :doc:`Matrices and Spaces of Matrices <matrices/index>`
+* :doc:`Modules <modules/index>`
+
+Geometry and Topology
+---------------------
+
+* :doc:`Combinatorial Geometry <geometry/index>`
+* :doc:`Cell Complexes and their Homology <homology/index>`
+* :doc:`Differential Forms <tensor/index>`
+
+Number Theory, Algebraic Geometry
+---------------------------------
+
+* :doc:`Quadratic Forms <quadratic_forms/index>`
+* :doc:`L-Functions <lfunctions/index>`
+* :doc:`Schemes <schemes/index>`
+* :doc:`Elliptic, Plane, and Hyperelliptic Curves <plane_curves/index>`
+* :doc:`Arithmetic Subgroups of SL_2(Z) <arithgroup/index>`
+* :doc:`General Hecke Algebras and Hecke Modules <hecke/index>`
+* :doc:`Modular Symbols <modsym/index>`
+* :doc:`Modular Forms <modfrm/index>`
+* :doc:`Modular Abelian Varieties <modabvar/index>`
+* :doc:`Miscellaneous Modular-Form-Related Modules <modmisc/index>`
+
+Miscellaneous Mathematics
+-------------------------
+
+* :doc:`Games <games/index>`
+* :doc:`Symbolic Logic <logic/index>`
+* :doc:`SAT solvers <sat/index>`
+* :doc:`Cryptography <cryptography/index>`
+* :doc:`Numerical Optimization <numerical/index>`
+* :doc:`Probability <probability/index>`
+* :doc:`Statistics <stats/index>`
+* :doc:`Quantitative Finance <finance/index>`
+* :doc:`Coding Theory <coding/index>`
+
+Interfaces, Databases, Miscellany
+---------------------------------
+
+* :doc:`Interpreter Interfaces <interfaces/index>`
+* :doc:`C/C++ Library Interfaces <libs/index>`
+* :doc:`Databases <databases/index>`
+* :doc:`Parallel Computing <parallel/index>`
+* :doc:`Miscellaneous <misc/index>`
+
+Other
+-----
+
 .. toctree::
    :maxdepth: 2
 
-   cmd
-   notebook
-   calculus
-   plotting
-   plot3d
-   games
-   graphs
-   constants
-   functions
-   parallel
-   structure
-   coercion
-   misc
-   databases
-   interfaces
-   libs
-   cryptography
-   logic
-   sat
-   combinat/index
-   numerical
-   probability
-   stats 
-   finance
-   categories
-   monoids
-   groups
-   rings
-   rings_standard
-   rings_numerical
-   number_fields
-   function_fields
-   padics
-   polynomial_rings
-   power_series
-   semirings
-   algebras
-   quadratic_forms
-   quat_algebras
-   matrices
-   modules
-   geometry
-   homology
-   lfunctions
-   schemes
-   plane_curves
-   coding
-   arithgroup
-   hecke
-   modsym
-   modfrm
-   modabvar
-   modmisc
-   tensor
-
    todolist
 
-   history_and_license
+* :doc:`History and License <history_and_license/index>`
 
-Indices and tables
-==================
+Indices and Tables
+------------------
 
 * :ref:`genindex`
 * :ref:`modindex`
 * :ref:`search`
-

doc/en/reference/interfaces/index.rst

@@ -3 +3 @@
 
 Sage provides a unified interface to the best computational
 software. This is accomplished using both C-libraries (see
-:ref:`ch:libraries`) and interpreter interfaces, which are
+`C/C++ Library Interfaces <../libs/index.html>`_)
+and interpreter interfaces, which are
 implemented using pseudo-tty's, system files, etc. This chapter is
 about these interpreter interfaces.
 
@@ -18 +19 @@
     There is overhead associated with each call to one of these
     systems. For example, computing ``2+2`` thousands of times using
     the GAP interface will be slower than doing it directly in
-    Sage. In contrast, the C-library interfaces of :ref:`ch:libraries`
+    Sage. In contrast, the C-library interfaces of
+    `C/C++ Library Interfaces <../libs/index.html>`_
     incur less overhead.
 
 

doc/en/reference/misc/index.rst

@@ -55 +55 @@
 .. toctree::
    :maxdepth: 2
 
-   other/sagetex
+   sagetex
    sage/misc/latex
    sage/misc/latex_macros
 

doc/en/reference/todolist.rst

@@ -15 +15 @@
         Rewrite the hand-written TODOs by using the correct ``.. todo::``
         markup.
 
+The combined to do list is only available in the html version of the reference manual.
+
 .. todolist::

doc/en/website/conf.py

@@ -33 +33 @@
    u'The Sage Development Team', 'manual'),
 ]
 
-
-
 html_additional_pages = {
     'index': 'index.html',
 }

doc/en/website/templates/index.html

@@ -137 +137 @@
         <a class="biglink" href="reference/index.html">
           Reference Manual
         </a>
-        <a title="Download PDF" class="pdf" href="../../pdf/en/reference/reference.pdf">
+        <a title="Link to PDF" class="pdf" href="../../pdf/en/reference/index.html">
           <img class="icon" src="_static/pdf.png"></img>
         </a>
         <br>

sage/combinat/tutorial.py

@@ -209 +209 @@
 
 .. _figure-examples-catalan-trees:
 
-.. figure:: ../../media/combinat/complete-binary-trees-4.png
+.. figure:: ../../media/complete-binary-trees-4.png
     :scale: 150 %
 
     Figure: The five complete binary trees with four leaves
@@ -866 +866 @@
 
     sage: C.unrank(20).plot()
 
-.. image:: ../../media/combinat/a_poset.png
+.. image:: ../../media/a_poset.png
 
 One can iterate through all graphs up to isomorphism. For example,
 there are 34 simple graphs with 5 vertices::
@@ -878 +878 @@
 
     sage: show(graphs(5, lambda G: G.size() <= 4))
 
-.. image:: ../../media/combinat/graphs-5.png
+.. image:: ../../media/graphs-5.png
 
 However, the *set* ``C`` of these graphs is not yet available in
 ``Sage``; as a result, the following commands are not yet
@@ -1609 +1609 @@
 
 .. _figure-prefix-tree-partitions:
 
-.. figure:: ../../media/combinat/prefix-tree-partitions-5.png
+.. figure:: ../../media/prefix-tree-partitions-5.png
     :scale: 150%
 
     Figure: The prefix tree of the partitions of 5.
@@ -1674 +1674 @@
 
 .. _figure-polytope:
 
-.. figure:: ../../media/combinat/polytope.png
+.. figure:: ../../media/polytope.png
     :scale: 75%
 
     Figure: The polytope `L` and its integer points, in cross-eyed stereographic perspective.
@@ -1840 +1840 @@
 the ones that are still canonical [4]_. Recursively, one obtains all
 the canonical graphs.
 
-.. figure:: ../../media/combinat/prefix-tree-graphs-4.png
+.. figure:: ../../media/prefix-tree-graphs-4.png
 
    Figure: The generation tree of simple graphs with `4` vertices.
 

sage/graphs/base/static_sparse_graph.pyx

@@ -24 +24 @@
 Data structure
 --------------
 
-.. image:: ../../../media/graphs/structure.png
+.. image:: ../../../media/structure.png
 
 The data structure is actually pretty simple and compact. ``short_digraph`` has
 three fields

sage/graphs/graph_decompositions/graph_products.pyx

@@ -64 +64 @@
 
   A contradiction indeed.
 
-  .. image:: ../../../media/graphs/cycle.png
+  .. image:: ../../../media/cycle.png
 
   That means that, for instance, the edges of a triangle necessarily have the
   same color.
@@ -76 +76 @@
   In this situation, opposed edges necessarily have the same colors because of
   the previous remark.
 
-  .. image:: ../../../media/graphs/square.png
+  .. image:: ../../../media/square.png
 
   **1st criterion** : As a corollary, we know that:
 

sage/graphs/graph_latex.py

@@ -16 +16 @@
 LaTeX Versions of Graphs
 -------------------------------------
 
-.. image:: ../../media/graphs/heawood-graph-latex.png
+.. image:: ../../media/heawood-graph-latex.png
    :align: center
 
 Many mathematical objects in Sage have LaTeX representations, and graphs are no exception.  For a graph ``g``, the command ``view(g)``, issued at the Sage command line or in the notebook, will create a graphic version of ``g``.  Similarly, ``latex(g)`` will return a (long) string that is a representation of the graph in LaTeX.  Other ways of employing LaTeX in Sage, such as ``%latex`` in a notebook cell, or the Typeset checkbox in the notebook, will handle ``g`` appropriately.

sage/homology/delta_complex.py

@@ -149 +149 @@
       first in the prescribed way.  The three edges each start and end
       at the single vertex, ``Simplex(0)``.
 
-      .. image:: ../../media/homology/torus_labelled.png
+      .. image:: ../../media/torus_labelled.png
 
     - ``data`` may be nested lists or tuples.  The nth entry in the
       list is a list of the n-simplices in the complex, and each
@@ -178 +178 @@
       If one draws two triangles and identifies them according to this
       description, the result is the real projective plane.
 
-      .. image:: ../../media/homology/rp2.png
+      .. image:: ../../media/rp2.png
 
       ::
 
@@ -1483 +1483 @@
         A `\Delta`-complex representation of the torus, consisting of one
         vertex, three edges, and two triangles.
 
-        .. image:: ../../media/homology/torus.png
+        .. image:: ../../media/torus.png
 
         EXAMPLES::
 
@@ -1497 +1497 @@
         A `\Delta`-complex representation of the real projective plane,
         consisting of two vertices, three edges, and two triangles.
 
-        .. image:: ../../media/homology/rp2.png
+        .. image:: ../../media/rp2.png
 
         EXAMPLES::
 
@@ -1518 +1518 @@
         A `\Delta`-complex representation of the Klein bottle, consisting
         of one vertex, three edges, and two triangles.
 
-        .. image:: ../../media/homology/klein.png
+        .. image:: ../../media/klein.png
 
         EXAMPLES::
 

sage/homology/simplicial_complex.py

@@ -34 +34 @@
 denote both the simplicial complex and the associated topological
 space.
 
-.. image:: ../../media/homology/simplices.png
+.. image:: ../../media/simplices.png
 
 For any simplicial complex `K` and any commutative ring `R` there is
 an associated chain complex, with differential of degree `-1`.  The

sage/misc/sagedoc.py

@@ -18 +18 @@
 Check that argspecs of extension function/methods appear correctly,
 see :trac:`12849`::
     
-    sage: docfilename = os.path.join(SAGE_ROOT, 'devel', 'sage', 'doc', 'output', 'html', 'en', 'reference', 'sage', 'symbolic', 'expression.html')
+    sage: docfilename = os.path.join(SAGE_ROOT, 'devel', 'sage', 'doc', 'output', 'html', 'en', 'reference', 'calculus', 'sage', 'symbolic', 'expression.html')
     sage: for line in open(docfilename):
     ...       if "#sage.symbolic.expression.Expression.N" in line:
     ...           print line

sage/modular/arithgroup/farey_symbol.pyx

@@ -419 +419 @@
         Farey symbol of the arithmetic group. The sides of the
         hyperbolic polygon are numbered 0, 1, ... from left to right.
 
-        .. image:: ../../../media/modular/arithgroup/pairing.png
+        .. image:: ../../../media/pairing.png
 
         EXAMPLES::