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? """ 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