def sphinx_build(rst_directory):
"""
Builds a sphinx project as html and latex.
:param rst_directory:
:return:
"""
print('project directory {}'.format(rst_directory))
# output directory and builder name
build_directory = os.path.join(rst_directory, '_build')
# delete files of old build
if os.path.exists(build_directory):
shutil.rmtree(build_directory)
environment_file = os.path.join(rst_directory, 'environment.pickle')
if os.path.exists(environment_file):
os.remove(environment_file)
for file_name in glob.glob(os.path.join(rst_directory, '*.doctree')):
os.remove(file_name)
# call to sphinx
for builder_name in ('html', 'latex'):
sphinx.build_main(argv=['', '-b', builder_name, rst_directory, os.path.join(build_directory, builder_name)])
def run(self):
input_dir = './docs/sphinx'
build_doctree_dir = './build/doctrees'
build_output_dir = './build/man'
output_dir = DOC_MAN_PATH
if os.path.exists(build_doctree_dir):
shutil.rmtree(build_doctree_dir)
if os.path.exists(build_output_dir):
shutil.rmtree(build_output_dir)
# sphinx doc generation
sphinx.build_main(['sphinx-build',
'-c', input_dir,
'-b', 'man',
'-T',
'-d', build_doctree_dir,
# input dir
input_dir,
# output dir
build_output_dir])
# copy to docs folder
if os.path.exists(output_dir):
shutil.rmtree(output_dir)
shutil.copytree(build_output_dir, output_dir)
# actual sdist
sdist.run(self)
def DoTask(self):
tmpDir = join(self.buildSetup.tmpDir, "chm")
Prepare()
#warnings.simplefilter('ignore', DeprecationWarning)
sphinx.build_main([
None,
"-a", # always write all output files
"-b", "htmlhelp",
"-E", # Don’t use a saved environment (the structure
# caching all cross-references),
"-N", # Prevent colored output.
"-P", # (Useful for debugging only.) Run the Python debugger,
# pdb, if an unhandled exception occurs while building.
"-D", "release=%s" % self.buildSetup.appVersion,
"-D", "templates_path=[]",
"-d", EncodePath(join(self.buildSetup.tmpDir, ".doctree")),
EncodePath(DOCS_SOURCE_DIR),
tmpDir,
])
print "calling HTML Help Workshop compiler"
htmlHelpCompilerPath = GetHtmlHelpCompilerPath()
if htmlHelpCompilerPath is None:
raise Exception(
"HTML Help Workshop command line compiler not found"
)
hhpPath = join(tmpDir, "EventGhost.hhp")
StartProcess(htmlHelpCompilerPath, hhpPath)
shutil.copy(join(tmpDir, "EventGhost.chm"), self.buildSetup.sourceDir)
def sphinx_build(rst_directory):
"""
Builds a sphinx project as html and latex.
:param rst_directory:
:return:
"""
print('project directory {}'.format(rst_directory))
# output directory and builder name
build_directory = os.path.join(rst_directory, '_build')
# delete files of old build
if os.path.exists(build_directory):
shutil.rmtree(build_directory)
environment_file = os.path.join(rst_directory, 'environment.pickle')
if os.path.exists(environment_file):
os.remove(environment_file)
for file_name in glob.glob(os.path.join(rst_directory, '*.doctree')):
os.remove(file_name)
# call to sphinx
for builder_name in ('html', 'latex'):
sphinx.build_main(argv=[
'', '-b', builder_name, rst_directory,
os.path.join(build_directory, builder_name)
])
def call_sphinx(builder, build_setup, dest_dir):
WritePluginList(join(build_setup.docsDir, "pluginlist.rst"))
Prepare(build_setup.docsDir)
sphinx.build_main([
None,
"-D",
"project=EventGhost",
"-D",
"copyright=2005-2017 EventGhost Project",
# "-D", "templates_path=[]",
'-q', # be quiet
# "-a", # always write all output files
# "-E", # Don’t use a saved environment (the structure
# caching all cross-references),
# "-N", # Prevent colored output.
# "-P", # (Useful for debugging only.) Run the Python debugger,
# pdb, if an unhandled exception occurs while building.
# '-v', # verbosity, can be given up to three times
# '-v',
# write warnings and errors to file:
# '-w', join('output', 'sphinx_log_chm.txt'),
"-b",
builder,
"-D",
"version=%s" % build_setup.appVersion,
"-D",
"release=%s" % build_setup.appVersion,
"-d",
join(build_setup.tmpDir, ".doctree"),
build_setup.docsDir,
dest_dir,
])
def DoTask(self):
tmpDir = join(self.buildSetup.tmpDir, "chm")
Prepare()
#warnings.simplefilter('ignore', DeprecationWarning)
sphinx.build_main([
None,
"-a", # always write all output files
"-b",
"htmlhelp",
"-E", # Don’t use a saved environment (the structure
# caching all cross-references),
"-N", # Prevent colored output.
"-P", # (Useful for debugging only.) Run the Python debugger,
# pdb, if an unhandled exception occurs while building.
"-D",
"release=%s" % self.buildSetup.appVersion,
"-D",
"templates_path=[]",
"-d",
EncodePath(join(self.buildSetup.tmpDir, ".doctree")),
EncodePath(DOCS_SOURCE_DIR),
tmpDir,
])
print "calling HTML Help Workshop compiler"
htmlHelpCompilerPath = GetHtmlHelpCompilerPath()
if htmlHelpCompilerPath is None:
raise Exception(
"HTML Help Workshop command line compiler not found")
hhpPath = join(tmpDir, "EventGhost.hhp")
StartProcess(htmlHelpCompilerPath, hhpPath)
shutil.copy(join(tmpDir, "EventGhost.chm"), self.buildSetup.sourceDir)
def run(self):
input_dir = './docs/sphinx'
build_doctree_dir = './build/doctrees'
build_output_dir = './build/man'
output_dir = DOC_MAN_PATH
if os.path.exists(build_doctree_dir):
shutil.rmtree(build_doctree_dir)
if os.path.exists(build_output_dir):
shutil.rmtree(build_output_dir)
# sphinx doc generation
sphinx.build_main([
'sphinx-build',
'-c',
input_dir,
'-b',
'man',
'-T',
'-d',
build_doctree_dir,
# input dir
input_dir,
# output dir
build_output_dir
])
# copy to docs folder
if os.path.exists(output_dir):
shutil.rmtree(output_dir)
shutil.copytree(build_output_dir, output_dir)
# actual sdist
sdist.run(self)
def main(args):
"""Generate a Dash docset from Sphinx source files."""
srcdir = args.srcdir
dstdir = args.dstdir
name = args.name
if not os.path.exists(dstdir):
os.makedirs(dstdir)
# Generate HTML without indices.
sphinx.build_main(
[
"sphinx-build",
"-b",
"html",
"-d",
os.path.join(dstdir, "doctrees"),
"-t",
"dash",
srcdir,
os.path.join(dstdir, "html"),
]
)
# Convert to docset.
try:
doc2dash.__main__.main.main(
[os.path.join(dstdir, "html"), "-d", dstdir, "-n", name, "-f", "-I", "index.html"], "doc2dash", False
)
except SystemExit, e:
pass
def call_sphinx(builder, build_setup, dest_dir):
WritePluginList(join(build_setup.docsDir, "pluginlist.rst"))
Prepare(build_setup.docsDir)
sphinx.build_main(
[
None,
"-D", "project=EventGhost",
"-D", "copyright=2005-2017 EventGhost Project",
# "-D", "templates_path=[]",
'-q', # be quiet
# "-a", # always write all output files
# "-E", # Don’t use a saved environment (the structure
# caching all cross-references),
# "-N", # Prevent colored output.
# "-P", # (Useful for debugging only.) Run the Python debugger,
# pdb, if an unhandled exception occurs while building.
# '-v', # verbosity, can be given up to three times
# '-v',
# write warnings and errors to file:
# '-w', join('output', 'sphinx_log_chm.txt'),
"-b", builder,
"-D", "version=%s" % build_setup.appVersion,
"-D", "release=%s" % build_setup.appVersion,
"-d", join(build_setup.tmpDir, ".doctree"),
build_setup.docsDir,
dest_dir,
]
)
def run(self):
from sphinx import build_main
args = [sys.argv[0], '-b', 'html',
'galacteek/docs/manual/en',
'galacteek/docs/manual/en/html']
if self.all:
args.append('-a')
build_main(args)
def call_sphinx(builder, workdir, extraopts=None):
import sphinx
if extraopts is None:
extraopts = []
if not options['--cache'] and files is None:
extraopts.append('-E')
docpath = os.path.join(throot, 'doc')
inopt = [docpath, workdir]
if files is not None:
inopt.extend(files)
sphinx.build_main(['', '-b', builder] + extraopts + inopt)
def run(self):
from sphinx import build_main
build_main([
'sphinx-build',
'-b',
'html', # builder to use
'-a', # generate output for all files
'-E', # ignore cached files, forces to re-read all source files from disk
'docs', # source directory
'./docs/_build/html', # output directory
])
sys.exit(0)
def _reload1(self, clean=False):
self._but1.setEnabled(False)
self._but2.setEnabled(False)
app = QtGui.qApp
app.flush()
app.processEvents()
app.processEvents()
if clean and os.path.isdir(OUTDIR):
shutil.rmtree(OUTDIR)
sphinx.build_main(['', WEBSITEDIR, OUTDIR])
self._browser.reload()
self._but1.setEnabled(True)
self._but2.setEnabled(True)
def DoTask(self):
Prepare()
sphinx.build_main([
None,
"-a",
"-b", "html",
"-E",
"-N",
"-P",
"-D", "release=%s" % self.buildSetup.appVersion,
"-d", join(self.buildSetup.tmpDir, ".doctree"),
DOCS_SOURCE_DIR,
join(self.buildSetup.websiteDir, "docs"),
])
def DoTask(self):
Prepare()
sphinx.build_main([
None,
"-a",
"-b", "html",
"-E",
"-N",
"-P",
"-D", "release=%s" % self.buildSetup.appVersion,
"-d", join(self.buildSetup.tmpDir, ".doctree"),
DOCS_SOURCE_DIR,
join(self.buildSetup.websiteDir, "docs"),
])
def test_run_full_case(tmpdir, case_dir, parallel):
input_dir = os.path.join(case_dir, 'input')
output_dir = os.path.join(case_dir, 'output')
docs_dir = tmpdir.mkdir('docs').strpath
conf = deepcopy(DEFAULT_CONF)
conf.update({
'automodapi_toctreedirnm': 'api',
'automodapi_writereprocessed': True,
'automodsumm_writereprocessed': True
})
if os.path.basename(case_dir) in ('mixed_toplevel',
'mixed_toplevel_all_objects'):
conf['extensions'].append('sphinx_automodapi.smart_resolver')
start_dir = os.path.abspath('.')
src_dir = 'src' if 'source_dir' in case_dir else '.'
ensuredir(os.path.join(docs_dir, src_dir))
write_conf(os.path.join(os.path.join(docs_dir, src_dir), 'conf.py'), conf)
for root, dirnames, filenames in os.walk(input_dir):
for filename in filenames:
root_dir = os.path.join(docs_dir, os.path.relpath(root, input_dir))
ensuredir(root_dir)
input_file = os.path.join(root, filename)
shutil.copy(input_file, root_dir)
argv = ['-W', '-b', 'html', src_dir, '_build/html']
if parallel:
argv.insert(0, '-j 4')
if SPHINX_LT_17:
# As of Sphinx 1.7, the first argument is now no longer ignored
argv.insert(0, 'sphinx-build')
try:
os.chdir(docs_dir)
status = build_main(argv=argv)
finally:
os.chdir(start_dir)
assert status == 0
# Check that all expected output files are there and match the reference files
for root, dirnames, filenames in os.walk(output_dir):
for filename in filenames:
path_reference = os.path.join(root, filename)
path_relative = os.path.relpath(path_reference, output_dir)
path_actual = os.path.join(docs_dir, path_relative)
assert os.path.exists(path_actual)
with io.open(path_actual, encoding='utf8') as f:
actual = f.read()
with io.open(path_reference, encoding='utf8') as f:
reference = f.read()
assert actual.strip() == reference.strip()
def test_build_docs():
docsdir = os.path.abspath(os.path.dirname(__file__)) + '/../../docs'
exitCode = sphinx.build_main(['_sphinx.py', docsdir, docsdir + '/__testbuild'])
# The following code works in sphinx >= 1.7.0
# exitCode = sphinx.build([docsdir, docsdir + '/__testbuild'])
assert exitCode == 0
shutil.rmtree(docsdir + '/__testbuild')
def _build(argv, config, versions, current_name, is_root):
"""Build Sphinx docs via multiprocessing for isolation.
:param tuple argv: Arguments to pass to Sphinx.
:param sphinxcontrib.versioning.lib.Config config: Runtime configuration.
:param sphinxcontrib.versioning.versions.Versions versions: Versions class instance.
:param str current_name: The ref name of the current version being built.
:param bool is_root: Is this build in the web root?
"""
# Patch.
application.Config = ConfigInject
if config.show_banner:
EventHandlers.BANNER_GREATEST_TAG = config.banner_greatest_tag
EventHandlers.BANNER_MAIN_VERSION = config.banner_main_ref
EventHandlers.BANNER_RECENT_TAG = config.banner_recent_tag
EventHandlers.SHOW_BANNER = True
EventHandlers.CURRENT_VERSION = current_name
EventHandlers.IS_ROOT = is_root
EventHandlers.VERSIONS = versions
SC_VERSIONING_VERSIONS[:] = [p for r in versions.remotes for p in sorted(r.items()) if p[0] not in ('sha', 'date')]
# Update argv.
if config.verbose > 1:
argv += ('-v',) * (config.verbose - 1)
if config.no_colors:
argv += ('-N',)
if config.overflow:
argv += config.overflow
# Build.
result = build_main(argv)
if result != 0:
raise SphinxError
def run(self):
if not _HAVE_SPHINX:
raise RuntimeError(
"You must install Sphinx to build the documentation.")
self.inplace = True
build_ext.run(self)
path = os.path.join(os.path.abspath("."), "doc", "_build", "html")
sphinx_args = ["-E", "-b", "html", "doc", path]
# sphinx.main calls sys.exit when sphinx.build_main exists.
# Call build_main directly so we can check status and print
# the full path to the built docs.
if hasattr(sphinx, 'build_main'):
status = sphinx.build_main(sphinx_args)
else:
status = sphinx.main(sphinx_args)
if status:
raise RuntimeError("Documentation build failed")
sys.stdout.write("\nDocumentation build complete. The "
"results can be found in %s.\n" % (path,))
def _build(argv, config, versions, current_name, is_root):
"""Build Sphinx docs via multiprocessing for isolation.
:param tuple argv: Arguments to pass to Sphinx.
:param sphinxcontrib.versioning.lib.Config config: Runtime configuration.
:param sphinxcontrib.versioning.versions.Versions versions: Versions class instance.
:param str current_name: The ref name of the current version being built.
:param bool is_root: Is this build in the web root?
"""
# Patch.
application.Config = ConfigInject
if config.show_banner:
EventHandlers.BANNER_GREATEST_TAG = config.banner_greatest_tag
EventHandlers.BANNER_MAIN_VERSION = config.banner_main_ref
EventHandlers.BANNER_RECENT_TAG = config.banner_recent_tag
EventHandlers.SHOW_BANNER = True
EventHandlers.CURRENT_VERSION = current_name
EventHandlers.IS_ROOT = is_root
EventHandlers.VERSIONS = versions
SC_VERSIONING_VERSIONS[:] = [p for r in versions.remotes for p in sorted(r.items()) if p[0] not in ('sha', 'date')]
# Update argv.
if config.verbose > 1:
argv += ('-v',) * (config.verbose - 1)
if config.no_colors:
argv += ('-N',)
if config.overflow:
argv += config.overflow
argv += ('-D', "version={}".format(current_name))
print(argv)
# Build.
result = build_main(argv)
if result != 0:
raise SphinxError
def build_docs(self, what=None, format=None, outdir=None, auto_open=True, http=None):
self._activate_virtualenv()
self.virtualenv_manager.install_pip_package('sphinx_rtd_theme==0.1.6')
import sphinx
import webbrowser
if not outdir:
outdir = os.path.join(self.topobjdir, 'docs')
if not what:
what = [os.path.join(self.topsrcdir, 'tools')]
outdir = os.path.join(outdir, format)
generated = []
failed = []
for path in what:
path = os.path.normpath(os.path.abspath(path))
docdir = self._find_doc_dir(path)
if not docdir:
failed.append((path, 'could not find docs at this location'))
continue
# find project name to use as a namespace within `outdir`
project = self._find_project_name(docdir)
savedir = os.path.join(outdir, project)
args = [
'sphinx',
'-b', format,
docdir,
savedir,
]
result = sphinx.build_main(args)
if result != 0:
failed.append((path, 'sphinx return code %d' % result))
else:
generated.append(savedir)
index_path = os.path.join(savedir, 'index.html')
if not http and auto_open and os.path.isfile(index_path):
webbrowser.open(index_path)
if generated:
print('\nGenerated documentation:\n%s\n' % '\n'.join(generated))
if failed:
failed = ['%s: %s' % (f[0], f[1]) for f in failed]
return die('failed to generate documentation:\n%s' % '\n'.join(failed))
if http is not None:
host, port = http.split(':', 1)
addr = (host, int(port))
if len(addr) != 2:
return die('invalid address: %s' % http)
httpd = mozhttpd.MozHttpd(host=addr[0], port=addr[1], docroot=outdir)
print('listening on %s:%d' % addr)
httpd.start(block=True)
def test_sphinx_scruffy_error(monkeypatch, build_dir):
"""Test sphinx_scruffy plugin if renderer fails. Should not affect the whole build."""
monkeypatch.setattr(sphinx_scruffy, 'render_scruffy',
lambda *args, **kwargs: 1 / 0)
res = sphinx.build_main(
['-c ' + os.path.join(BASE_DIR, 'conf.py'), BASE_DIR, build_dir])
assert res is 0
assert 'index.html' in os.listdir(build_dir)
def main(projects, argv=None, exit_on_error=False):
import sphinx
argv = argv or sys.argv
for project, args in projects.items():
print("building docs for", project, "---> sphinx-build", " ".join(args))
code = sphinx.build_main(argv=argv+args)
if exit_on_error and code:
sys.exit(code) # pragma: no cover
def _test(self):
with utils.mock.patch('sys.stderr', six.moves.StringIO()) as stderr:
with utils.mock.patch('sys.stdout', six.moves.StringIO()) as stdout:
self.assertEquals(0, sphinx.build_main([
"-b{}".format(builder),
"-d{}".format(os.path.join(self.build_dir, 'doctrees')),
self.source_dir,
os.path.join(self.build_dir, builder)])
)
def run(self):
command = [
None, # in Sphinx < 1.7.0 the first command-line argument was parsed, in 1.7.0 it became argv[1:]
'-b', 'html', # the builder to use, e.g., create a HTML version of the documentation
'-a', # generate output for all files
'-E', # ignore cached files, forces to re-read all source files from disk
'docs', # the source directory where the documentation files are located
'./docs/_build/html', # where to save the output files
]
import sphinx
if sphinx.version_info[:2] < (1, 7):
from sphinx import build_main
else:
from sphinx.cmd.build import build_main
command.pop(0)
build_main(command)
def generate_rst(binpath, temppath, outpath, version):
import developer_manual
import user_manual
html_dir = os.path.abspath(
os.path.join(os.path.dirname(__file__), '../html'))
cfg_dev = os.path.join(os.path.dirname(__file__), 'developer_manual')
cfg_usr = os.path.join(os.path.dirname(__file__), 'user_manual')
temp_dev = os.path.join(temppath, 'rst', 'developer_manual')
temp_usr = os.path.join(temppath, 'rst', 'user_manual')
out_dev = os.path.join(outpath, 'developer_manual')
out_usr = os.path.join(outpath, 'user_manual')
if html_dir <> outpath:
clone_rst(html_dir, outpath)
clone_rst(cfg_dev, temp_dev)
clone_rst(cfg_usr, temp_usr)
developer_manual.generate_rst(temppath, outpath)
user_manual.generate_rst(temppath, outpath, binpath)
generate_download_inc_files(temp_dev, temp_usr, version)
# Determine the typical green color for the upper and lower bars on the webpage.
color = '#406756'
shared_opts = [
'-bhtml', '-D', 'version={0}'.format('.'.join(version)), '-D',
'release={0}'.format(version[0]), '-D',
'html_theme_options.relbarbgcolor={0}'.format(color)
]
if _LOG.getEffectiveLevel() > logging.WARNING:
shared_opts += ['-Q']
elif _LOG.getEffectiveLevel() >= logging.WARNING:
shared_opts += ['-q']
options = shared_opts + ['-c', cfg_dev, temp_dev, out_dev]
print '<OPTIONS>', ' '.join(options)
try:
sphinx.build_main(shared_opts + ['-c', cfg_dev, temp_dev, out_dev])
except SystemExit as e:
if e.code != 0:
raise e
try:
sphinx.build_main(shared_opts + ['-c', cfg_usr, temp_usr, out_usr])
except SystemExit as e:
if e.code != 0:
raise e
def run(self):
docdir = self.docdir
destdir = op.join(docdir, 'html')
if op.exists(destdir):
shutil.rmtree(destdir)
import sphinx
try:
import unittest.mock as mock
except ImportError:
import mock
# Sigh. Why can't I mock a package?
mockobj = mock.MagicMock()
mockedModules = open(op.join(docdir, 'mock_modules.txt')).readlines()
mockedClasses = open(op.join(docdir, 'mock_classes.txt')).readlines()
mockedModules = {m.strip(): mockobj for m in mockedModules}
mockedClasses = {l.strip(): None for l in mockedClasses}
# a different mock class for each mocked class
for clsname in mockedClasses.keys():
class MockClass(object):
def __init__(self, *args, **kwargs):
pass
mockedClasses[clsname] = MockClass
class MockType(type):
pass
patches = [mock.patch.dict('sys.modules', **mockedModules)] + \
[mock.patch('wx.lib.newevent.NewEvent',
return_value=(mockobj, mockobj))] + \
[mock.patch(n, c) for n, c in mockedClasses.items()] + \
[mock.patch('fsleyes_props.PropertyOwner', MockType)]
[p.start() for p in patches]
sphinx.build_main(['sphinx-build', docdir, destdir])
[p.stop() for p in patches]
def _run_sphinx(self, docdir, savedir, fmt='html'):
import sphinx
args = [
'sphinx',
'-b',
fmt,
docdir,
savedir,
]
return sphinx.build_main(args)
def sphinx_build(src_dir, build_dir):
import sphinx
ret = sphinx.build_main(['sphinx-build', # Dummy
'-b', 'html',
'-d', op.join(build_dir, 'doctrees'),
src_dir, # Source
op.join(build_dir, 'html'), # Dest
])
if ret != 0:
raise RuntimeError('Sphinx error: %s' % ret)
print("Build finished. The HTML pages are in %s/html." % build_dir)
def test_basic(tmpdir, theme):
# Just make sure the docs build with the specified theme
# (to make sure e.g. that no templates are missing)
with open(tmpdir.join('conf.py').strpath, 'w') as f:
f.write(BASIC_CONF.format(theme=theme))
with open(tmpdir.join('index.rst').strpath, 'w') as f:
f.write(BASIC_INDEX.format(theme=theme))
src_dir = tmpdir.strpath
html_dir = tmpdir.mkdir('html').strpath
if SPHINX_LT_17:
status = build_main(argv=['sphinx-build', '-W', '-b', 'html', src_dir, html_dir])
else:
# As of Sphinx 1.7, the first argument is now no longer ignored
status = build_main(argv=['-W', '-b', 'html', src_dir, html_dir])
assert status == 0
def _run_sphinx(self, docdir, savedir, config=None, fmt='html'):
import sphinx
config = config or self.manager.conf_py_path
args = [
'sphinx',
'-b', fmt,
'-c', os.path.dirname(config),
docdir,
savedir,
]
return sphinx.build_main(args)
def build(ctx, source, nowarn):
"""
Build documentation from ``source``, placing built files in
``target``.
"""
_logger.info('building documentation')
outdir = ctx.obj['outdir']
args = ['-b html']
if not nowarn:
args.append('-W')
if sphinx.build_main(args + [source, outdir]):
click.ClickException("Error building sphinx doc")
def html_dir():
"""
Build the HTML output for the documentation and provide its path to tests.
"""
docs_path = os.path.join(os.path.abspath(os.path.dirname(__file__)), '..',
'docs')
build_path = os.path.join(docs_path, '_test', 'html')
os.chdir(docs_path)
result = build_main(['sphinx-build', '-b', 'html', '.', build_path])
assert result == 0
yield build_path
rmtree(build_path)
def test_conf(tmpdir):
# Just make sure the docs build with the default sphinx-astropy configuration
with open(tmpdir.join('conf.py').strpath, 'w') as f:
f.write(BASIC_CONF)
with open(tmpdir.join('index.rst').strpath, 'w') as f:
f.write(BASIC_INDEX)
src_dir = tmpdir.strpath
html_dir = tmpdir.mkdir('html').strpath
if SPHINX_LT_17:
status = build_main(
argv=['sphinx-build', '-W', '-b', 'html', src_dir, html_dir])
else:
# As of Sphinx 1.7, the first argument is now no longer ignored
status = build_main(argv=['-W', '-b', 'html', src_dir, html_dir])
assert status == 0
def main(args):
"""Generate a Dash docset from Sphinx source files."""
srcdir = args.srcdir
dstdir = args.dstdir
name = args.name
if not os.path.exists(dstdir):
os.makedirs(dstdir)
# Generate HTML without indices.
sphinx.build_main([ "sphinx-build", "-b", "html", "-d", os.path.join(dstdir, "doctrees"), \
"-t", "dash", srcdir, os.path.join(dstdir, "html") ])
# Convert to docset.
try:
doc2dash.__main__.main.main( \
[ os.path.join(dstdir, "html"), "-d", dstdir, "-n", name, \
"-f", "-I", "index.html"], "doc2dash", False)
except SystemExit, e:
pass
def _executeSphinx(self, options, outputFile, errorsFile):
"""
General execution of sphinx. This method is used by:
* phase #1: by _phase1ExecuteSphinxForNormalDocProduction
* phase #3: by _phase3ExecuteSphinxForProblemDocProduction
The options are different in each case.
:param options: particular options depending on the phase
:return: exit code
"""
# config_arguments = []
# map(config_arguments.extend,
# [ '-D%s=%s' % (name, value)] for (name, value) in self.configValues] )
# print '===',config_arguments
additional_arguments = [
'-T', # Display the full traceback when an unhandled exception occurs.
'-b',
'html', # Build HTML pages. This is the default builder.
# '-d', self.docTrees, # Directory of the doctree pickles
'-c',
self.confDir, # Directory containing the conf.py file
self.sourceDir, # Source directory
self.targetDir, # target directory
]
#arguments=config_arguments+options+additional_arguments
arguments = options + additional_arguments
if debug:
print(' sphinxproblems: Executing sphinx as following')
print(' ' * 8 + 'sphinx-build %s' % ' '.join(arguments))
if showOutputAndErrors:
exit_code = sphinx.build_main(argv=arguments)
else:
stdout = sys.stdout
stderr = sys.stderr
with open(outputFile, 'w') as sys.stdout:
with open(errorsFile, 'w') as sys.stderr:
exit_code = sphinx.build_main(argv=arguments)
sys.stdout = stdout
sys.stderr = stderr
return exit_code
def _build_doc(self, target):
import shutil
import sphinx
rst_src = self._build_source()
metadata = self.distribution.metadata
build_dir = os.path.join(self.build_dir, target)
dist_dir = os.path.join(self.dist_root, target)
cached_directory = os.path.join(os.path.dirname(build_dir), 'doctrees')
all_sphinx_opts = [
'',
'-b',
target, # builder to use; default is html
'-d',
cached_directory, # path for the cached doctree files
'-n', # warn about all missing references
'-q', # no output on stdout, warnings on stderr
'-T', # show full traceback on exception
'-D',
'project={!s}'.format(metadata.name),
'-D',
'version={!s}'.format(metadata.version)
]
if not self.ignore_warnings:
all_sphinx_opts.append('-W')
all_sphinx_opts.append(rst_src)
all_sphinx_opts.append(build_dir)
sphinx.build_main([str(arg) for arg in all_sphinx_opts])
shutil.rmtree(str(dist_dir), ignore_errors=True)
mkdir_p(os.path.dirname(dist_dir))
shutil.copytree(str(build_dir), str(dist_dir))
return dist_dir
def _test(self):
with utils.mock.patch('sys.stderr',
six.moves.StringIO()) as stderr:
with utils.mock.patch('sys.stdout',
six.moves.StringIO()) as stdout:
self.assertEquals(
0,
sphinx.build_main([
"-b{}".format(builder), "-d{}".format(
os.path.join(self.build_dir, 'doctrees')),
self.source_dir,
os.path.join(self.build_dir, builder)
]))
def build_docs(self, what=None, format=None, outdir=None, auto_open=True):
self._activate_virtualenv()
self.virtualenv_manager.install_pip_package('sphinx_rtd_theme==0.1.6')
import sphinx
import webbrowser
if not outdir:
outdir = os.path.join(self.topobjdir, 'docs')
if not what:
what = [os.path.join(self.topsrcdir, 'tools')]
generated = []
failed = []
for path in what:
path = os.path.normpath(os.path.abspath(path))
docdir = self._find_doc_dir(path)
if not docdir:
failed.append((path, 'could not find docs at this location'))
continue
# find project name to use as a namespace within `outdir`
project = self._find_project_name(docdir)
savedir = os.path.join(outdir, format, project)
args = [
'sphinx',
'-b', format,
docdir,
savedir,
]
result = sphinx.build_main(args)
if result != 0:
failed.append((path, 'sphinx return code %d' % result))
else:
generated.append(savedir)
# attempt to open html docs in a browser
index_path = os.path.join(savedir, 'index.html')
if auto_open and os.path.isfile(index_path):
webbrowser.open(index_path)
if generated:
print("\nGenerated documentation:\n%s\n" % '\n'.join(generated))
if failed:
failed = ['%s - %s' % (f[0], f[1]) for f in failed]
print("ERROR failed to generate documentation:\n%s" % '\n'.join(failed))
return 1
def test_run_full_case(tmpdir, case_dir):
input_dir = os.path.join(case_dir, 'input')
output_dir = os.path.join(case_dir, 'output')
docs_dir = tmpdir.mkdir('docs').strpath
conf = deepcopy(DEFAULT_CONF)
conf.update({
'automodapi_toctreedirnm': 'api',
'automodapi_writereprocessed': True,
'automodsumm_writereprocessed': True
})
if os.path.basename(case_dir) == 'mixed_toplevel':
conf['extensions'].append('sphinx_automodapi.smart_resolver')
start_dir = os.path.abspath('.')
src_dir = 'src' if 'source_dir' in case_dir else '.'
ensuredir(os.path.join(docs_dir, src_dir))
write_conf(os.path.join(os.path.join(docs_dir, src_dir), 'conf.py'), conf)
for root, dirnames, filenames in os.walk(input_dir):
for filename in filenames:
root_dir = os.path.join(docs_dir, os.path.relpath(root, input_dir))
ensuredir(root_dir)
input_file = os.path.join(root, filename)
shutil.copy(input_file, root_dir)
try:
os.chdir(docs_dir)
status = build_main(
argv=['sphinx-build', '-W', '-b', 'html', src_dir, 'build/_html'])
finally:
os.chdir(start_dir)
assert status == 0
# Check that all expected output files are there and match the reference files
for root, dirnames, filenames in os.walk(output_dir):
for filename in filenames:
path_reference = os.path.join(root, filename)
path_relative = os.path.relpath(path_reference, output_dir)
path_actual = os.path.join(docs_dir, path_relative)
assert os.path.exists(path_actual)
actual = open(path_actual).read()
reference = open(path_reference).read()
assert actual.strip() == reference.strip()
def sphinx_build(src_dir, build_dir):
import sphinx
ret = sphinx.build_main([
'sphinx-build', # Dummy
'-b',
'html',
'-d',
op.join(build_dir, 'doctrees'),
src_dir, # Source
op.join(build_dir, 'html'), # Dest
])
if ret != 0:
raise RuntimeError('Sphinx error: %s' % ret)
print("Build finished. The HTML pages are in %s/html." % build_dir)
def url_build():
"""
build ablog
**param**:
- all (default: false)
"""
try:
if not request.data: request.data = str(json.dumps({})).encode()
allfiles = json.loads(request.data.decode()).get('all',False)
argv = sys.argv[:1]
argv.extend(['-b', app.config['ABLOG_BUILDER']])
argv.extend(['-d', app.config['ABLOG_DOCTREES']])
if allfiles:
argv.extend(['-a'])
argv.extend([app.config['ABLOG_SRC_DIR'], app.config['ABLOG_WEBSITE']])
sphinx.build_main(argv)
getEnv(reload=True)
return json.dumps({'build' : True})
except Exception as e:
app.logger.debug(e)
return json.dumps({'build' : False})
def run_build_main(docs_dir, html_dir, overflow):
"""Run build_main().
:param str docs_dir: Path to input docs directory.
:param str html_dir: Path to output html directory.
:param iter overflow: Append these args to sphinx-build call.
:return: Value from build_main().
:rtype: int
"""
argv = ('sphinx-build', str(docs_dir), str(html_dir))
if overflow:
argv += overflow
result = build_main(argv)
return result
def sphinx_build(directory):
"""
:param directory:
:return:
"""
print('build directory {}'.format(directory))
# output directory and builder name
out_directory = os.path.join(directory, '_build')
builder_name = 'html'
# delete files of old build
if os.path.exists(out_directory):
shutil.rmtree(out_directory)
environment_file = os.path.join(directory, 'environment.pickle')
if os.path.exists(environment_file):
os.remove(environment_file)
for file_name in glob.glob(os.path.join(directory, '*.doctree')):
os.remove(file_name)
# call to sphinx
sphinx.build_main(argv=['', '-b', builder_name, directory, out_directory])
def call_sphinx(builder, workdir):
import sphinx
if options['--check']:
extraopts = ['-W']
else:
extraopts = []
if not options['--cache'] and files is None:
extraopts.append('-E')
docpath = os.path.join(throot, 'doc')
inopt = [docpath, workdir]
if files is not None:
inopt.extend(files)
ret = sphinx.build_main(['', '-b', builder] + extraopts + inopt)
if ret != 0:
sys.exit(ret)
def sphinx_build(src_dir, build_dir):
import sphinx
cmd = [ '-b', 'html',
'-d', op.join(build_dir, 'doctrees'),
src_dir, # Source
op.join(build_dir, 'html'), # Dest
]
if sphinx.version_info > (1, 7):
import sphinx.cmd.build
ret = sphinx.cmd.build.build_main(cmd)
else:
ret = sphinx.build_main(['sphinx-build'] + cmd)
if ret != 0:
raise RuntimeError('Sphinx error: %s' % ret)
print("Build finished. The HTML pages are in %s/html." % build_dir)
def build_docs(source_dir, target_dir, flags):
"""
Build documentation from ``source_dir``, placing built files in
``target_dir``.
:param str source_dir: location of sphinx documentation files
:param str target_dir: location to build to
"""
print 'building documentation'
args = ['-b html']
if len(flags):
args = args + flags
if sphinx.build_main(args + [source_dir, target_dir]):
return False
open('%s/.nojekyll' % target_dir, 'a').close()
return True
def sphinx_build(src_dir, build_dir):
import sphinx
ret = sphinx.build_main(
[
"sphinx-build", # Dummy
"-b",
"html",
"-d",
op.join(build_dir, "doctrees"),
src_dir, # Source
op.join(build_dir, "html"), # Dest
]
)
if ret != 0:
raise RuntimeError("Sphinx error: %s" % ret)
print("Build finished. The HTML pages are in %s/html." % build_dir)
def test_build_ok(self):
args = [
'build_sphinx',
'-E', # Dont use a saved environment but rebuild it completely.
'-q', # Do not output anything on standard output, only write warnings and errors to standard error.
'-w{}'.format(self.stderr_file), # Write warnings (and errors) to the given file
self.rst_source_files_dir, # souce dir of rst files
self.build_output_dir, # output dir for html files
]
exit_status = build_main(args)
self.assertEqual(exit_status, 0)
# Confirm that html file was generated:
self.assertTrue(os.path.isfile(os.path.join(self.build_output_dir, 'contents.html')))
# Confirm there is no content (no errors/warnings) in self.stderr_file:
self.assertEqual(os.stat(self.stderr_file).st_size, 0)
def get_sphinx_rst_worker(self, task, text, path, basedir, builddir):
add_override_file(path, text)
rel_path = os.path.relpath(path, start=basedir)
command = ['sphinx-build', '-Q', '-b', 'html', basedir, builddir, path]
rel_path_html = os.path.splitext(rel_path)[0] + '.html'
builddir_path = os.path.join(builddir, rel_path_html)
result = not sphinx.build_main(command)
remove_override_file(path)
if not result:
task.builddir_path = None
task.return_error(GLib.Error('\'sphinx-build\' command error for {}'.format(path)))
return
task.builddir_path = builddir_path
task.return_boolean(True)
def sphinx_build(src_dir, build_dir):
import sphinx
cmd = [
"-b",
"html",
"-d",
op.join(build_dir, "doctrees"),
src_dir, # Source
op.join(build_dir, "html"), # Dest
]
if sphinx.version_info > (1, 7):
import sphinx.cmd.build
ret = sphinx.cmd.build.build_main(cmd)
else:
ret = sphinx.build_main(["sphinx-build"] + cmd)
if ret != 0:
raise RuntimeError("Sphinx error: %s" % ret)
print("Build finished. The HTML pages are in %s/html." % build_dir)
def build():
'''
Runs a clean Sphinx build of the blog.
'''
# clean build directory
if os.path.exists(paths.blog):
shutil.rmtree(paths.blog)
flags = ["sphinx-build"]
# silence Sphinx if in quiet mode
if output.quiet:
flags.append("-q")
flags += ["-d", paths.doctree, "-b", "html", paths.root, paths.html]
# build always prints "index.html"
output.filename.info("index.html")
# copy some extra files to the output directory
if os.path.exists("_copy"):
shutil.copytree("_copy/", paths.html)
return build_main(flags)
def build(self):
'''Render reStructuredText files with sphinx'''
return build_main(['sphinx-build', self.c.sphinx_path,
os.path.join(self.c.sphinx_path, self.c.output)])
if not _skip_apidoc:
# Clean out the apidoc temp tree. Leftovers here may create problems.
if os.path.isdir(_rst_temp_dir):
shutil.rmtree(_rst_temp_dir)
# Create .rst files in _rst_temp_dir.
for package in _source_packages:
rst_dir = os.path.join(_rst_temp_dir, package)
code_dir = os.path.join('..', package)
cmd_opts = ['--force', '-o' + rst_dir, code_dir]
sphinx.apidoc.main(['sphinx-apidoc'] + _apidoc_format + cmd_opts)
# Sync from _rst_temp_dir to _rst_base_dir.
if not os.path.isdir(_rst_base_dir):
os.mkdir(_rst_base_dir)
for dir_path, subdir_list, file_list in os.walk(_rst_temp_dir):
_sync_dir(dir_path, file_list)
# Get rid of _rst_temp_dir.
shutil.rmtree(_rst_temp_dir)
# Run sphinx. Convert all .rst files to target formats (_builders) into _build_output_dir.
for builder in _builders:
cmd_opts = ['-b', builder, '.', _build_output_dir]
res = sphinx.build_main(['sphinx-build'] + cmd_opts)
if res != 0:
raise RuntimeError('sphinx-build call failed for builder ' + builder)
# Open the documentation in browser.
if not _skip_load_in_browser:
# Open file in new tab (`new=2`) in browser.
html_file = os.path.join(_build_output_dir, 'index.html')
webbrowser.open(html_file, new=2)
wooMods='wooMods.rst'
with open(wooMods,'w') as f:
f.write('Woo modules\n######################\n\n')
f.write('.. toctree::\n\n')
for o in sorted(rsts):
print('USING',o)
if re.match('(^|.*/)wooExtra(\..*)?$',o):
print('[SKIPPED]')
continue
f.write(' %s\n'%o)
if 1:
for fmt in 'html','latex':
args=['','-T','-b',fmt,'-j','1','-d','../build/doctrees','../source','../build/%s'%fmt]
print('Calling sphinx.build_main with: '+' '.join(args))
builtins.woo_sphinx_fmt=fmt # this is used in conf.py
sphinx.build_main(args)
#
# document extra modules, in separate trees
#
import pkg_resources, shutil,re
for mName in [m for m in sys.modules if m.startswith('wooExtra.') and len(m.split('.'))==2]:
mod=sys.modules[mName]
srcDir='../source-extra/'+mod.KEY
outDir='../build-extra/'+mod.KEY
if not os.path.exists(srcDir): os.makedirs(srcDir)
outName=srcDir+'/index.rst'
print('WRITING OUTPUT FOR %s TO %s'%(mName,outName))
with open(outName,'w') as f:
f.write('.. note:: This page is not `documentation of Woo itself <http://www.woodem.org>`_, only of an extra module.\n\n')
f.write('%s module\n################################\n\n'%mName)
def build_documentation(working_dir,
source_packages, builders, apidoc_format=_apidoc_format,
rst_base_dir=_rst_base_dir, rst_temp_dir=_rst_temp_dir, build_output_dir=_build_output_dir,
skip_apidoc=_skip_apidoc, skip_load_in_browser=False, load_file=None,
rebuild=False):
def get_files_in_dir(directory):
"""Return a list of the file names in the given directory."""
return [file_name
for file_name in os.listdir(directory)
if os.path.isfile(os.path.join(directory, file_name))]
def get_dirs_in_dir(directory):
"""Return a list of the directory names in the given directory."""
return [dir_name
for dir_name in os.listdir(directory)
if os.path.isdir(os.path.join(directory, dir_name))]
def sync_dir(temp_dir, file_names, rst_base_dir, rst_temp_dir):
"""Sync the in ``temp_dir`` with the corresponding files under ``_rst_base_dir``. The
list of files should match ``file_names``."""
rel_dir = os.path.relpath(temp_dir, rst_temp_dir)
source_dir = os.path.join(rst_temp_dir, rel_dir)
target_dir = os.path.join(rst_base_dir, rel_dir)
if os.path.isdir(target_dir):
target_subdirs = get_dirs_in_dir(target_dir)
for subdir in target_subdirs:
source_subdir = os.path.join(source_dir, subdir)
target_subdir = os.path.join(target_dir, subdir)
if not os.path.isdir(source_subdir):
shutil.rmtree(target_subdir)
assert os.path.isdir(source_dir)
if not os.path.isdir(source_dir):
if os.path.isdir(target_dir):
shutil.rmtree(target_dir)
else:
if os.path.isdir(target_dir):
source_files = get_files_in_dir(source_dir)
target_files = get_files_in_dir(target_dir)
for file in source_files:
source_file_path = os.path.join(source_dir, file)
target_file_path = os.path.join(target_dir, file)
if not os.path.isfile(target_file_path):
# Copy missing files.
shutil.copy2(source_file_path, target_file_path)
# Copy mismatched files.
elif not filecmp.cmp(source_file_path, target_file_path, shallow=False):
shutil.copy2(source_file_path, target_file_path)
for file in target_files:
source_file_path = os.path.join(source_dir, file)
target_file_path = os.path.join(target_dir, file)
if not os.path.isfile(source_file_path):
# Delete files in target that shouldn't be there.
os.remove(target_file_path)
else:
shutil.copytree(source_dir, target_dir)
# Make sure everything matches now.
match, mismatch, error = filecmp.cmpfiles(source_dir, target_dir, file_names, shallow=False)
assert len(match) == len(file_names) and len(mismatch) == 0 and len(error) == 0
current_dir = os.getcwd()
os.chdir(working_dir)
build_output_dir = os.path.abspath(build_output_dir)
rst_base_dir = os.path.abspath(rst_base_dir)
rst_temp_dir = os.path.abspath(rst_temp_dir)
try:
if rebuild:
print('...rebuilding (with clean build directories)...')
for dir_to_clean in [rst_base_dir, build_output_dir]:
if os.path.isdir(dir_to_clean):
import time
shutil.rmtree(dir_to_clean)
time.sleep(1)
os.mkdir(dir_to_clean)
# Run sphinx-apidoc. Create the API .rst files in _rst_temp_dir, then sync to _rst_base_dir.
if not skip_apidoc:
# Clean out the apidoc temp tree. Leftovers here may create problems.
if os.path.isdir(rst_temp_dir):
shutil.rmtree(rst_temp_dir)
# Create .rst files in rst_temp_dir.
for package in source_packages:
rst_dir = os.path.join(rst_temp_dir, package)
code_dir = os.path.join('..', package)
cmd_opts = ['--force', '-o' + rst_dir, code_dir]
sphinx.apidoc.main(['sphinx-apidoc'] + apidoc_format + cmd_opts)
# Sync from _rst_temp_dir to _rst_base_dir.
if not os.path.isdir(rst_base_dir):
os.mkdir(rst_base_dir)
if not os.path.isdir(rst_temp_dir):
os.mkdir(rst_temp_dir)
for dir_path, subdir_list, file_list in os.walk(rst_temp_dir):
sync_dir(dir_path, file_list, rst_base_dir, rst_temp_dir)
# Get rid of _rst_temp_dir.
if os.path.isdir(rst_temp_dir):
shutil.rmtree(rst_temp_dir)
# Run sphinx. Convert all .rst files to target formats (_builders) into _build_output_dir.
for builder in builders:
cmd_opts = ['-b', builder, '.', build_output_dir]
res = None
# Work-around for Sphinx bug https://github.com/sphinx-doc/sphinx/issues/1974
# The bug is in milestone https://github.com/sphinx-doc/sphinx/milestones/1.3.2
for ii in range(20):
res = sphinx.build_main(['sphinx-build'] + cmd_opts)
if res == 0:
break
if res != 0:
raise RuntimeError('sphinx-build call failed for builder ' + builder)
# Open the documentation in browser.
if not skip_load_in_browser:
# Open file in new tab (`new=2`) in browser.
html_file = os.path.join(build_output_dir, load_file + '.html')
print('...opening {index} in default browser...'.format(index=html_file))
webbrowser.open(html_file, new=2)
finally:
os.chdir(current_dir)
wxversion.select('3.0')
# Purge and then rebuild the documentation with Sphinx
if os.path.exists('documentation/build'):
shutil.rmtree('documentation/build')
try:
import sphinx
except ImportError:
print 'You must have sphinx installed and in the Python path to build the Neuroptikon package. See <http://sphinx.pocoo.org/>.'
sys.exit(1)
# Work around bug in version of Sphinx on my Mac, which uses sys.argv, even when passed this argument
sphinx_args = ['-q', '-b', 'html', 'documentation/Source', 'documentation/build/Documentation']
if sys.platform == 'darwin':
saved_sys_argv = sys.argv
sys.argv = sphinx_args
result = sphinx.build_main(argv=sphinx_args) # python 2.7.8?
sys.argv = saved_sys_argv
else:
result = sphinx.main(argv=sphinx_args) # python 2.7.2?
if result != 0:
sys.exit(result)
# Assemble the platform-specific application settings.
if sys.platform == 'darwin':
# Mac build notes:
# 1. Install Python from http://www.python.org/ftp/python/2.5.4/python-2.5.4-macosx.dmg
# 2. Make that python active: sudo python_select python25 (?)
# 3. sudo easy_install py2app
# 4. sudo easy_install numpy
# 5. Install wxPython from http://downloads.sourceforge.net/wxpython/wxPython2.8-osx-unicode-2.8.9.2-universal-py2.5.dmg
def run(self):
if not _HAVE_SPHINX:
raise RuntimeError(
"You must install Sphinx to build or test the documentation.")
if sys.version_info[0] >= 3:
import doctest
from doctest import OutputChecker as _OutputChecker
# Match u or U (possibly followed by r or R), removing it.
# r/R can follow u/U but not precede it. Don't match the
# single character string 'u' or 'U'.
_u_literal_re = re.compile(
r"(\W|^)(?<![\'\"])[uU]([rR]?[\'\"])", re.UNICODE)
# Match b or B (possibly followed by r or R), removing.
# r/R can follow b/B but not precede it. Don't match the
# single character string 'b' or 'B'.
_b_literal_re = re.compile(
r"(\W|^)(?<![\'\"])[bB]([rR]?[\'\"])", re.UNICODE)
class _StringPrefixFixer(_OutputChecker):
def check_output(self, want, got, optionflags):
# The docstrings are written with python 2.x in mind.
# To make the doctests pass in python 3 we have to
# strip the 'u' prefix from the expected results. The
# actual results won't have that prefix.
want = re.sub(_u_literal_re, r'\1\2', want)
# We also have to strip the 'b' prefix from the actual
# results since python 2.x expected results won't have
# that prefix.
got = re.sub(_b_literal_re, r'\1\2', got)
return super(
_StringPrefixFixer, self).check_output(
want, got, optionflags)
def output_difference(self, example, got, optionflags):
example.want = re.sub(_u_literal_re, r'\1\2', example.want)
got = re.sub(_b_literal_re, r'\1\2', got)
return super(
_StringPrefixFixer, self).output_difference(
example, got, optionflags)
doctest.OutputChecker = _StringPrefixFixer
if self.test:
path = os.path.join(
os.path.abspath('.'), "doc", "_build", "doctest")
mode = "doctest"
else:
path = os.path.join(
os.path.abspath('.'), "doc", "_build", version)
mode = "html"
try:
os.makedirs(path)
except:
pass
sphinx_args = ["-E", "-b", mode, "doc", path]
# sphinx.main calls sys.exit when sphinx.build_main exists.
# Call build_main directly so we can check status and print
# the full path to the built docs.
if hasattr(sphinx, 'build_main'):
status = sphinx.build_main(sphinx_args)
else:
status = sphinx.main(sphinx_args)
if status:
raise RuntimeError("documentation step '%s' failed" % (mode,))
sys.stdout.write("\nDocumentation step '%s' performed, results here:\n"
" %s/\n" % (mode, path))
