[Python-checkins] r61316 - doctools/trunk/sphinx/builder.py doctools/trunk/sphinx/environment.py doctools/trunk/sphinx/quickstart.py

georg.brandl python-checkins at python.org
Sat Mar 8 22:23:54 CET 2008


Author: georg.brandl
Date: Sat Mar  8 22:23:54 2008
New Revision: 61316

Modified:
   doctools/trunk/sphinx/builder.py
   doctools/trunk/sphinx/environment.py
   doctools/trunk/sphinx/quickstart.py
Log:
Add some labels by default; create a master doc in quickstart.


Modified: doctools/trunk/sphinx/builder.py
==============================================================================
--- doctools/trunk/sphinx/builder.py	(original)
+++ doctools/trunk/sphinx/builder.py	Sat Mar  8 22:23:54 2008
@@ -244,6 +244,7 @@
                 doctree = self.env.get_and_resolve_doctree(docname, self)
             except Exception, err:
                 warnings.append('%s:: doctree not found!' % docname)
+                continue
             self.write_doc(docname, doctree)
         for warning in warnings:
             if warning.strip():

Modified: doctools/trunk/sphinx/environment.py
==============================================================================
--- doctools/trunk/sphinx/environment.py	(original)
+++ doctools/trunk/sphinx/environment.py	Sat Mar  8 22:23:54 2008
@@ -243,6 +243,11 @@
         self.index_num = 0          # autonumber for index targets
         self.gloss_entries = set()  # existing definition labels
 
+        # Some magically present labels
+        self.labels['genindex'] = ('genindex', '', 'Index')
+        self.labels['modindex'] = ('modindex', '', 'Module Index')
+        self.labels['search']   = ('search', '', 'Search Page')
+
     def set_warnfunc(self, func):
         self._warnfunc = func
         self.settings['warning_stream'] = RedirStream(func)
@@ -614,15 +619,18 @@
                     entries.append(toc)
             if entries:
                 return addnodes.compact_paragraph('', '', *entries)
-            return []
+            return None
 
         for toctreenode in doctree.traverse(addnodes.toctree):
             maxdepth = toctreenode.get('maxdepth', -1)
             newnode = _entries_from_toctree(toctreenode)
-            # prune the tree to maxdepth
-            if maxdepth > 0:
-                walk_depth(newnode, 1, maxdepth)
-            toctreenode.replace_self(newnode)
+            if newnode is not None:
+                # prune the tree to maxdepth
+                if maxdepth > 0:
+                    walk_depth(newnode, 1, maxdepth)
+                toctreenode.replace_self(newnode)
+            else:
+                toctreenode.replace_self([])
 
         # set the target paths in the toctrees (they are not known
         # at TOC generation time)
@@ -667,7 +675,9 @@
                             contnode['refdocname'] = docname
                             contnode['refsectname'] = sectname
                             newnode['refuri'] = builder.get_relative_uri(
-                                fromdocname, docname) + '#' + labelid
+                                fromdocname, docname)
+                            if labelid:
+                                newnode['refuri'] += '#' + labelid
                         newnode.append(innernode)
                 elif typ == 'keyword':
                     # keywords are referenced by named labels

Modified: doctools/trunk/sphinx/quickstart.py
==============================================================================
--- doctools/trunk/sphinx/quickstart.py	(original)
+++ doctools/trunk/sphinx/quickstart.py	Sat Mar  8 22:23:54 2008
@@ -140,14 +140,53 @@
 #latex_appendices = []
 '''
 
+
+MASTER_FILE = '''\
+.. %(project)s documentation master file, created by sphinx-quickstart.py on %(now)s.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+Welcome to %(project)s's documentation!
+===========%(underline)s=================
+
+Contents:
+
+.. toctree::
+   :maxdepth: 2
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
+
+'''
+
+def mkdir_p(dir):
+    if path.isdir(dir):
+        return
+    os.makedirs(dir)
+
+
 def is_path(x):
-    """Please enter an existing path name."""
-    return path.isdir(x)
+    """Please enter a valid path name."""
+    return path.isdir(x) or not path.exists(x)
 
 def nonempty(x):
     """Please enter some text."""
     return len(x)
 
+def choice(*l):
+    def val(x):
+        return x in l
+    val.__doc__ = 'Please enter one of %s.' % ', '.join(l)
+    return val
+
+def boolean(x):
+    """Please enter either 'y' or 'n'."""
+    return x.upper() in ('Y', 'YES', 'N', 'NO')
+
 def suffix(x):
     """Please enter a file suffix, e.g. '.rst' or '.txt'."""
     return x[0:1] == '.' and len(x) > 1
@@ -184,10 +223,22 @@
 accept a default value, if one is given in brackets).'''
 
     print '''
-This tool will create "src" and "build" folders in this path, which
-must be an existing directory.'''
+Enter the root path for documentation.'''
     do_prompt(d, 'path', 'Root path for the documentation', '.', is_path)
     print '''
+You have two options for placing the build directory for Sphinx output.
+Either, you use a directory ".build" within the root path, or you separate
+"source" and "build" directories within the root path.'''
+    do_prompt(d, 'sep', 'Separate source and build directories (y/n)', 'n',
+              boolean)
+    print '''
+Inside the root directory, two more directories will be created; ".templates"
+for custom HTML templates and ".static" for custom stylesheets and other
+static files. Since the leading dot may be inconvenient for Windows users,
+you can enter another prefix (such as "_") to replace the dot.'''
+    do_prompt(d, 'dot', 'Name prefix for templates and static dir', '.', ok)
+
+    print '''
 The project name will occur in several places in the built documentation.'''
     do_prompt(d, 'project', 'Project name')
     do_prompt(d, 'author', 'Author name(s)')
@@ -208,36 +259,41 @@
 "contents tree", that is, it is the root of the hierarchical structure
 of the documents. Normally, this is "index", but if your "index"
 document is a custom template, you can also set this to another filename.'''
-    do_prompt(d, 'master', 'Name of your master document (without suffix)', 'index')
-    print '''
-Inside the "src" directory, two directories will be created; ".templates"
-for custom HTML templates and ".static" for custom stylesheets and other
-static files. Since the leading dot may be inconvenient for Windows users,
-you can enter another prefix (such as "_") to replace the dot.'''
-    do_prompt(d, 'dot', 'Name prefix for templates and static dir', '.', ok)
+    do_prompt(d, 'master', 'Name of your master document (without suffix)',
+              'index')
 
     d['year'] = time.strftime('%Y')
     d['now'] = time.asctime()
+    d['underline'] = len(d['project']) * '='
+
+    if not path.isdir(d['path']):
+        mkdir_p(d['path'])
 
-    os.mkdir(path.join(d['path'], 'src'))
-    os.mkdir(path.join(d['path'], 'build'))
+    separate = d['sep'].upper() in ('Y', 'YES')
+    srcdir = separate and path.join(d['path'], 'source') or d['path']
 
-    f = open(path.join(d['path'], 'src', 'conf.py'), 'w')
+    mkdir_p(srcdir)
+    if separate:
+        mkdir_p(path.join(d['path'], 'build'))
+    else:
+        mkdir_p(path.join(srcdir, d['dot'] + 'build'))
+    mkdir_p(path.join(srcdir, d['dot'] + 'templates'))
+    mkdir_p(path.join(srcdir, d['dot'] + 'static'))
+
+    f = open(path.join(srcdir, 'conf.py'), 'w')
     f.write(QUICKSTART_CONF % d)
     f.close()
 
-    masterfile = path.join(d['path'], 'src', d['master'] + d['suffix'])
-
-    templatedir = path.join(d['path'], 'src', d['dot'] + 'templates')
-    os.mkdir(templatedir)
-    staticdir = path.join(d['path'], 'src', d['dot'] + 'static')
-    os.mkdir(staticdir)
+    masterfile = path.join(srcdir, d['master'] + d['suffix'])
+    f = open(masterfile, 'w')
+    f.write(MASTER_FILE % d)
+    f.close()
 
     print
     print bold('Finished: An initial directory structure has been created.')
     print '''
-You should now create your master file %s and other documentation
-sources. Use the sphinx-build.py script to build the docs.
+You should now populate your master file %s and create other documentation
+source files. Use the sphinx-build.py script to build the docs.
 ''' % (masterfile)
 
 


More information about the Python-checkins mailing list