added project option and improved doc.

sphinx/setup_command.py

@@ -22,7 +22,39 @@ from sphinx.util.console import darkred, nocolor, color_terminal
 
 
 class BuildDoc(Command):
-    """Distutils command to build Sphinx documentation."""
+    """Distutils command to build Sphinx documentation.
+    
+    The Sphinx build can then be triggered from distutils, and some 
+    Sphinx options can be set in ``setup.py`` or ``setup.cfg`` instead
+    of Sphinx own configuration file.
+    
+    For instance, from `setup.py`::
+    
+        from sphinx.setup_command import BuildDoc
+        cmdclass['build_sphinx'] = BuildDoc
+
+        name = 'My project'
+        version = 1.2
+        release = 1.2.0
+        setup(
+            name=name,
+            author='Bernard Montgomery',
+            version=release,
+            cmdclass={'build_sphinx': BuildDoc},
+            command_options={
+                'build_sphinx': {
+                    'project': ('setup.py', name),
+                    'version': ('setup.py', version),
+                    'release': ('setup.py', release) } })
+    
+    Or add this section in ``setup.cfg``::
+    
+        [build_sphinx]
+        project = 'My project'
+        version = 1.2
+        release = 1.2.0
+    
+    """
 
     description = 'Build Sphinx documentation'
     user_options = [
@@ -31,9 +63,10 @@ class BuildDoc(Command):
         ('source-dir=', 's', 'Source directory'),
         ('build-dir=', None, 'Build directory'),
         ('builder=', 'b', 'The builder to use. Defaults to "html"'),
+        ('project=', None, 'The documented project’s name'
         ('version=', None, 'The short X.Y version'),
         ('release=', None, 'The full version, including alpha/beta/rc tags'),
-        ('today=', None, 'hum... today??')]
+        ('today=', None, 'How to format the current date, used as the replacement for |today|')]
     boolean_options = ['fresh-env', 'all-files']