[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