def read_config(source, current_name):
"""Read the Sphinx config for one version.
:raise HandledError: If sphinx-build fails. Will be logged before raising.
:param str source: Source directory to pass to sphinx-build.
:param str current_name: The ref name of the current version being built.
:return: Specific Sphinx config values.
:rtype: dict
"""
log = logging.getLogger(__name__)
queue = multiprocessing.Queue()
config = Config.from_context()
with TempDir() as temp_dir:
argv = ('sphinx-build', source, temp_dir)
log.debug('Running sphinx-build for config values with args: %s',
str(argv))
child = multiprocessing.Process(target=_read_config,
args=(argv, config, current_name,
queue))
child.start()
child.join() # Block.
if child.exitcode != 0:
log.error(
'sphinx-build failed for branch/tag while reading config: %s',
current_name)
raise HandledError
config = queue.get()
return config
def build_all(exported_root, destination, versions):
"""Build all versions.
:param str exported_root: Tempdir path with exported commits as subdirectories.
:param str destination: Destination directory to copy/overwrite built docs to. Does not delete old files.
:param sphinxcontrib.versioning.versions.Versions versions: Versions class instance.
"""
log = logging.getLogger(__name__)
while True:
# Build root.
remote = versions[Config.from_context().root_ref]
log.info('Building root: %s', remote['name'])
source = os.path.dirname(
os.path.join(exported_root, remote['sha'],
remote['conf_rel_path']))
build(source, destination, versions, remote['name'], True)
# Build all refs.
for remote in list(versions.remotes):
log.info('Building ref: %s', remote['name'])
source = os.path.dirname(
os.path.join(exported_root, remote['sha'],
remote['conf_rel_path']))
target = os.path.join(destination, remote['root_dir'])
try:
build(source, target, versions, remote['name'], False)
except HandledError:
log.warning(
'Skipping. Will not be building %s. Rebuilding everything.',
remote['name'])
versions.remotes.pop(versions.remotes.index(remote))
break # Break out of for loop.
else:
break # Break out of while loop if for loop didn't execute break statement above.
def build(source, target, versions, current_name, is_root):
"""Build Sphinx docs for one version. Includes Versions class instance with names/urls in the HTML context.
:raise HandledError: If sphinx-build fails. Will be logged before raising.
:param str source: Source directory to pass to sphinx-build.
:param str target: Destination directory to write documentation to (passed to sphinx-build).
: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?
"""
log = logging.getLogger(__name__)
argv = ('sphinx-build', source, target)
config = Config.from_context()
log.debug('Running sphinx-build for %s with args: %s', current_name,
str(argv))
child = multiprocessing.Process(target=_build,
args=(argv, config, versions, current_name,
is_root))
child.start()
child.join() # Block.
if child.exitcode != 0:
log.error('sphinx-build failed for branch/tag: %s', current_name)
raise HandledError
def build_all(exported_root, destination, versions):
"""Build all versions.
:param str exported_root: Tempdir path with exported commits as subdirectories.
:param str destination: Destination directory to copy/overwrite built docs to. Does not delete old files.
:param sphinxcontrib.versioning.versions.Versions versions: Versions class instance.
"""
log = logging.getLogger(__name__)
while True:
# Build root.
remote = versions[Config.from_context().root_ref]
log.info('Building root: %s', remote['name'])
source = os.path.dirname(os.path.join(exported_root, remote['sha'], remote['conf_rel_path']))
build(source, destination, versions, remote['name'], True)
# Build all refs.
for remote in list(versions.remotes):
log.info('Building ref: %s', remote['name'])
source = os.path.dirname(os.path.join(exported_root, remote['sha'], remote['conf_rel_path']))
target = os.path.join(destination, remote['root_dir'])
try:
build(source, target, versions, remote['name'], False)
except HandledError:
log.warning('Skipping. Will not be building %s. Rebuilding everything.', remote['name'])
versions.remotes.pop(versions.remotes.index(remote))
break # Break out of for loop.
else:
break # Break out of while loop if for loop didn't execute break statement above.
def read_config(source, current_name):
"""Read the Sphinx config for one version.
:raise HandledError: If sphinx-build fails. Will be logged before raising.
:param str source: Source directory to pass to sphinx-build.
:param str current_name: The ref name of the current version being built.
:return: Specific Sphinx config values.
:rtype: dict
"""
log = logging.getLogger(__name__)
queue = multiprocessing.Queue()
config = Config.from_context()
with TempDir() as temp_dir:
argv = ('sphinx-build', source, temp_dir)
log.debug('Running sphinx-build for config values with args: %s', str(argv))
child = multiprocessing.Process(target=_read_config, args=(argv, config, current_name, queue))
child.start()
child.join() # Block.
if child.exitcode != 0:
log.error('sphinx-build failed for branch/tag while reading config: %s', current_name)
raise HandledError
config = queue.get()
return config
def pre_build(local_root, versions):
"""Build docs for all versions to determine root directory and master_doc names.
Need to build docs to (a) avoid filename collision with files from root_ref and branch/tag names and (b) determine
master_doc config values for all versions (in case master_doc changes from e.g. contents.rst to index.rst between
versions).
Exports all commits into a temporary directory and returns the path to avoid re-exporting during the final build.
:param str local_root: Local path to git root directory.
:param sphinxcontrib.versioning.versions.Versions versions: Versions class instance.
:return: Tempdir path with exported commits as subdirectories.
:rtype: str
"""
log = logging.getLogger(__name__)
exported_root = TempDir(True).name
# Extract all.
for sha in {r['sha'] for r in versions.remotes}:
target = os.path.join(exported_root, sha)
log.debug('Exporting %s to temporary directory.', sha)
export(local_root, sha, target)
# Build root.
remote = versions[Config.from_context().root_ref]
with TempDir() as temp_dir:
log.debug('Building root (before setting root_dirs) in temporary directory: %s', temp_dir)
source = os.path.dirname(os.path.join(exported_root, remote['sha'], remote['conf_rel_path']))
build(source, temp_dir, versions, remote['name'], True)
existing = os.listdir(temp_dir)
# Define root_dir for all versions to avoid file name collisions.
for remote in versions.remotes:
root_dir = RE_INVALID_FILENAME.sub('_', remote['name'])
while root_dir in existing:
root_dir += '_'
remote['root_dir'] = root_dir
log.debug('%s root directory is %s', remote['name'], root_dir)
existing.append(root_dir)
# Get found_docs and master_doc values for all versions.
for remote in list(versions.remotes):
log.debug('Partially running sphinx-build to read configuration for: %s', remote['name'])
source = os.path.dirname(os.path.join(exported_root, remote['sha'], remote['conf_rel_path']))
try:
config = read_config(source, remote['name'])
except HandledError:
log.warning('Skipping. Will not be building: %s', remote['name'])
versions.remotes.pop(versions.remotes.index(remote))
continue
remote['found_docs'] = config['found_docs']
remote['master_doc'] = config['master_doc']
return exported_root
def build(source, target, versions, current_name, is_root):
"""Build Sphinx docs for one version. Includes Versions class instance with names/urls in the HTML context.
:raise HandledError: If sphinx-build fails. Will be logged before raising.
:param str source: Source directory to pass to sphinx-build.
:param str target: Destination directory to write documentation to (passed to sphinx-build).
: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?
"""
log = logging.getLogger(__name__)
argv = ('sphinx-build', source, target)
config = Config.from_context()
log.debug('Running sphinx-build for %s with args: %s', current_name, str(argv))
child = multiprocessing.Process(target=_build, args=(argv, config, versions, current_name, is_root))
child.start()
child.join() # Block.
if child.exitcode != 0:
log.error('sphinx-build failed for branch/tag: %s', current_name)
raise HandledError
def build(source, target, versions, current_name, is_root):
"""Build Sphinx docs for one version. Includes Versions class instance with names/urls in the HTML context.
:raise HandledError: If sphinx-build fails. Will be logged before raising.
:param str source: Source directory to pass to sphinx-build.
:param str target: Destination directory to write documentation to (passed to sphinx-build).
: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?
"""
import subprocess
log = logging.getLogger(__name__)
argv = ('sphinx-build', source, target)
config = Config.from_context()
if config.run_setup_py:
with ChangeDir(source):
current_version_root = subprocess.check_output(
"git rev-parse --show-toplevel".split(" ")).decode(
"utf-8").split("\n")[0]
with ChangeDir(current_version_root):
subprocess.check_call(["python", "setup.py", "install"])
log.debug('Running sphinx-build for %s with args: %s', current_name,
str(argv))
child = multiprocessing.Process(target=_build,
args=(argv, config, versions, current_name,
is_root))
child.start()
child.join() # Block.
if child.exitcode != 0:
log.error('sphinx-build failed for branch/tag: %s', current_name)
raise HandledError
