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 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))