def _plugin_build_docs(destdir, cfg):
"""Builds the Sphinx docs for the plugin distribution, assuming it has
a structure like the one created by plugin quickstart.
"""
name = cfg.get("metadata", "name")
version = cfg.get("metadata", "version")
path_added = False
try:
docdir = os.path.join(destdir, "docs")
srcdir = os.path.join(destdir, "src")
# have to add srcdir to sys.path or autodoc won't find source code
if srcdir not in sys.path:
sys.path[0:0] = [srcdir]
path_added = True
sphinx.main(
argv=[
"",
"-E",
"-a",
"-b",
"html",
"-Dversion=%s" % version,
"-Drelease=%s" % version,
"-d",
os.path.join(srcdir, name, "sphinx_build", "doctrees"),
docdir,
os.path.join(srcdir, name, "sphinx_build", "html"),
]
)
finally:
if path_added:
sys.path.remove(srcdir)
def _plugin_build_docs(destdir, cfg):
"""Builds the Sphinx docs for the plugin distribution, assuming it has
a structure like the one created by plugin quickstart.
"""
name = cfg.get('metadata', 'name')
version = cfg.get('metadata', 'version')
path_added = False
try:
docdir = os.path.join(destdir, 'docs')
srcdir = os.path.join(destdir, 'src')
# have to add srcdir to sys.path or autodoc won't find source code
if srcdir not in sys.path:
sys.path[0:0] = [srcdir]
path_added = True
sphinx.main(argv=[
'', '-E', '-a', '-b', 'html',
'-Dversion=%s' % version,
'-Drelease=%s' % version, '-d',
os.path.join(srcdir, name, 'sphinx_build', 'doctrees'), docdir,
os.path.join(srcdir, name, 'sphinx_build', 'html')
])
finally:
if path_added:
sys.path.remove(srcdir)
def build_docs(srcdir, destdir, confdir = None, page = None):
current_dir = os.getcwd()
os.chdir(srcdir)
_build_destdir = destdir
args = ['sphinx-build', # Fake argv[0]
'-b', 'html', # Use the JSON builder
'-q', # Do not output anything on standard output, only write warnings and errors to standard error.
srcdir, # Source file directory
_build_destdir, # Destination directory
]
if confdir:
args.insert(1, confdir)
args.insert(1, '-c')
if page:
args.append(os.path.join(srcdir, page.path))
else:
if os.path.exists(destdir):
shutil.rmtree(destdir)
if not os.path.exists(_build_destdir):
os.makedirs(_build_destdir)
import sphinx
sphinx.main(args)
os.chdir(current_dir)
def run(self):
# metadata contains information supplied in setup()
metadata = self.distribution.metadata
src_dir = (self.distribution.package_dir or {"": ""})[""]
src_dir = os.path.join(os.getcwd(), src_dir)
# Build docs from docstrings in *.py files
sphinx.apidoc.main(["", "-e", "-o", os.path.join("docs", "source", "api"), src_dir])
# Build the doc sources
sphinx.main(
[
"",
"-c",
"docs",
"-D",
"project=" + metadata.name,
"-D",
"version=" + metadata.version,
"-D",
"release=" + metadata.version,
os.path.join("docs", "source"),
os.path.join("docs", "build"),
]
)
def _plugin_build_docs(destdir, cfg):
"""Builds the Sphinx docs for the plugin distribution, assuming it has
a structure like the one created by plugin quickstart.
"""
name = cfg.get('metadata', 'name')
version = cfg.get('metadata', 'version')
path_added = False
try:
docdir = os.path.join(destdir, 'docs')
srcdir = os.path.join(destdir, 'src')
# have to add srcdir to sys.path or autodoc won't find source code
if srcdir not in sys.path:
sys.path[0:0] = [srcdir]
path_added = True
sphinx.main(argv=['', '-E', '-a', '-b', 'html',
'-Dversion=%s' % version,
'-Drelease=%s' % version,
'-d', os.path.join(srcdir, name, 'sphinx_build', 'doctrees'),
docdir,
os.path.join(srcdir, name, 'sphinx_build', 'html')])
finally:
if path_added:
sys.path.remove(srcdir)
def run(self):
docdir = op.join(basedir, 'doc')
destdir = op.join(docdir, 'html')
if op.exists(destdir):
shutil.rmtree(destdir)
print('Building documentation [{}]'.format(destdir))
import sphinx
try:
import unittest.mock as mock
except:
import mock
mockobj = mock.MagicMock()
mockedModules = open(op.join(docdir, 'mock_modules.txt')).readlines()
mockedClasses = open(op.join(docdir, 'mock_classes.txt')).readlines()
mockedModules = [l.strip() for l in mockedModules]
mockedClasses = [l.strip() for l in mockedClasses]
mockedModules = {m: mockobj for m in mockedModules}
patches = [mock.patch.dict('sys.modules', **mockedModules)] + \
[mock.patch('wx.lib.newevent.NewEvent',
return_value=(mockobj, mockobj))] + \
[mock.patch(c, object) for c in mockedClasses]
[p.start() for p in patches]
sphinx.main(['sphinx-build', docdir, destdir])
[p.stop() for p in patches]
def run(self):
try:
import sphinx
except ImportError:
log.info('Sphinx not installed -- skipping documentation. (%s)', sys.exc_info()[1])
return
if not os.path.exists(self.out_dir):
if self.dry_run:
self.announce('skipping creation of directory %s (dry run)' % self.out_dir)
else:
self.announce('creating directory %s' % self.out_dir)
os.makedirs(self.out_dir)
if self.dry_run:
self.announce('skipping %s (dry run)' % ' '.join(self.sphinx_args))
else:
self.announce('running %s' % ' '.join(self.sphinx_args))
opath = sys.path
try:
# We need to point Sphinx at the built library, including
# the extension module so that autodoc works properly.
sys.path.insert(0,os.path.realpath(self.build_lib))
sphinx.main(self.sphinx_args)
finally:
sys.path = opath;
def build_docs():
"""Build the Blogofile sphinx based documentation"""
#Abort if sphinx isn't installed
try:
import sphinx
except ImportError:
return
#print "Building the docs..."
#Configure the theme
#Insert the rendered head, headers, and footers into the theme
config = sys.modules[globals()['__name__']]
from mako.template import Template
head_t = Template(open(os.path.join("_templates","head.mako")).read())
head = head_t.render(**{'bf':bf})
header_t = Template(open(os.path.join("_templates","header.mako")).read())
header = header_t.render(**{'bf':bf})
footer_t = Template(open(os.path.join("_templates","footer.mako")).read())
footer = footer_t.render(**{'bf':bf})
#Create the new layout.html from preparse_layout.html
#Insert the rendered templates appropriately
layout = open(os.path.join("_documentation","themes","blogofile",
"preparse_layout.html")).read()
layout = layout.replace("blogofile_head_goes_here",head)
layout = layout.replace("blogofile_header_goes_here",header)
layout = layout.replace("blogofile_footer_goes_here",footer)
layout_f = open(os.path.join("_documentation","themes","blogofile",
"layout.html"),"w")
layout_f.write(layout)
layout_f.close()
logger.info("Compiling HTML Documentation..")
sphinx.main(shlex.split("sphinx-build -q -b html _documentation "+
os.path.join("_site","documentation")))
def intl_update(self):
ui.info(ui.blue, "::", ui.reset, "Generating message catalogs ...")
import sphinx
from sphinx_intl.commands import run as sphinx_intl_run
# First step: run sphinx-build -b gettext
cmd = [sys.executable, "-c", self.build_dir, "-b", "gettext"]
cmd.append(self.source_dir)
locale_dir = os.path.join(self.source_dir, "locale")
cmd.append(locale_dir)
rc = 0
try:
sphinx.main(argv=cmd)
except SystemExit as e:
rc = e.code
if rc != 0:
raise SphinxBuildError(self)
ui.info()
# Second step: run sphinx-intl update -l <lingua> for every lingua
ui.info(ui.blue, "::", ui.reset, "Updating .po files ...")
for i, lingua in enumerate(self.linguas):
ui.info_count(i, len(self.linguas), ui.blue, lingua)
cmd = [
"update", "-c",
os.path.join(self.build_dir, "conf.py"), "--pot-dir",
locale_dir, "--locale-dir", locale_dir, "--language", lingua
]
sphinx_intl_run(cmd)
def build(self, expected_return=0):
print("")
sys.argv = [
"sphinx-build", "-q", "-d", paths.doctree, "-b", "html",
paths.root, paths.html
]
sphinx.main(sys.argv)
def run(self):
docdir = op.join(basedir, 'doc')
destdir = op.join(docdir, 'html')
if op.exists(destdir):
shutil.rmtree(destdir)
print('Building documentation [{}]'.format(destdir))
import sphinx
try:
import unittest.mock as mock
except:
import mock
mockobj = mock.MagicMock()
mockobj.__version__ = '2.2.0'
mockedModules = open(op.join(docdir, 'mock_modules.txt')).readlines()
mockedModules = [l.strip() for l in mockedModules]
mockedModules = {m: mockobj for m in mockedModules}
patches = [mock.patch.dict('sys.modules', **mockedModules)]
[p.start() for p in patches]
sphinx.main(['sphinx-build', docdir, destdir])
[p.stop() for p in patches]
def build_html_doc(self):
"""Build the html documentation."""
try:
import sphinx
except ImportError:
self.warn("sphinx not found, documentation won't be build.")
return
sphinx_ver = sphinx.__version__
def digits(x):
res = re.match('\d+', x)
if res is None:
return 0
else:
return int(res.group())
if map(digits, sphinx_ver.split('.')) < [0, 5, 1]:
self.warn("Sphinx's version is too old (%s, expected at least "
"0.5.1, documentation won't be build." % sphinx_ver)
return
# Build the documentation just like it is done through the Makefile
sphinx.main([__file__,
"-b", "html",
"-d", os.path.join(BASE_DOCS_DIR, 'doctrees'),
os.path.join(BASE_DOCS_DIR, 'src'), DOCS_DIR])
def DoTask(self):
tmpDir = join(self.buildSetup.tmpDir, "chm")
Prepare()
#warnings.simplefilter('ignore', DeprecationWarning)
sphinx.main([
None,
#"-a",
"-b", "htmlhelp",
"-E",
"-P",
"-D", "release=%s" % eg.Version.base,
"-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):
# We import here to ensure that setup.py has had a chance to install the
# relevant package eggs first.
import sphinx
import sphinx.apidoc
metadata = self.distribution.metadata
src_dir = os.path.join(PYTHON_STEM, self.distribution.package_dir[""], "grpc")
sys.path.append(src_dir)
sphinx.apidoc.main(
[
"",
"--force",
"--full",
"-H",
metadata.name,
"-A",
metadata.author,
"-V",
metadata.version,
"-R",
metadata.version,
"-o",
os.path.join("doc", "src"),
src_dir,
]
)
conf_filepath = os.path.join("doc", "src", "conf.py")
with open(conf_filepath, "a") as conf_file:
conf_file.write(CONF_PY_ADDENDUM)
sphinx.main(["", os.path.join("doc", "src"), os.path.join("doc", "build")])
def run(self):
if self.clean:
if not os.path.exists(self.builddir):
print('Nothing to clean, quiting...')
return
prompt = ('This action will remove all files in {0}, '
'would you like to continue? (y/N)').format(
os.path.abspath(self.builddir))
try:
answer = raw_input(prompt)
except NameError:
answer = input(prompt)
finally:
if answer.lower() == 'y':
shutil.rmtree(self.builddir)
else:
print('Operation aborted.')
else:
import sphinx
sphinxbuild = os.environ.get('SPHINXBUILD', self.sphinxbuild)
sphinxopts = os.environ.get('SPHINXOPTS', self.sphinxopts)
args = '{0} -b {1} -d {2}/doctree {3} {4} {2}/{1}'
self._process_images()
for fmt in self.formats:
sphinx.main(args.format(sphinxbuild,
fmt, self.builddir, sphinxopts, self.sourcedir).split())
def intl_update(self):
ui.info(ui.blue, "::", ui.reset, "Generating message catalogs ...")
import sphinx
from sphinx_intl.commands import run as sphinx_intl_run
# First step: run sphinx-build -b gettext
cmd = [sys.executable, "-c", self.build_dir, "-b", "gettext"]
cmd.append(self.source_dir)
locale_dir = os.path.join(self.source_dir, "locale")
cmd.append(locale_dir)
rc = 0
try:
sphinx.main(argv=cmd)
except SystemExit as e:
rc = e.code
if rc != 0:
raise SphinxBuildError(self)
ui.info()
# Second step: run sphinx-intl update -l <lingua> for every lingua
ui.info(ui.blue, "::", ui.reset, "Updating .po files ...")
for i, lingua in enumerate(self.linguas):
ui.info_count(i, len(self.linguas), ui.blue, lingua)
cmd = ["update",
"-c", os.path.join(self.build_dir, "conf.py"),
"--pot-dir", locale_dir,
"--locale-dir", locale_dir,
"--language", lingua]
sphinx_intl_run(cmd)
def build(self, expected_return=0):
print("")
with mock.patch.object(sys, "exit") as mock_exit:
sys.argv = ["sphinx-build", "-q", "-d", paths.doctree, "-b", "html", paths.root, paths.html]
sphinx.main(sys.argv)
mock_exit.assert_called_once_with(expected_return)
def _plugin_build_docs(destdir, cfg, src="src"):
"""Builds the Sphinx docs for the plugin distribution, assuming it has
a structure like the one created by plugin quickstart.
"""
name = cfg.get("metadata", "name")
version = cfg.get("metadata", "version")
docdir = os.path.join(destdir, "docs")
srcdir = os.path.abspath(os.path.join(destdir, src))
sphinx.main(
argv=[
"",
"-E",
"-a",
"-b",
"html",
"-Dversion=%s" % version,
"-Drelease=%s" % version,
"-d",
os.path.join(srcdir, name, "sphinx_build", "doctrees"),
docdir,
os.path.join(srcdir, name, "sphinx_build", "html"),
]
)
def run(self):
try:
import sphinx
except ImportError:
log.info('Sphinx not installed -- skipping documentation. (%s)',
sys.exc_info()[1])
return
if not os.path.exists(self.out_dir):
if self.dry_run:
self.announce('skipping creation of directory %s (dry run)' %
self.out_dir)
else:
self.announce('creating directory %s' % self.out_dir)
os.makedirs(self.out_dir)
if self.dry_run:
self.announce('skipping %s (dry run)' % ' '.join(self.sphinx_args))
else:
self.announce('running %s' % ' '.join(self.sphinx_args))
opath = sys.path
try:
# We need to point Sphinx at the built library, including
# the extension module so that autodoc works properly.
sys.path.insert(0, os.path.realpath(self.build_lib))
sphinx.main(self.sphinx_args)
finally:
sys.path = opath
def build_docs(parser=None, options=None, args=None):
"""A script (openmdao build_docs) points to this. It generates the Sphinx
documentation for openmdao.
"""
global _is_release
if args and parser:
print_sub_help(parser, 'build_docs')
return -1
if options is not None and hasattr(options, 'version') and options.version:
version = options.version
shtitle = 'OpenMDAO Documentation v%s' % version
_is_release = True
else:
_is_release = False
try:
tag, ncommits, commit = get_rev_info()
version = "%s-%s-%s" % (tag, ncommits, commit)
shtitle = 'OpenMDAO Documentation (%s commits after version %s)' % (ncommits, tag)
except:
# try to get commit id
try:
top = get_ancestor_dir(sys.executable, 3)
if '-OpenMDAO-Framework-' in top:
commit = top.split('-')[-1]
version = "dev - commit id: %s" % commit
shtitle = "OpenMDAO Documentation (commit id %s)" % commit
else:
raise RuntimeError("can't find commit id")
except:
version = "?-?-?"
shtitle = "OpenMDAO Documentation (unknown revision)"
branchdir, docdir, bindir = _get_dirnames()
startdir = os.getcwd()
if not os.path.isdir(docdir):
raise RuntimeError('doc directory '+docdir+' not found')
_write_src_docs(branchdir, docdir)
_make_license_table(docdir)
os.chdir(docdir)
try:
# make necessary directories
if os.path.isdir(os.path.join('_build', 'html')):
shutil.rmtree(os.path.join('_build', 'html'), onerror=onerror)
if os.path.isdir(os.path.join('_build', 'doctrees')):
shutil.rmtree(os.path.join('_build', 'doctrees'), onerror=onerror)
os.makedirs(os.path.join('_build', 'html'))
os.makedirs(os.path.join('_build', 'doctrees'))
sphinx.main(argv=['-P', '-b', 'html',
'-Dhtml_short_title=%s' % shtitle,
'-Dversion=%s' % version,
'-Drelease=%s' % version,
'-d', os.path.join(docdir, '_build', 'doctrees'),
docdir, os.path.join(docdir, '_build', 'html')])
finally:
os.chdir(startdir)
def ablog_build(builder=None,
sourcedir=None,
website=None,
doctrees=None,
traceback=False,
runpdb=False,
allfiles=False,
**kwargs):
confdir = find_confdir()
conf = read_conf(confdir)
website = (website or os.path.join(
confdir, getattr(conf, 'ablog_builddir', '_website')))
doctrees = (doctrees or os.path.join(
confdir, getattr(conf, 'ablog_doctrees', '.doctrees')))
sourcedir = (sourcedir or confdir)
argv = sys.argv[:1]
argv.extend(['-b', builder or getattr(conf, 'ablog_builder', 'dirhtml')])
argv.extend(['-d', doctrees])
if traceback:
argv.extend(['-T'])
if runpdb:
argv.extend(['-P'])
if allfiles:
argv.extend(['-a'])
argv.extend([sourcedir, website])
from sphinx import main
main(argv)
def run(self):
import sphinx
from sphinx import apidoc
sphinx_args = ['-P', '-n', '-c', 'documentation/', '.']
apidoc_args = []
if self.cathartic:
sphinx_args = ['-a', '-E'] + sphinx_args
apidoc_args = ['--force'] + apidoc_args
apidoc.main(
['sphinx-apidoc', '--output-dir=fipy/generated', '--suffix=rst'] +
apidoc_args + ['fipy'])
apidoc.main([
'sphinx-apidoc',
'--output-dir=documentation/tutorial/package/generated',
'--suffix=rst'
] + apidoc_args + ['documentation/tutorial/package'])
if self.html:
sphinx.main(['sphinx-build', '-b', 'redirecting_html'] +
sphinx_args + ['documentation/_build/html/'])
if self.pdf:
try:
sphinx.main(['sphinx-build', '-b', 'latex'] + sphinx_args +
['documentation/_build/latex/'])
except SystemExit:
pass
outdir = os.path.join('documentation', '_build', 'latex')
from docutils.core import publish_file
for xtra in ("LICENSE", "DISCLAIMER"):
publish_file(source_path="%s.rst" % xtra,
destination_path=os.path.join(
outdir, "%s.tex" % xtra),
reader_name='standalone',
parser_name='restructuredtext',
writer_name='latex',
settings_overrides={
'template':
'documentation/_templates/empty.tex'
})
savedir = os.getcwd()
os.chdir(outdir)
os.system("pdflatex fipy")
os.system("pdflatex fipy")
os.system("pdflatex fipy")
os.system("makeindex -s python.ist fipy")
os.system("makeindex -s python.ist modfipy")
os.system("pdflatex fipy")
os.system("pdflatex fipy")
os.chdir(savedir)
def DoTask(self):
tmpDir = join(self.buildSetup.tmpDir, "chm")
Prepare()
#warnings.simplefilter('ignore', DeprecationWarning)
sphinx.main([
None,
#"-a",
"-b",
"htmlhelp",
"-E",
"-P",
"-D",
"release=%s" % eg.Version.base,
"-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 main(self, format):
'''Create the documentation.
'''
if format not in FORMATS:
raise Exception, 'bad format'
self.writeModuleReference()
self.writeGeneratedChapters()
self.writeContents()
if format == 'html':
dirOut = self.dirBuildHtml
pathLaunch = os.path.join(self.dirBuildHtml, 'contents.html')
elif format == 'latex':
dirOut = self.dirBuildLatex
#pathLaunch = os.path.join(dirBuildHtml, 'contents.html')
elif format == 'pdf':
dirOut = self.dirBuildPdf
else:
raise Exception('undefined format %s' % format)
if common.getPlatform() in ['darwin', 'nix', 'win']:
# -b selects the builder
import sphinx
sphinxList = ['sphinx', '-E', '-b', format, '-d', self.dirBuildDoctrees,
self.dirRst, dirOut]
sphinx.main(sphinxList)
if format == 'html':
webbrowser.open(pathLaunch)
def build_sphinx_build():
#Abort if sphinx isn't installed
try:
import sphinx
except ImportError:
return
#print "Building the docs..."
#Configure the theme
#Insert the rendered head, headers, and footers into the theme
config = sys.modules[globals()['__name__']]
from mako.template import Template
head_t = Template(open(os.path.join("_templates", "head.mako")).read())
head = head_t.render(**{'bf': bf})
header_t = Template(open(os.path.join("_templates", "header.mako")).read())
header = header_t.render(**{'bf': bf})
footer_t = Template(open(os.path.join("_templates", "footer.mako")).read())
footer = footer_t.render(**{'bf': bf})
#Create the new layout.html from preparse_layout.html
#Insert the rendered templates appropriately
layout = open(
os.path.join("_documentation", "themes", "blogofile",
"preparse_layout.html")).read()
layout = layout.replace("blogofile_head_goes_here", head)
layout = layout.replace("blogofile_header_goes_here", header)
layout = layout.replace("blogofile_footer_goes_here", footer)
layout_f = open(
os.path.join("_documentation", "themes", "blogofile", "layout.html"),
"w")
layout_f.write(layout)
layout_f.close()
logger.info("Compiling HTML Documentation..")
sphinx.main(
shlex.split("sphinx-build -q -b html _documentation " +
os.path.join("_site", "documentation")))
def build(self, expected_return=0):
print("")
with mock.patch.object(sys, 'exit') as mock_exit:
sys.argv = ["sphinx-build", "-q", "-d", paths.doctree, "-b",
"html", paths.root, paths.html]
sphinx.main(sys.argv)
mock_exit.assert_called_once_with(expected_return)
def run(self):
import sphinx, shutil, os
if os.path.exists("docs/build/html"):
shutil.rmtree("docs/build/html")
self.mkpath("docs/build/html")
sphinx.main(["-E", "docs", "docs/build/html"])
def call_sphinx(builder, workdir, extraopts=None):
import sphinx
if extraopts is None:
extraopts = []
if not options['--cache']:
extraopts.append('-E')
sphinx.main(['', '-b', builder] + extraopts +
[os.path.join(throot, 'doc'), workdir])
def build(self, **kwargs):
""" Run sphinx.main() with the correct arguments """
try:
import sphinx
except ImportError as e:
ui.error(e, "skipping build")
return
build_type = kwargs.get("build_type", None)
language = kwargs.get("language", None)
spellcheck = kwargs.get("spellcheck", False)
werror = kwargs.get("werror", False)
pdb = kwargs.get("pdb", False)
if self.prebuild_script:
ui.info(ui.green, "Running pre-build script:", ui.white,
self.prebuild_script)
cmd = [sys.executable, self.prebuild_script]
qisys.command.call(cmd, cwd=self.path)
ui.info()
self.generate_examples_zips()
if self.translated and language and language != "en" \
and language not in self.linguas:
raise UnknownLingua(self, language)
if self.translated:
self.intl_build(language)
qisys.sh.mkdir(self.html_dir, recursive=True)
spell_dir = os.path.join(self.build_dir, "spellcheck")
qisys.sh.mkdir(spell_dir, recursive=True)
cmd = [sys.executable, "-c", self.build_dir]
if spellcheck:
cmd.extend(("-b", "spelling"))
else:
cmd.extend(("-b", "html"))
if werror:
cmd.append("-W")
if language:
cmd.append("-Dlanguage=%s" % language)
if pdb:
cmd.append("-P")
cmd.append(self.source_dir)
if spellcheck:
cmd.append(spell_dir)
else:
cmd.append(self.html_dir)
if build_type:
os.environ["build_type"] = build_type
ui.debug("launching:", cmd)
rc = 0
try:
sphinx.main(argv=cmd)
except SystemExit as e:
rc = e.code
if spellcheck:
num_errors = get_num_spellcheck_errors(self.build_dir)
if num_errors != 0:
raise SphinxBuildError(self)
if rc != 0:
raise SphinxBuildError(self)
def build(self, **kwargs):
""" Run sphinx.main() with the correct arguments """
try:
import sphinx
except ImportError as e:
ui.error(e, "skipping build")
return
build_type = kwargs.get("build_type", None)
language = kwargs.get("language", None)
spellcheck = kwargs.get("spellcheck", False)
werror = kwargs.get("werror", False)
pdb = kwargs.get("pdb", False)
if self.prebuild_script:
ui.info(ui.green, "Running pre-build script:",
ui.white, self.prebuild_script)
cmd = [sys.executable, self.prebuild_script]
qisys.command.call(cmd, cwd=self.path)
ui.info()
self.generate_examples_zips()
if self.translated and language and language != "en" \
and language not in self.linguas:
raise UnknownLingua(self, language)
if self.translated:
self.intl_build(language)
qisys.sh.mkdir(self.html_dir, recursive=True)
spell_dir = os.path.join(self.build_dir, "spellcheck")
qisys.sh.mkdir(spell_dir, recursive=True)
cmd = [sys.executable, "-c", self.build_dir]
if spellcheck:
cmd.extend(("-b", "spelling"))
else:
cmd.extend(("-b", "html"))
if werror:
cmd.append("-W")
if language:
cmd.append("-Dlanguage=%s" % language)
if pdb:
cmd.append("-P")
cmd.append(self.source_dir)
if spellcheck:
cmd.append(spell_dir)
else:
cmd.append(self.html_dir)
if build_type:
os.environ["build_type"] = build_type
ui.debug("launching:", cmd)
rc = 0
try:
sphinx.main(argv=cmd)
except SystemExit as e:
rc = e.code
if spellcheck:
num_errors = get_num_spellcheck_errors(self.build_dir)
if num_errors != 0:
raise SphinxBuildError(self)
if rc != 0:
raise SphinxBuildError(self)
def sphinx_build(src_dir, build_dir):
import sphinx
sphinx.main(( 'sphinx-build', # Dummy
'-b', 'html',
'-d', os.path.join(build_dir, 'doctrees'),
src_dir, # Source
os.path.join(build_dir, 'html'), # Dest
))
print("Build finished. The HTML pages are in %s/html." % build_dir)
def build_pdf(output_path=os.path.abspath('./docs/pdf/MTfit.pdf')):
print(
"------------------------------\n\nLaTeX Build\n\n------------------------------"
)
try:
sphinx.main([
'sphinx', '-b', 'latex', '-a',
os.path.abspath('./docs/source/'),
os.path.abspath('./docs/latex/')
])
except SystemExit:
pass
os.chdir('./docs/latex/')
try:
os.remove('MTfit.toc')
except Exception:
pass
try:
os.remove('MTfit.aux')
except Exception:
pass
try:
os.remove('MTfit.idx')
except Exception:
pass
# modify table of contents location
tex = open('MTfit.tex').readlines()
if '\\endabstract\n' in tex:
tex.insert(tex.index('\\endabstract\n'),
tex.pop(tex.index('\\sphinxtableofcontents\n')))
with open('MTfit.tex', 'w') as f:
f.write(''.join(tex))
print(
"------------------------------\n\nPDF Build\n\n------------------------------"
)
# Two compiles to update toc
p = subprocess.Popen(['pdflatex', '-interaction=nonstopmode', 'MTfit.tex'],
stdout=subprocess.PIPE,
stderr=subprocess.STDOUT)
(bout, berr) = p.communicate()
p2 = subprocess.Popen(
['pdflatex', '-interaction=nonstopmode', 'MTfit.tex'],
stdout=subprocess.PIPE,
stderr=subprocess.STDOUT)
(b2out, b2err) = p2.communicate()
if sys.version_info.major >= 3:
bout = bout.decode()
b2out = b2out.decode()
print(bout)
os.chdir('../../')
if 'fatal error occured' in bout.lower() + b2out.lower():
raise Exception('Fatal Error in PDF generation')
try:
os.mkdir('./docs/pdf')
except Exception:
pass
shutil.move('./docs/latex/MTfit.pdf', output_path)
def sphinx_build(src_dir, build_dir):
import sphinx
sphinx.main(( 'sphinx-build', # Dummy
'-b', 'html',
'-d', os.path.join(build_dir, 'doctrees'),
src_dir, # Source
os.path.join(build_dir, 'html'), # Dest
))
print("Build finished. The HTML pages are in %s/html." % build_dir)
def run(self):
# metadata contains information supplied in setup()
metadata = self.distribution.metadata
# package_dir may be None, in that case use the current directory.
src_dir = (self.distribution.package_dir or {'': ''})['']
src_dir = os.path.join(os.getcwd(), src_dir)
import sphinx
sphinx.main(['runme',
'-D', 'version=%s' % metadata.get_version(),
os.path.join('docs',), os.path.join(self.built_docs, 'docs')])
def run(self):
# metadata contains information supplied in setup()
metadata = self.distribution.metadata
# package_dir may be None, in that case use the current directory.
src_dir = (self.distribution.package_dir or {'': ''})['']
src_dir = os.path.join(os.getcwd(), src_dir)
import sphinx
sphinx.main(['runme',
'-D', 'version=%s' % metadata.get_version(),
os.path.join('docs',), os.path.join(self.built_docs, 'docs')])
def test_docs():
"""Tests the openmdao sphinx documentation.
A console script (openmdao_testdocs) calls this.
This forces a build of the docs before testing.
"""
branchdir, docdir, bindir =_get_dirnames()
# force a new build before testing
build_docs()
sphinx.main(argv=['-P', '-b', 'doctest', '-d',
os.path.join(docdir, '_build', 'doctrees'),
docdir, os.path.join(docdir, '_build', 'html')])
def build_epub(output_path=os.path.abspath('./docs/epub/')):
print(
"------------------------------\n\nepub Build\n\n------------------------------"
)
try:
sphinx.main([
'sphinx', '-b', 'epub', '-a',
os.path.abspath('./docs/source/'), output_path
])
except SystemExit:
pass
def build_man_pages(output_path=os.path.abspath('./docs/man/')):
print(
"------------------------------\n\nMan Build\n\n------------------------------"
)
try:
sphinx.main([
'sphinx', '-b', 'man', '-a',
os.path.abspath('./docs/source/'), output_path
])
except SystemExit:
pass
def build_html(output_path=os.path.abspath('./docs/html/')):
print(
"------------------------------\n\nHTML Build\n\n------------------------------"
)
try:
sphinx.main([
'sphinx', '-b', 'html', '-a',
os.path.abspath('./docs/source/'), output_path
])
except SystemExit:
pass
def run(self):
import sphinx
metadata = self.distribution.metadata
docs = os.path.join(os.getcwd(), 'docs')
sphinx.main([
'', '-D', 'project=' + metadata.name, '-D',
'copyright={}, {}'.format(datetime.now().year, metadata.author),
'-D', 'version=' + metadata.version, '-D',
'release=' + metadata.version, docs,
os.path.join(docs, '_build')
])
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.main(['', '-b', builder] + extraopts + inopt)
def test_build_docs(self):
docdir = os.path.join(self.topdir, 'docs')
os.chdir(docdir)
htmldir = self.tempdir
args = ['sphinx', '-b', 'html', '-nW', '.', htmldir]
if self.verbose < 3:
args += ['-Q']
try:
sphinx.main(args)
except SystemExit as e:
ret = e.code
self.assertEqual(ret, 0)
def test_build_docs(self):
docdir = os.path.join(self.topdir, 'docs')
os.chdir(docdir)
htmldir = self.tempdir
args = ['sphinx', '-b', 'html', '-nW', '.', htmldir]
if self.verbose < 3:
args += ['-Q']
try:
sphinx.main(args)
except SystemExit as e:
ret = e.code
self.assertEqual(ret, 0)
def run (self):
import sphinx
from sphinx import apidoc
sphinx_args = ['-P', '-n', '-c', 'documentation/', '.']
apidoc_args = []
if self.cathartic:
sphinx_args = ['-a', '-E'] + sphinx_args
apidoc_args = ['--force'] + apidoc_args
apidoc.main(['sphinx-apidoc', '--output-dir=fipy/generated', '--suffix=rst']
+ apidoc_args + ['fipy'])
apidoc.main(['sphinx-apidoc', '--output-dir=documentation/tutorial/package/generated', '--suffix=rst']
+ apidoc_args + ['documentation/tutorial/package'])
if self.html:
sphinx.main(['sphinx-build', '-b', 'redirecting_html'] + sphinx_args + ['documentation/_build/html/'])
if self.pdf:
try:
sphinx.main(['sphinx-build', '-b', 'latex'] + sphinx_args + ['documentation/_build/latex/'])
except SystemExit:
pass
outdir = os.path.join('documentation', '_build', 'latex')
from docutils.core import publish_file
for xtra in ("LICENSE", "DISCLAIMER"):
publish_file(source_path="%s.rst" % xtra,
destination_path=os.path.join(outdir, "%s.tex" % xtra),
reader_name='standalone',
parser_name='restructuredtext',
writer_name='latex',
settings_overrides= {
'template': 'documentation/_templates/empty.tex'
})
savedir = os.getcwd()
os.chdir(outdir)
os.system("pdflatex fipy")
os.system("pdflatex fipy")
os.system("pdflatex fipy")
os.system("makeindex -s python.ist fipy")
os.system("makeindex -s python.ist modfipy")
os.system("pdflatex fipy")
os.system("pdflatex fipy")
os.chdir(savedir)
def build_sphinx_pdf():
#Do PDF generation if TeX is installed
if os.path.isfile("/usr/bin/tex"):
latex_dir = tempfile.mkdtemp()
logger.info("Compiling PDF Documentation..")
sphinx.main(shlex.split("sphinx-build -q -b latex _documentation "+
latex_dir))
subprocess.Popen(shlex.split(
"make -C %s all-pdf" % latex_dir),
stdout=subprocess.PIPE,
stderr=subprocess.PIPE).communicate()
shutil.copyfile(os.path.join(latex_dir,"Blogofile.pdf"),
os.path.join("_site","documentation","Blogofile.pdf"))
def test_docs(options, args=None):
"""Tests the openmdao sphinx documentation.
A console script (openmdao test_docs) calls this.
This forces a build of the docs before testing.
"""
branchdir, docdir, bindir = _get_dirnames()
# force a new build before testing
build_docs()
sphinx.main(argv=[
'-P', '-b', 'doctest', '-d',
os.path.join(docdir, '_build', 'doctrees'), docdir,
os.path.join(docdir, '_build', 'html')
])
def DoTask(self):
Prepare()
sphinx.main([
None,
#"-a",
"-b", "html",
#"-E",
"-P",
"-D", "release=%s" % eg.Version.base,
"-d", join(self.buildSetup.tmpDir, ".doctree"),
DOCS_SOURCE_DIR,
join(self.buildSetup.sourceDir, "website", "docs"),
])
def genere_doc():
"""
Fonction de génération de l'autodocumentation. La documentation sera générée a chaque appel de cette procédure.
.. warning:: Cette fonction peut faire ressortir certain warning sans raison apparente. Cela n'influe pas sur le résultat de la documentation qui sera tout de même générée mais il sera nécessaire de couper l'éxécution de la console de manière manuelle afin d'effectuer une nouvelle éxécution (appuyer sur le bouton en forme e fleche verte en haut a droite de la console)
"""
sphinx.apidoc.main(['sphinx-apidoc', '-f', '--output-dir=doc/generated', './'])
sphinx.main(['sphinx-build', '-b', 'html', 'doc', 'doc/_build/html'])
# sphinx.main(['sphinx-build', '-b', 'latex', 'doc', 'doc/_build/latex'])
def run(self):
import sphinx
from sphinx import apidoc
sphinx_args = ["-P", "-n", "-c", "documentation/", "."]
apidoc_args = []
if self.cathartic:
sphinx_args = ["-a", "-E"] + sphinx_args
apidoc_args = ["--force"] + apidoc_args
apidoc.main(["sphinx-apidoc", "--output-dir=fipy/generated", "--suffix=txt"] + apidoc_args + ["fipy"])
apidoc.main(
["sphinx-apidoc", "--output-dir=documentation/tutorial/package/generated", "--suffix=txt"]
+ apidoc_args
+ ["documentation/tutorial/package"]
)
if self.html:
sphinx.main(["sphinx-build", "-b", "redirecting_html"] + sphinx_args + ["documentation/_build/html/"])
if self.pdf:
sphinx.main(["sphinx-build", "-b", "latex"] + sphinx_args + ["documentation/_build/latex/"])
outdir = os.path.join("documentation", "_build", "latex")
from docutils.core import publish_file
for xtra in ("LICENSE", "DISCLAIMER"):
publish_file(
source_path="%s.txt" % xtra,
destination_path=os.path.join(outdir, "%s.tex" % xtra),
reader_name="standalone",
parser_name="restructuredtext",
writer_name="latex",
settings_overrides={"template": "documentation/_templates/empty.tex"},
)
savedir = os.getcwd()
os.chdir(outdir)
os.system("pdflatex fipy")
os.system("pdflatex fipy")
os.system("pdflatex fipy")
os.system("makeindex -s python.ist fipy")
os.system("makeindex -s python.ist modfipy")
os.system("pdflatex fipy")
os.system("pdflatex fipy")
os.chdir(savedir)
def test_buildhtml(self):
if not os.path.exists('.test_sphinxext/'):
os.makedirs('.test_sphinxext/')
try:
sphinx.main([
'',
'-b', 'html',
'-d', '.test_sphinxext/doctree',
docpath,
'.test_sphinxext/html'
])
assert Exception("Should raise SystemExit 0")
except SystemExit as e:
assert e.code == 0
def build_sphinx_pdf():
#Do PDF generation if TeX is installed
if os.path.isfile("/usr/bin/tex"):
latex_dir = tempfile.mkdtemp()
logger.info("Compiling PDF Documentation..")
sphinx.main(
shlex.split("sphinx-build -q -b latex _documentation " +
latex_dir))
subprocess.Popen(shlex.split("make -C %s all-pdf" % latex_dir),
stdout=subprocess.PIPE,
stderr=subprocess.PIPE).communicate()
shutil.copyfile(
os.path.join(latex_dir, "Blogofile.pdf"),
os.path.join("_site", "documentation", "Blogofile.pdf"))
def runSphinx(self):
try:
import sphinx
except ImportError:
message = 'Sphinx is required to build documentation; '
message += 'download from http://sphinx-doc.org'
raise ImportError(message)
target = self.command
if target == 'latexpdf':
target = 'latex'
# other options are in source/conf.py,
sphinxOptions = ['sphinx']
sphinxOptions.extend(('-b', target))
sphinxOptions.extend(('-d', self.doctreesDirectoryPath))
if self.useMultiprocessing:
sphinxOptions.extend(('-j', str(self.cpus_to_use)))
sphinxOptions.append(self.autogenDirectoryPath)
sphinxOptions.append(self.buildDirectories[target])
# sphinx.main() returns 0 on success, 1 on failure.
# If the docs fail to build, we should not try to open a web browser.
returnCode = 0
try:
returnCode = sphinx.main(sphinxOptions) # pylint: disable=assignment-from-no-return
except SystemExit:
returnCode = 0
if returnCode == 1:
raise DocBuilderException(
"Build failed (or nothing to build), no web browser being launched"
)
def run(self):
# We import here to ensure that setup.py has had a chance to install the
# relevant package eggs first.
import sphinx
import sphinx.apidoc
metadata = self.distribution.metadata
src_dir = os.path.join(PYTHON_STEM, 'grpc')
sys.path.append(src_dir)
sphinx.apidoc.main([
'', '--force', '--full', '-H', metadata.name, '-A', metadata.author,
'-V', metadata.version, '-R', metadata.version,
'-o', os.path.join('doc', 'src'), src_dir])
conf_filepath = os.path.join('doc', 'src', 'conf.py')
with open(conf_filepath, 'a') as conf_file:
conf_file.write(CONF_PY_ADDENDUM)
sphinx.main(['', os.path.join('doc', 'src'), os.path.join('doc', 'build')])
