def test_text_documentation(self):
Sphinx(
self.SOURCE_DIR,
self.CONFIG_DIR,
self.OUTPUT_DIR,
self.DOCTREE_DIR,
buildername="text",
warningiserror=True,
).build(force_all=True)
def run(self):
from sphinx.application import Sphinx
sph = Sphinx(
'./docs', # source directory
'./docs', # directory containing conf.py
'./docs/_build/latex', # output directory
'./docs/_build/doctrees', # doctree directory
'latex') # finally, specify the latex builder
sph.build()
def rebuild(confoverrides=None, **kwargs):
app = Sphinx(srcdir=".",
confdir=".",
outdir="_build/text",
doctreedir="_build/.doctrees",
buildername="text",
confoverrides=confoverrides,
**kwargs)
app.build()
def runsphinx(text, builder, confoverrides):
f = open(os.path.join(_srcdir, 'index.rst'), 'w')
try:
f.write(text)
finally:
f.close()
app = Sphinx(_srcdir, _fixturedir, _outdir, _outdir, builder,
confoverrides)
app.build()
def build_help(dist_dir=None):
try:
if not dist_dir:
dist_dir = os.path.join(os.path.dirname(__file__), 'html')
app = Sphinx(os.path.dirname(__file__), os.path.dirname(__file__),
dist_dir, os.path.join(dist_dir, '.doctrees'), 'html')
app.build([])
except Exception as e:
print(e)
def render_sphinx(content):
with tempfile.TemporaryDirectory() as tmp_dir:
src_path = pathlib.Path(tmp_dir, "src/contents.rst")
src_path.parent.mkdir()
with src_path.open("w") as src:
src.write(content)
build_path = pathlib.Path(tmp_dir, "build/contents.fjson")
source_dir = str(src_path.parent)
doctree_dir = os.path.join(source_dir, ".doctrees")
confoverrides = {
"extensions": ["zuul_sphinx"],
"master_doc": "contents"
}
status_log = io.StringIO()
# NOTE (fschmidt): This part needs to be in sync with the used version
# of Sphinx. Current version is:
# https://github.com/sphinx-doc/sphinx/blob/v1.8.1/sphinx/cmd/build.py#L299
with patch_docutils(source_dir), docutils_namespace():
# Remove the color from the Sphinx' console output. Otherwise
# the lines cannot be parsed properly as some \n are not set properly.
nocolor()
app = Sphinx(
srcdir=source_dir,
confdir=None,
outdir=str(build_path.parent),
doctreedir=doctree_dir,
buildername="json",
confoverrides=confoverrides,
status=status_log,
warning=sys.stderr,
)
# Add the mocked SupportedOS directive to get the os information
# without rendering it into the resulting HTML page
app.add_directive("supported_os", SupportedOS)
# Start the Sphinx build
app.build(force_all=True, filenames=[])
if app.statuscode:
raise SphinxBuildError
# Extract the platforms from the logger output
platforms = []
status_log.seek(0)
for line in status_log.readlines():
prefix, _, platform = line.partition(":")
if prefix == SUPPORTED_OS_LOG_PREFIX:
platforms.append(platform.strip().lower())
with build_path.open() as build:
html_parts = json.load(build)
return {"html": html_parts["body"], "platforms": platforms}
def get_sphinx_app(srcdir, outdir, docname):
stdout = io.StringIO()
stderr = io.StringIO()
app = Sphinx(
srcdir, srcdir, outdir, outdir, 'spelling',
status=stdout, warning=stderr,
freshenv=True,
)
return (stdout, stderr, app)
def run(self):
from sphinx.application import Sphinx
sph = Sphinx(
'./docs/source', # source directory
'./docs/source', # directory containing conf.py
'./docs/build', # output directory
'./docs/build/doctrees', # doctree directory
'doctest') # finally, specify the doctest builder
sph.build()
def mock_sphinx_env_compat(
conf=None,
srcdir=None,
document=None,
with_builder=False,
raise_on_warning=False,
):
"""Set up an environment, to parse sphinx roles/directives,
outside of a `sphinx-build`.
:param conf: a dictionary representation of the sphinx `conf.py`
:param srcdir: a path to a source directory
(for example, can be used for `include` statements)
This primarily copies the code in `sphinx.util.docutils.docutils_namespace`
and `sphinx.util.docutils.sphinx_domains`.
"""
with tempfile.TemporaryDirectory() as tempdir:
# store currently loaded roles/directives, so we can revert on exit
_directives = copy.copy(directives._directives)
_roles = copy.copy(roles._roles)
# creating a builder attempts to make the doctreedir
app = Sphinx(
srcdir=srcdir,
confdir=None,
outdir=tempdir,
doctreedir=tempdir,
confoverrides=conf,
buildername=with_builder,
warningiserror=raise_on_warning,
keep_going=True,
)
_sphinx_domains = sphinx_domains(app.env)
_sphinx_domains.enable()
if document is not None:
document.settings.env = app.env
try:
yield app
finally:
# NOTE: the following cleanup is to avoid warnings while creating a Sphinx
# Application multiple times
# revert loaded roles/directives
directives._directives = _directives
roles._roles = _roles
for node in list(additional_nodes):
unregister_node(node)
additional_nodes.discard(node)
# revert directive/role function (ee
# `sphinx.util.docutils.sphinx_domains`)
_sphinx_domains.disable()
def sphinxify(docstring, context, buildername='html', img_path=''):
"""
Largely modified Spyder's sphinxify.
"""
# if not img_path:
# img_path = os.path.join(CONFDIR, "_images")
if img_path:
if os.name == 'nt':
img_path = img_path.replace('\\', '/')
leading = '/' if os.name.startswith('posix') else ''
docstring = docstring.replace('_images', leading + img_path)
srcdir = CONFDIR
# srcdir = encoding.to_unicode_from_fs(srcdir)
base_name = osp.join(srcdir, xrtQookPageName)
rst_name = base_name + '.rst'
# This is needed so users can type \\ on latex eqnarray envs inside raw
# docstrings
docstring = docstring.replace('\\\\', '\\\\\\\\')
# Add a class to several characters on the argspec. This way we can
# highlight them using css, in a similar way to what IPython does.
# NOTE: Before doing this, we escape common html chars so that they
# don't interfere with the rest of html present in the page
argspec = escape(context['argspec'])
for char in ['=', ',', '(', ')', '*', '**']:
argspec = argspec.replace(
char, '<span class="argspec-highlight">' + char + '</span>')
context['argspec'] = argspec
doc_file = codecs.open(rst_name, 'w', encoding='utf-8')
doc_file.write(docstring)
doc_file.close()
confoverrides = {
'html_context': context,
'extensions': ['sphinx.ext.mathjax']
}
doctreedir = osp.join(srcdir, 'doctrees')
sphinx_app = Sphinx(srcdir,
CONFDIR,
srcdir,
doctreedir,
buildername,
confoverrides,
status=None,
warning=None,
freshenv=True,
warningiserror=False,
tags=None)
try:
sphinx_app.build(None, [rst_name])
except SystemMessage:
pass
def make_docs(self, builder="html", clean=False):
# Make the html or latex documentation
self.delnb()
doc_version = self.doc_version
if builder not in ["html", "latex"]:
raise ValueError(
'Not a supported builder: Must be "html" or "latex"')
BUILDDIR = DOCREPO / builder
print(
f'{"-" * 80}\n'
f"building {builder.upper()} documentation ({doc_version.capitalize()} version : {version})"
f"\n in {BUILDDIR}"
f'\n{"-" * 80}')
# recreate dir if needed
if clean:
print("CLEAN:")
self.clean(builder)
# self.sync_notebook = True
self.regenerate_api = True
self.make_dirs()
if self.regenerate_api:
shutil.rmtree(API, ignore_errors=True)
print(f"remove {API}")
# run sphinx
print(f"\n{builder.upper()} BUILDING:")
srcdir = confdir = DOCS
outdir = f"{BUILDDIR}/{doc_version}"
doctreesdir = f"{DOCTREES}/{doc_version}"
sp = Sphinx(srcdir, confdir, outdir, doctreesdir, builder)
sp.verbosity = 1
sp.build()
print(f"\n{'-' * 130}\nBuild finished. The {builder.upper()} pages "
f"are in {outdir}.")
if doc_version == "stable":
doc_version = "latest"
# make also the latest identical
sh(f"rm -rf {BUILDDIR}/latest")
sh(f"cp -r {BUILDDIR}/stable {BUILDDIR}/latest")
if builder == "html":
self.make_redirection_page()
# a workaround to reduce the size of the image in the pdf document
# TODO: v.0.2 probably better solution exists?
if builder == "latex":
self.resize_img(GALLERY, size=580.0)
def setUp(self):
self.src_dir = mkdtemp(prefix='tmp_nbexamples_')
os.rmdir(self.src_dir)
self.out_dir = osp.join(self.src_dir, 'build', 'html')
shutil.copytree(sphinx_supp, self.src_dir)
self.app = Sphinx(
srcdir=self.src_dir, confdir=self.src_dir, outdir=self.out_dir,
doctreedir=osp.join(self.src_dir, 'build', 'doctrees'),
buildername='html')
self.app.build()
def test_html_documentation(self):
app = Sphinx(
self.source_dir,
self.config_dir,
self.output_dir,
self.doctree_dir,
buildername='html',
warningiserror=True,
)
app.build(force_all=self.all_files)
def build(test_dir, confoverrides=None, **kwargs):
os.chdir("tests/python/{0}".format(test_dir))
app = Sphinx(srcdir=".",
confdir=".",
outdir="_build/text",
doctreedir="_build/.doctrees",
buildername="text",
confoverrides=confoverrides,
**kwargs)
app.build(force_all=True)
def test_html_documentation(self):
output_dir = os.path.join(self.top, 'build', 'html')
app = Sphinx(self.source_dir,
self.source_dir,
output_dir,
self.doctree_dir,
buildername='html',
warningiserror=True)
app.build(force_all=True)
def prepareSphinx(src_dir,
out_dir,
doctree_dir,
config=None,
extra_config=None,
builder=None,
relax=False):
"""
prepare a sphinx application instance
Return a prepared Sphinx application instance [1] ready for execution.
[1]: https://github.com/sphinx-doc/sphinx/blob/master/sphinx/application.py
"""
# Enable coloring of warning and other messages. Note that this can
# cause sys.stderr to be mocked which is why we pass the new value
# explicitly on the call to Sphinx() below.
if not color_terminal():
nocolor()
conf = dict(config) if config else {}
if extra_config:
conf.update(extra_config)
conf_dir = src_dir if config is None else None
warnerr = not relax
sts = None
if 'SPHINX_STATUS' in os.environ:
sts = sys.stdout
verbosity = 0
if 'SPHINX_VERBOSITY' in os.environ:
try:
verbosity = int(os.environ['SPHINX_VERBOSITY'])
except ValueError:
pass
# default to using this extension's builder
if not builder:
builder = 'confluence'
with docutils_namespace():
app = Sphinx(
src_dir, # output for document sources
conf_dir, # configuration directory
out_dir, # output for generated documents
doctree_dir, # output for doctree files
builder, # builder to execute
confoverrides=conf, # load provided configuration (volatile)
status=sts, # status output
warning=sys.stderr, # warnings output
warningiserror=warnerr, # treat warnings as errors
verbosity=verbosity) # verbosity
yield app
def fix_build_env(builder, conf):
"""
Given a builder name and the conf object, this function fixes the build
artifacts for the current build to prevent a full rebuild. Currently
re-pickles the environment and dumps the ``.buildinfo`` file in the build
directory with the correct hashes.
"""
fn = os.path.join(conf.paths.projectroot, conf.paths.branch_output,
builder, '.buildinfo')
logger.info('updating cache for: ' + builder)
if not os.path.isfile(fn):
return
doctree_dir = os.path.join(conf.paths.projectroot,
conf.paths.branch_output, "doctrees-" + builder)
sphinx_app = Sphinx(srcdir=os.path.join(conf.paths.projectroot,
conf.paths.branch_output,
"source"),
confdir=conf.paths.projectroot,
outdir=os.path.join(conf.paths.projectroot,
conf.paths.branch_output, builder),
doctreedir=doctree_dir,
buildername=builder,
status=tempfile.NamedTemporaryFile(),
warning=tempfile.NamedTemporaryFile())
sphinx_app.env.topickle(os.path.join(doctree_dir, ENV_PICKLE_FILENAME))
with open(fn, 'r') as f:
lns = f.readlines()
tags_hash_ln = None
for ln in lns:
if ln.startswith('tags'):
tags_hash_ln = ln
break
if tags_hash_ln is None:
tags_hash_ln = 'tags: ' + get_stable_hash(sorted(sphinx_app.tags))
with open(fn, 'w') as f:
config_dict = dict(
(name, sphinx_app.config[name])
for (name, desc) in sphinx_app.config.values.items()
if desc[1] == 'html')
f.write('# Sphinx build info version 1')
f.write('\n\n') # current format requires an extra line here.
f.write('config: ' + get_stable_hash(config_dict))
f.write('\n')
f.write(tags_hash_ln)
f.write('\n')
def run(self):
try:
from sphinx.application import Sphinx
from docutils.utils import SystemMessage
except ImportError:
raise SystemExit(
'This command requires Sphinx to be installed.') from None
fix_docutils()
dest_dir = os.path.join(basedir, 'doc')
src_dir = os.path.join(basedir, 'rst')
confoverrides = {}
confoverrides['version'] = s3ql.VERSION
confoverrides['release'] = s3ql.RELEASE
for builder in ('html', 'latex', 'man'):
print('Running %s builder...' % builder)
self.mkpath(os.path.join(dest_dir, builder))
app = Sphinx(srcdir=src_dir,
confdir=src_dir,
outdir=os.path.join(dest_dir, builder),
doctreedir=os.path.join(dest_dir, 'doctrees'),
buildername=builder,
confoverrides=confoverrides,
freshenv=self.fresh_env)
self.fresh_env = False
self.all_files = False
try:
if self.all_files:
app.builder.build_all()
else:
app.builder.build_update()
except SystemMessage as err:
print('reST markup error:',
err.args[0].encode('ascii', 'backslashreplace'),
file=sys.stderr)
# These shouldn't be installed by default
for name in ('expire_backups.1', 'pcp.1'):
os.rename(os.path.join(dest_dir, 'man', name),
os.path.join(basedir, 'contrib', name))
print('Running pdflatex...')
for _ in range(3):
with open('/dev/null', 'wb') as null:
subprocess.check_call(
['pdflatex', '-interaction', 'batchmode', 'manual.tex'],
cwd=os.path.join(dest_dir, 'latex'),
stdout=null)
os.rename(os.path.join(dest_dir, 'latex', 'manual.pdf'),
os.path.join(dest_dir, 'manual.pdf'))
def run(self):
# type: () -> None
if not color_terminal():
nocolor()
if not self.verbose: # type: ignore
status_stream = StringIO()
else:
status_stream = sys.stdout # type: ignore
confoverrides = {} # type: Dict[str, Any]
if self.project:
confoverrides['project'] = self.project
if self.version:
confoverrides['version'] = self.version
if self.release:
confoverrides['release'] = self.release
if self.today:
confoverrides['today'] = self.today
if self.copyright:
confoverrides['copyright'] = self.copyright
if self.nitpicky:
confoverrides['nitpicky'] = self.nitpicky
for builder, builder_target_dir in self.builder_target_dirs:
app = None
try:
confdir = self.config_dir or self.source_dir
with patch_docutils(confdir), docutils_namespace():
app = Sphinx(self.source_dir,
self.config_dir,
builder_target_dir,
self.doctree_dir,
builder,
confoverrides,
status_stream,
freshenv=self.fresh_env,
warningiserror=self.warning_is_error,
verbosity=self.verbosity,
keep_going=self.keep_going)
app.build(force_all=self.all_files)
if app.statuscode:
raise DistutilsExecError('caused by %s builder.' %
app.builder.name)
except Exception as exc:
handle_exception(app, self, exc, sys.stderr)
if not self.pdb:
raise SystemExit(1) from exc
if not self.link_index:
continue
src = app.config.root_doc + app.builder.out_suffix # type: ignore
dst = app.builder.get_outfilename('index') # type: ignore
os.symlink(src, dst)
def test_html_documentation(self):
from sphinx.application import Sphinx
app = Sphinx(
self.source_dir,
self.config_dir,
self.output_dir,
self.doctree_dir,
buildername='html',
warningiserror=False,
)
app.build(force_all=self.all_files)
def setUpClass(cls):
super(TestDocStrings, cls).setUpClass()
root = os.path.dirname(sphinxcontrib_django.__file__)
confdir = os.path.join(os.path.dirname(__file__), 'testdocs')
cls.app = Sphinx(srcdir=root,
confdir=confdir,
outdir=os.path.join(confdir, '_build'),
doctreedir=root,
buildername='html',
freshenv=True)
sphinxcontrib_django.setup(cls.app)
def test_text_documentation(self):
# The same, but with different buildername
app = Sphinx(
self.source_dir,
self.config_dir,
self.output_dir,
self.doctree_dir,
buildername='text',
warningiserror=False,
)
app.build(force_all=self.all_files)
def test_sphinx_build(buildername: str, tmp_path: pathlib.Path) -> None:
"""Test :meth:`sphinx.application.Sphinx.build`."""
doctreedir = tmp_path / "doctrees"
with docutils_namespace():
app = Sphinx("docs",
"docs",
tmp_path,
doctreedir,
buildername=buildername,
warningiserror=True)
app.build(force_all=True)
def make_doc(self):
global _sphinx_app
dest = self._output_folder
doctree_dir = os.path.join(self._build_folder, '.doctrees')
self.build_config_file()
# We must cache sphinx instance otherwise extensions are loaded
# multiple times and duplicated references errors are raised.
if _sphinx_app is None:
_sphinx_app = Sphinx(
self._build_folder, self._build_folder, dest, doctree_dir, self.build_fmt)
_sphinx_app.build(force_all=True)
def setUp(self):
if self.build_path is not None:
self.app = Sphinx(
srcdir=self.build_path,
confdir=self.build_path,
outdir=os.path.join(self.build_path, '_build', 'text'),
doctreedir=os.path.join(self.build_path, '_build', '.doctrees'),
buildername='html',
verbosity=1,
)
self.app.build(force_all=True)
def test_html_documentation(self):
""" Tests whether the HTML documentation can be build properly. """
app = Sphinx(
self.source_dir,
self.config_dir,
self.output_dir,
self.doctree_dir,
buildername='html',
warningiserror=True,
)
app.build(force_all=self.all_files)
def load_sphinx(self, project_path):
issues = []
try:
from sphinx.application import Sphinx
except ImportError:
Sphinx = None # noqa: N806
if Sphinx:
register_directive = directives.register_directive
register_local_role = roles.register_local_role
def hijacked_directive(name, *args, **kwargs):
# pylint: disable=unused-argument
register_directive(name, DummyDirective)
def hijacked_role(name, *args, **kwargs):
# pylint: disable=unused-argument
register_local_role(name, dummy_role)
directives.register_directive = hijacked_directive
roles.register_local_role = hijacked_role
tmp_dir_in = mkdtemp()
tmp_dir_out = mkdtemp()
try:
with open(os.path.join(tmp_dir_in, 'conf.py'), 'w') as conf:
conf.write('extensions = %r' %
(self.config['options']['sphinx-extensions'], ))
Sphinx(
tmp_dir_in,
tmp_dir_in,
tmp_dir_out,
tmp_dir_out,
None,
status=None,
)
finally:
rmtree(tmp_dir_in)
rmtree(tmp_dir_out)
directives.register_directive = register_directive
roles.register_local_role = register_local_role
else:
issues.append(
ToolIssue(
'rstlint: Sphinx not found in the environment -- cannot load'
' extensions',
project_path,
))
return issues
def test_linkcheck(self):
src_dir = config_dir = self.path_to_docs
output_dir = os.path.sep.join([src_dir, "_build", "linkcheck"])
doctree_dir = os.path.sep.join([src_dir, "_build", "doctrees"])
app = Sphinx(src_dir,
config_dir,
output_dir,
doctree_dir,
buildername="linkcheck",
warningiserror=False,
parallel=n_cpu)
app.build(force_all=True)
def test_autodoc(tmpdir):
root = str(tmpdir)
tmpdir.join('conf.py').write("extensions = ['sphinx.ext.autodoc']\n")
tmpdir.join('contents.rst').write(
".. automodule:: reg.tests.fixtures.module\n"
" :members:\n")
# status=None makes Sphinx completely quiet, in case you run
# py.test with the -s switch. For debugging you might want to
# remove it.
app = Sphinx(root, root, root, root, 'text', status=None)
app.build()
assert tmpdir.join('contents.txt').read() == """\
def run(self):
if not color_terminal():
nocolor()
if not self.verbose:
status_stream = StringIO()
else:
status_stream = sys.stdout
confoverrides = {}
if self.project:
confoverrides['project'] = self.project
if self.version:
confoverrides['version'] = self.version
if self.release:
confoverrides['release'] = self.release
if self.today:
confoverrides['today'] = self.today
if self.copyright:
confoverrides['copyright'] = self.copyright
app = Sphinx(self.source_dir,
self.config_dir,
self.builder_target_dir,
self.doctree_dir,
self.builder,
confoverrides,
status_stream,
freshenv=self.fresh_env)
try:
app.build(force_all=self.all_files)
if app.statuscode:
raise DistutilsExecError('caused by %s builder.' %
app.builder.name)
except Exception as err:
if self.pdb:
import pdb
print(darkred(
'Exception occurred while building, starting debugger:'),
file=sys.stderr)
traceback.print_exc()
pdb.post_mortem(sys.exc_info()[2])
else:
from docutils.utils import SystemMessage
if isinstance(err, SystemMessage):
print(darkred('reST markup error:'), file=sys.stderr)
print(err.args[0].encode('ascii', 'backslashreplace'),
file=sys.stderr)
else:
raise
if self.link_index:
src = app.config.master_doc + app.builder.out_suffix
dst = app.builder.get_outfilename('index')
os.symlink(src, dst)