def main(tag: str | None):
GITHUB_PAGES = ROOT / "steam-py.github.io"
GITHUB_PAGES_DOCS = GITHUB_PAGES / "docs"
target_dir = GITHUB_PAGES_DOCS / (tag or "latest")
build_main([
str(DOCS_STEAM_PY),
str(target_dir),
*(str(p) for p in DOCS_STEAM_PY.rglob("*.rst|*.md")),
"-b",
"dirhtml",
"-a",
"-E",
"-T",
])
if tag:
try:
(GITHUB_PAGES_DOCS / "stable").symlink_to(target_dir,
target_is_directory=True)
except FileExistsError:
pass
index = json.loads((GITHUB_PAGES / "index.json").read_text())
if tag:
index["docs"]["tags"].append(tag)
(GITHUB_PAGES / "index.json").write_text(json.dumps(index, indent=2))
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'):
build_main(argv=[
'-b', builder_name, rst_directory,
os.path.join(build_directory, builder_name)
])
def makedocs(c):
from sphinx.cmd.build import build_main
build_main(
["-b", "dirhtml",
get_docs_source_path(),
get_docs_build_path()])
def run(self):
build_cmd = self.reinitialize_command('build_ext')
build_cmd.inplace = 1
self.run_command('build_ext')
build_main(['-b', 'html', 'doc/source', 'build/sphinx/html'])
# Bundle documentation inside of drizzlepac
if os.path.exists(docs_compiled_src):
if os.path.exists(docs_compiled_dest):
shutil.rmtree(docs_compiled_dest)
shutil.copytree(docs_compiled_src, docs_compiled_dest)
def run(self):
build_cmd = self.reinitialize_command('build_ext')
build_cmd.inplace = 1
self.run_command('build_ext')
build_main(['-b', 'html', 'doc/source', 'build/sphinx/html'])
# Bundle documentation inside of drizzlepac
if os.path.exists(docs_compiled_src):
if os.path.exists(docs_compiled_dest):
shutil.rmtree(docs_compiled_dest)
shutil.copytree(docs_compiled_src, docs_compiled_dest)
def makedocs(
c, doctype="html", docs_build_path=get_docs_build_path(),
):
from sphinx.cmd.build import build_main
from m2r import convert
with open("./README.md", "r") as _file:
markdown_contents = _file.read()
with open(os.path.join(get_docs_source_path(), "readme.rst"), "w+") as _file:
_file.write(convert(markdown_contents))
build_main(["-b", doctype, get_docs_source_path(), docs_build_path])
def test_build_docs():
docsdir = os.path.abspath(os.path.dirname(__file__)) + "/../../docs"
exitCode = build.build_main([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 run(self):
if not _HAVE_SPHINX:
raise RuntimeError(
"You must install Sphinx to build or test the documentation.")
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]
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))
def test_build_docs():
docsdir = os.path.abspath(os.path.dirname(__file__)) + "/../../docs"
exitCode = build.build_main([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 run(self):
build_cmd = self.reinitialize_command('build_ext')
build_cmd.inplace = 1
self.run_command('build_ext')
retcode = build_main(['-W', '--keep-going', '-b', 'html', './docs', './docs/_build/html'])
if retcode != 0:
sys.exit(retcode)
def run(self):
build_cmd = self.reinitialize_command('build_ext')
build_cmd.inplace = 1
self.run_command('build_ext')
retcode = build_main(['-W', '--keep-going', '-b', 'html', './docs', './docs/_build/html'])
if retcode != 0:
sys.exit(retcode)
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.
old_init = application.Config.__init__
def init_override(self, *args):
old_init(self, *args)
self.extensions.append('sphinxcontrib.versioning.sphinx_')
application.Config.__init__ = init_override
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
# Build pdf if required
if config.pdf_file:
args = list(argv)
args.insert(0, "latexpdf") # Builder type
args.insert(0, "ignore") # Will be ignored
result = make_main(args)
# Copy to _static dir of src
latexDir = argv[1] + "/latex/"
copyfile(latexDir + config.pdf_file,
argv[1] + "/_static/" + config.pdf_file)
rmtree(latexDir)
if result != 0:
raise SphinxError
def build_contents(request):
marker = request.node.get_closest_marker("builder")
if marker is None:
return None
else:
builder = marker.args[0]
example_dir = path(
__file__).parent.abspath() / "examples" / f"test_{builder}"
argv = [
"-b",
builder,
example_dir,
example_dir / "_build",
]
build_main(argv)
with open(example_dir / "_build" / "index.html") as f:
contents = f.read()
return BeautifulSoup(contents, "html.parser")
def test_conf(tmpdir):
# Just make sure the docs build with the default sphinx-astropy configuration
generate_files(tmpdir)
src_dir = tmpdir.strpath
html_dir = tmpdir.mkdir('html').strpath
status = build_main(argv=['-W', '-b', 'html', src_dir, html_dir])
assert status == 0
def run_generic_build(self, builder: str, doctreedir: str = None) -> int:
# compatibility with old Makefile
papersize = os.getenv('PAPER', '')
opts = self.opts
if papersize in ('a4', 'letter'):
opts.extend(['-D', 'latex_elements.papersize=' + papersize + 'paper'])
if doctreedir is None:
doctreedir = self.builddir_join('doctrees')
args = ['-b', builder,
'-d', doctreedir,
self.srcdir,
self.builddir_join(builder)]
return build_main(args + opts)
def run_generic_build(self, builder, doctreedir=None):
# type: (str, str) -> int
# compatibility with old Makefile
papersize = os.getenv('PAPER', '')
opts = self.opts
if papersize in ('a4', 'letter'):
opts.extend(['-D', 'latex_elements.papersize=' + papersize + 'paper'])
if doctreedir is None:
doctreedir = self.builddir_join('doctrees')
args = ['-b', builder,
'-d', doctreedir,
self.srcdir,
self.builddir_join(builder)]
return build_main(args + opts)
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?
"""
# Was unable to get this inject to work in python 3.6 sphinx 2+
# replaced with importlib jazz before build_main
# 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')
]
if config.verbose > 1:
argv += ('-v', ) * (config.verbose - 1)
if config.no_colors:
argv += ('-N', )
if config.overflow:
argv += config.overflow
# import extensions variable from conf.py from checked out version of code.
# if this extension isn't present override extensions in call to sphinx-build
# to include it along with any other extension present in conf
spec = importlib.util.spec_from_file_location('conf',
Path(argv[0], 'conf.py'))
_conf = importlib.util.module_from_spec(spec)
spec.loader.exec_module(_conf)
extensions = _conf.extensions
if "sphinxcontrib.versioning" not in extensions:
extensions.append("sphinxcontrib.versioning")
argv += ("-D", f"extensions={','.join(extensions)}")
# kick of sphinx-build
result = build_main(argv)
if result != 0:
raise SphinxError
def test_intersphinx_toggle(tmpdir, capsys):
# Test the sphinx_astropy.ext.intersphinx_toggle extension
generate_files(tmpdir)
src_dir = tmpdir.strpath
html_dir = tmpdir.mkdir('html').strpath
status = build_main(argv=[
'-W', '-b', 'html', src_dir, html_dir, '-D', 'disable_intersphinx=1'
])
assert status == 0
captured = capsys.readouterr()
assert 'disabling intersphinx' in captured.out
assert 'loading intersphinx' not in captured.out
def test_build_ok(self):
args = [
"-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 build(ctx, source, nowarn):
"""
Build documentation from ``source``, placing built files in
``target``.
"""
_logger.info('building documentation')
outdir = ctx.obj['outdir']
if sphinx_version_at_least_1_7:
# args have to be specified this way for 1.7+, otherwise one gets
# "Builder name html not registered or available through entry point"
# See https://github.com/sphinx-doc/sphinx/issues/4623
args = ['-b', 'html']
else:
args = ['-b html']
if not nowarn:
args.append('-W')
if build_main(args + [source, outdir]):
raise click.ClickException("Error building sphinx doc")
def run_sphinx_in_tmpdir(tmpdir, additional_conf={}, expect_error=False):
start_dir = os.path.abspath('.')
conf = deepcopy(DEFAULT_CONF)
conf.update(additional_conf)
write_conf(tmpdir.join('conf.py').strpath, conf)
argv = ['-W', '-b', 'html', '.', '_build/html']
try:
os.chdir(tmpdir.strpath)
status = build_main(argv=argv)
finally:
os.chdir(start_dir)
if expect_error:
assert status != 0
else:
assert status == 0
async def execute_task(self, **kwargs):
options = self.collector.configuration["documentation"]
srcdir = options.src
outdir = os.path.join(options.out, "result")
confdir = pkg_resources.resource_filename("photons_docs", "config")
doctreedir = os.path.join(options.out, "doctree")
if self.is_fresh and os.path.exists(options.out):
shutil.rmtree(options.out)
for d in (outdir, doctreedir):
if not os.path.exists(d):
os.makedirs(d)
argv = [srcdir, outdir, "-c", confdir, "-d", doctreedir]
if self.is_fresh:
argv.append("-E")
argv.extend(shlex.split(self.photons_app.extra))
sys.exit(build_main(argv))
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):
build_cmd = self.reinitialize_command('build_ext')
build_cmd.inplace = 1
self.run_command('build_ext')
build_main(['-b', 'html', './docs', './docs/_build/html'])
def run_sphinx_build(argv):
build_main(argv=argv[1:])
import os
import sys
from sphinx.cmd.build import build_main
# Set some environment variables for consistency.
os.putenv("LANG", "en_US.UTF-8")
os.putenv("LC_ALL", "en_US.UTF-8")
os.putenv("TZ", "UTC")
# Launch Sphinx
sys.exit(build_main(sys.argv[1:]))
def build(c):
""" 构建 html 静态文件
"""
from sphinx.cmd.build import build_main
build_main(['source', 'build', '-b', 'html'])
def run(self):
# *********************************************************************
# This code block is to be able to build the documentation if
# python-openzwave is installed into the python that is running the
# setup program. What happens is for some reason both libopenzwave.pyd
# files try to load and this causes them to bump heads and the ugly
# things start happening. so we want to make sure that we load the one
# that was just compiled and also remove any python-openzwave
# references in sys.path. this ensures the proper one gets loaded
build_ext = self.distribution.get_command_obj('build_ext')
build_ext.ensure_finalized()
extension = self.distribution.ext_modules[0]
ext_path = build_ext.get_ext_fullpath(extension.name)
mod = imp.load_dynamic('libopenzwave', ext_path)
sys.modules['libopenzwave'] = mod
for path in sys.path[:]:
if 'python_openzwave' in path:
sys.path.remove(path)
sys.path.insert(0, os.path.abspath(self.build_lib))
# *********************************************************************
if self.sphinx_conf is not None:
self.sphinx_conf.additional_lines = (
'import sys\n'
'sys.path.insert(0, r\'{path}\')\n\n'.format(
path=os.path.abspath(self.build_lib))
) + self.sphinx_conf.additional_lines
with open(self.conf_path, 'w') as f:
f.write(str(self.sphinx_conf))
try:
if self.output_path is None:
self.output_path = os.path.join(self.build_lib, 'docs')
self.run_command('egg')
sys.path.insert(0, os.path.abspath(self.build_lib))
from sphinx.cmd.build import build_main
options = (self.builder_name + self.html_values +
self.config_overrides + self.full_traceback +
self.all_output + self.no_saved_environment + self.tag +
self.doctree_path + self.num_processes +
self.config_path + self.no_config + self.keep_going +
self.warnings_are_errors + self.error_log +
self.only_errors + self.quiet + self.no_color +
self.nit_picky + self.verbose +
[self.source_path, self.output_path])
build_main(options)
except:
traceback.print_exc()
sys.exit(1)
if self.config_backup is not None:
config_file = self.config_backup.replace('.backup', '')
os.remove(config_file)
os.rename(self.config_backup, config_file)
import shutil
from pathlib import Path
from sphinx.cmd import build
if __name__ == '__main__':
source_root = Path(__file__).parent
build_root = source_root.parent / "build"
try:
shutil.rmtree(build_root)
except FileNotFoundError:
pass
build.build_main([str(source_root), str(build_root)])
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))
def run(self):
build_cmd = self.reinitialize_command('build_ext')
build_cmd.inplace = 1
self.run_command('build_ext')
build_main(['-b', 'html', './docs', './docs/_build/html'])
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))
def main(argv=None):
if not argv:
argv = sys.argv[1:]
parser = argparse.ArgumentParser()
parser.add_argument("sourcedir", help="path to documentation source files")
parser.add_argument("outputdir", help="path to output directory")
parser.add_argument(
"filenames",
nargs="*",
help="a list of specific files to rebuild. Ignored if -a is specified",
)
parser.add_argument(
"-c",
metavar="PATH",
dest="confdir",
help=("path where configuration file (conf.py) is located "
"(default: same as SOURCEDIR)"),
)
parser.add_argument(
"-C",
action="store_true",
dest="noconfig",
help="use no config file at all, only -D options",
)
parser.add_argument(
"-D",
metavar="setting=value",
action="append",
dest="define",
default=[],
help="override a setting in configuration file",
)
parser.add_argument(
"--dump-metadata",
action="store_true",
help="dump generated metadata and exit",
)
args, argv = parser.parse_known_args(argv)
if args.noconfig:
return 1
# Conf-overrides
confoverrides = {}
for d in args.define:
key, _, value = d.partition("=")
confoverrides[key] = value
# Parse config
config = sphinx_config.Config.read(
os.path.abspath(args.confdir if args.confdir else args.sourcedir),
confoverrides,
)
config.add("smv_tag_whitelist", sphinx.DEFAULT_TAG_WHITELIST, "html", str)
config.add("smv_branch_whitelist", sphinx.DEFAULT_TAG_WHITELIST, "html",
str)
config.add("smv_remote_whitelist", sphinx.DEFAULT_REMOTE_WHITELIST, "html",
str)
config.add("smv_released_pattern", sphinx.DEFAULT_RELEASED_PATTERN, "html",
str)
config.add("smv_outputdir_format", sphinx.DEFAULT_OUTPUTDIR_FORMAT, "html",
str)
config.add("smv_prefer_remote_refs", False, "html", bool)
config.pre_init_values()
config.init_values()
# Get relative paths to root of git repository
gitroot = pathlib.Path(".").resolve()
sourcedir = os.path.relpath(args.sourcedir, str(gitroot))
if args.confdir:
confdir = os.path.relpath(args.confdir, str(gitroot))
else:
confdir = sourcedir
conffile = os.path.join(confdir, "conf.py")
# Get git references
gitrefs = git.get_refs(
str(gitroot),
config.smv_tag_whitelist,
config.smv_branch_whitelist,
config.smv_remote_whitelist,
files=(sourcedir, conffile),
)
# Order git refs
if config.smv_prefer_remote_refs:
gitrefs = sorted(gitrefs, key=lambda x: (not x.is_remote, *x))
else:
gitrefs = sorted(gitrefs, key=lambda x: (x.is_remote, *x))
logger = logging.getLogger(__name__)
with tempfile.TemporaryDirectory() as tmp:
# Generate Metadata
metadata = {}
outputdirs = set()
for gitref in gitrefs:
# Clone Git repo
repopath = os.path.join(tmp, gitref.commit)
try:
git.copy_tree(gitroot.as_uri(), repopath, gitref)
except (OSError, subprocess.CalledProcessError):
logger.error(
"Failed to copy git tree for %s to %s",
gitref.refname,
repopath,
)
continue
# Find config
confpath = os.path.join(repopath, confdir)
try:
current_config = sphinx_config.Config.read(
confpath,
confoverrides,
)
except (OSError, sphinx_config.ConfigError):
logger.error(
"Failed load config for %s from %s",
gitref.refname,
confpath,
)
continue
current_config.pre_init_values()
current_config.init_values()
# Ensure that there are not duplicate output dirs
outputdir = config.smv_outputdir_format.format(
ref=gitref,
config=current_config,
)
if outputdir in outputdirs:
logger.warning(
"outputdir '%s' for %s conflicts with other versions",
outputdir,
gitref.refname,
)
continue
outputdirs.add(outputdir)
# Get List of files
source_suffixes = current_config.source_suffix
if isinstance(source_suffixes, str):
source_suffixes = [current_config.source_suffix]
current_sourcedir = os.path.join(repopath, sourcedir)
project = sphinx_project.Project(current_sourcedir,
source_suffixes)
metadata[gitref.name] = {
"name":
gitref.name,
"version":
current_config.version,
"release":
current_config.release,
"is_released":
bool(re.match(config.smv_released_pattern, gitref.refname)),
"source":
gitref.source,
"creatordate":
gitref.creatordate.strftime(sphinx.DATE_FMT),
"sourcedir":
current_sourcedir,
"outputdir":
os.path.join(os.path.abspath(args.outputdir), outputdir),
"confdir":
os.path.abspath(confdir),
"docnames":
list(project.discover()),
}
if args.dump_metadata:
print(json.dumps(metadata, indent=2))
return 0
if not metadata:
logger.error("No matching refs found!")
return 2
# Write Metadata
metadata_path = os.path.abspath(os.path.join(tmp, "versions.json"))
with open(metadata_path, mode="w") as fp:
json.dump(metadata, fp, indent=2)
# Run Sphinx
argv.extend(["-D", "smv_metadata_path={}".format(metadata_path)])
for version_name, data in metadata.items():
os.makedirs(data["outputdir"], exist_ok=True)
defines = itertools.chain(
*(("-D", string.Template(d).safe_substitute(data))
for d in args.define))
current_argv = argv.copy()
current_argv.extend([
*defines,
"-D",
"smv_current_version={}".format(version_name),
"-c",
data["confdir"],
data["sourcedir"],
data["outputdir"],
*args.filenames,
])
logger.debug("Running sphinx-build with args: %r", current_argv)
status = sphinx_build.build_main(current_argv)
if status not in (0, None):
return 3
return 0
def test_build_docs(self):
build_main(argv=['-b', 'html', self.docs_path, self.html_path])
def main():
sys.exit(build_main(['doc/source', 'doc/build', '-a']))
def run_sphinx_build(argv):
build_main(argv=argv[1:])
def build(self, expected_return=0):
print("")
sys.argv = [
"-q", "-d", paths.doctree, "-b", "html", paths.root, paths.html
]
build_main(sys.argv)