merge with 0.6

CHANGES

@@ -17,6 +17,8 @@ Release 1.0 (in development)
 Release 0.6.2 (in development)
 ==============================
 
+* #173: Respect the docutils ``title`` directive.
+
 * #172: The ``obj`` role now links to modules as promised.
 
 * #19: Tables now can have a "longtable" class, in order to get

sphinx/environment.py

@@ -785,13 +785,21 @@ class BuildEnvironment:
         Add a title node to the document (just copy the first section title),
         and store that title in the environment.
         """
-        for node in document.traverse(nodes.section):
-            titlenode = nodes.title()
-            visitor = SphinxContentsFilter(document)
-            node[0].walkabout(visitor)
-            titlenode += visitor.get_entry_text()
-            self.titles[docname] = titlenode
-            return
+        titlenode = nodes.title()
+        # explicit title set with title directive
+        if document.has_key('title'):
+            titlenode += nodes.Text(document['title'])
+        # look for first section title and use that as the title
+        else:
+            for node in document.traverse(nodes.section):
+                visitor = SphinxContentsFilter(document)
+                node[0].walkabout(visitor)
+                titlenode += visitor.get_entry_text()
+                break
+            else:
+                # document has no title
+                titlenode += nodes.Text('<no title>')
+        self.titles[docname] = titlenode
 
     def note_labels_from(self, docname, document):
         for name, explicit in document.nametypes.iteritems():

tests/root/markup.txt

@@ -1,5 +1,7 @@
 :tocdepth: 2
 
+.. title:: set by title directive
+
 Testing various markup
 ======================
 

tests/test_build.py

@@ -93,6 +93,7 @@ HTML_XPATH = {
         ".//p": 'In HTML.',
         ".//p": 'In both.',
         ".//p": 'Always present',
+        ".//title": 'set by title directive',
     },
     'desc.html': {
         ".//dt[@id='mod.Cls.meth1']": '',