1 # -*- coding: utf-8 -*-

     2 """

     3     sphinx.setup_command

     4     ~~~~~~~~~~~~~~~~~~~~

     5 

     6     Setuptools/distutils commands to assist the building of sphinx

     7     documentation.

     8 

     9     :author: Sebastian Wiesner

    10     :contact: basti.wiesner@gmx.net

    11     :copyright: 2008 by Sebastian Wiesner.

    12     :license: MIT.

    13 """

    14 

    15 import sys

    16 import os

    17 from StringIO import StringIO

    18 from distutils.cmd import Command

    19 

    20 from sphinx.application import Sphinx

    21 from sphinx.util.console import darkred, nocolor

    22 

    23 

    24 class BuildDoc(Command):

    25     """Distutils command to build Sphinx documentation."""

    26 

    27     description = 'Build Sphinx documentation'

    28     user_options = [

    29         ('fresh-env', 'E', 'discard saved environment'),

    30         ('all-files', 'a', 'build all files'),

    31         ('source-dir=', 's', 'Source directory'),

    32         ('build-dir=', None, 'Build directory'),

    33         ('builder=', 'b', 'The builder to use. Defaults to "html"'),

    34         ]

    35     boolean_options = ['fresh-env', 'all-files']

    36 

    37 

    38     def initialize_options(self):

    39         self.fresh_env = self.all_files = False

    40         self.source_dir = self.build_dir = None

    41         self.conf_file_name = 'conf.py'

    42         self.builder = 'html'

    43 

    44     def finalize_options(self):

    45         if self.source_dir is None:

    46             if os.path.isdir('doc'):

    47                 for root, dirnames, filenames in os.walk('doc'):

    48                     if 'conf.py' in filenames:

    49                         self.source_dir = root

    50                         self.announce('Using source directory %s' % root)

    51                         break

    52         self.ensure_dirname('source_dir')

    53         self.source_dir = os.path.abspath(self.source_dir)

    54 

    55         if self.build_dir is None:

    56             build = self.get_finalized_command('build')

    57             self.build_dir = os.path.join(build.build_base, 'sphinx')

    58             self.mkpath(self.build_dir)

    59         self.ensure_dirname('build_dir')

    60         self.doctree_dir = os.path.join(self.build_dir, 'doctrees')

    61         self.mkpath(self.doctree_dir)

    62         self.builder_target_dir = os.path.join(self.build_dir, self.builder)

    63         self.mkpath(self.builder_target_dir)

    64 

    65     def run(self):

    66         if not sys.stdout.isatty() or sys.platform == 'win32':

    67             # Windows' poor cmd box doesn't understand ANSI sequences

    68             nocolor()

    69         if not self.verbose:

    70             status_stream = StringIO()

    71         else:

    72             status_stream = sys.stdout

    73         app = Sphinx(self.source_dir, self.source_dir,

    74                      self.builder_target_dir, self.doctree_dir,

    75                      self.builder, {}, status_stream,

    76                      freshenv=self.fresh_env)

    77 

    78         try:

    79             if self.all_files:

    80                 app.builder.build_all()

    81             else:

    82                 app.builder.build_update()

    83         except Exception, err:

    84             from docutils.utils import SystemMessage

    85             if isinstance(err, SystemMessage):

    86                 sys.stderr, darkred('reST markup error:')

    87                 print >>sys.stderr, err.args[0].encode('ascii', 'backslashreplace')

    88             else:

    89                 raise