Georg Brandl avatar Georg Brandl committed 303e7f6 Merge

Comments (0)

Files changed (1)

sphinx/setup_command.py

 
 
 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`::
+
+       # this is only necessary when not using setuptools/distribute
+       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},
+           # these are optional and override conf.py settings
+           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 = [
         ('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, 'How to format the current date, used as the '
+         'replacement for |today|'),
+    ]
     boolean_options = ['fresh-env', 'all-files']
 
 
     def initialize_options(self):
         self.fresh_env = self.all_files = False
         self.source_dir = self.build_dir = None
-        self.conf_file_name = 'conf.py'
         self.builder = 'html'
+        self.version = ''
+        self.release = ''
+        self.today = ''
 
     def _guess_source_dir(self):
         for guess in ('doc', 'docs'):
             status_stream = StringIO()
         else:
             status_stream = sys.stdout
+        confoverrides = {}
+        if self.version:
+             confoverrides['version'] = self.version
+        if self.release:
+             confoverrides['release'] = self.release
+        if self.today:
+             confoverrides['today'] = self.today
         app = Sphinx(self.source_dir, self.source_dir,
                      self.builder_target_dir, self.doctree_dir,
-                     self.builder, {}, status_stream,
+                     self.builder, confoverrides, status_stream,
                      freshenv=self.fresh_env)
 
         try:
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.