def __init__(self,
confoverrides=None,
srcdir=None,
raise_on_warning=False):
self.extensions = {}
self.registry = SphinxComponentRegistry()
try:
self.html_themes = {}
except AttributeError:
# changed to property in sphinx 4.1
pass
self.events = EventManager(self)
# logging
self.verbosity = 0
self._warncount = 0
self.warningiserror = raise_on_warning
self._status = StringIO()
self._warning = StringIO()
logging.setup(self, self._status, self._warning)
self.tags = Tags([])
self.config = Config({}, confoverrides or {})
self.config.pre_init_values()
self._init_i18n()
for extension in builtin_extensions:
self.registry.load_extension(self, extension)
# fresh env
self.doctreedir = ""
self.srcdir = srcdir
self.confdir = None
self.outdir = ""
self.project = Project(srcdir=srcdir,
source_suffix={".md": "markdown"})
self.project.docnames = {"mock_docname"}
self.env = BuildEnvironment()
self.env.setup(self)
self.env.temp_data["docname"] = "mock_docname"
# Ignore type checkers because we disrespect superclass typing here
self.builder = None # type: ignore[assignment]
if not with_builder:
return
# this code is only required for more complex parsing with extensions
for extension in self.config.extensions:
self.setup_extension(extension)
buildername = "dummy"
self.preload_builder(buildername)
self.config.init_values()
self.events.emit("config-inited", self.config)
with tempfile.TemporaryDirectory() as tempdir:
# creating a builder attempts to make the doctreedir
self.doctreedir = tempdir
self.builder = self.create_builder(buildername)
self.doctreedir = ""
def __init__(self,
confoverrides=None,
srcdir=None,
raise_on_warning=False):
self.extensions = {}
self.registry = SphinxComponentRegistry()
self.html_themes = {}
self.events = EventManager(self)
# logging
self.verbosity = 0
self._warncount = 0
self.warningiserror = raise_on_warning
self._status = StringIO()
self._warning = StringIO()
log_setup(self, self._status, self._warning)
self.tags = Tags(None)
self.config = Config({}, confoverrides or {})
self.config.pre_init_values()
self._init_i18n()
for extension in builtin_extensions:
self.registry.load_extension(self, extension)
# fresh env
self.doctreedir = None
self.srcdir = srcdir
self.confdir = None
self.outdir = None
self.project = Project(srcdir=srcdir, source_suffix=".md")
self.project.docnames = ["mock_docname"]
self.env = BuildEnvironment()
self.env.setup(self)
self.env.temp_data["docname"] = "mock_docname"
self.builder = None
if not with_builder:
return
# this code is only required for more complex parsing with extensions
for extension in self.config.extensions:
self.setup_extension(extension)
buildername = "dummy"
self.preload_builder(buildername)
self.config.init_values()
self.events.emit("config-inited", self.config)
with tempfile.TemporaryDirectory() as tempdir:
# creating a builder attempts to make the doctreedir
self.doctreedir = tempdir
self.builder = self.create_builder(buildername)
self.doctreedir = None
def load_config_file(dirname='.', filename='conf.py', cmd_args=''):
"""
Function that loads the values defined in the configuration file parses the
options given, and returns
a dictionary with the appropriate variables.
"""
# Search for conf.py in the ancestors of the current directory
dirname = find_conf_dir(dirname)
if dirname == None:
print 'ERROR: Configuration file', filename, 'could not be found.',
print 'Check the location of this script.'
sys.exit(1)
tags = []
eval_strs = []
debug = False
# Swallow the options
try:
opts, args = getopt.getopt(sys.argv[1:], "dt:D:", [])
except getopt.GetoptError:
print >> sys.stderr, 'Incorrect option.'
print >> sys.stderr, main.__doc__
sys.exit(2)
# Parse the options
for optstr, value in opts:
# Debug option
if optstr == "-d":
debug = True
if optstr == "-t":
tags.append(value)
if optstr == "-D":
eval_strs.append(value)
current_dir = os.getcwd()
tags = Tags(tags)
os.chdir(dirname)
exec(open(filename).read())
# Evaluate the remaining strings
for value in eval_strs:
parts = value.split('=')
if len(parts) != 2:
print 'ERROR: Invalid syntax in option', value
sys.exit(1)
exec(parts[0] + "='" + parts[1] + "'")
del eval_strs
return (locals(), args)
def main():
Arguments.parse_arguments()
tags: Tags = Tags()
local = locals()
exec(open(os.path.join(Arguments.root, 'conf.py')).read(), local)
Consistency.levels = (list(local['didactic_levels'].keys())
+ [ALL, DEFAULT])
Consistency.scenarios = (list(local['didactic_scenarios'].keys())
+ [ALL, DEFAULT])
global hex_hash
hex_hash = local['hex_hash']
Build.generate_build(Parse.load_configuration(Arguments.source))
def read_config(path, passed_tags):
tags = Tags()
passed_tags = sum(passed_tags, ())
for tag in passed_tags:
tags.add(tag)
namespace = {
"__file__": os.path.abspath(path),
"tags": tags,
}
olddir = os.getcwd()
try:
if not os.path.isfile(path):
msg = "'%s' is not found (or specify --locale-dir option)." % path
raise click.BadParameter(msg)
os.chdir(os.path.dirname(path) or ".")
execfile_(os.path.basename(path), namespace)
finally:
os.chdir(olddir)
return namespace
def __init__(self,
srcdir,
confdir,
outdir,
doctreedir,
buildername,
confoverrides=None,
status=sys.stdout,
warning=sys.stderr,
freshenv=False,
warningiserror=False,
tags=None,
verbosity=0,
parallel=0):
self.verbosity = verbosity
self.next_listener_id = 0
self._extensions = {}
self._listeners = {}
self.domains = BUILTIN_DOMAINS.copy()
self.builderclasses = BUILTIN_BUILDERS.copy()
self.builder = None
self.env = None
self.srcdir = srcdir
self.confdir = confdir
self.outdir = outdir
self.doctreedir = doctreedir
self.parallel = parallel
if status is None:
self._status = StringIO()
self.quiet = True
else:
self._status = status
self.quiet = False
if warning is None:
self._warning = StringIO()
else:
self._warning = warning
self._warncount = 0
self.warningiserror = warningiserror
self._events = events.copy()
# say hello to the world
self.info(bold('Running Sphinx v%s' % sphinx.__version__))
# status code for command-line application
self.statuscode = 0
# read config
self.tags = Tags(tags)
self.config = Config(confdir, CONFIG_FILENAME, confoverrides or {},
self.tags)
self.config.check_unicode(self.warn)
# set confdir to srcdir if -C given (!= no confdir); a few pieces
# of code expect a confdir to be set
if self.confdir is None:
self.confdir = self.srcdir
# backwards compatibility: activate old C markup
self.setup_extension('sphinx.ext.oldcmarkup')
# load all user-given extension modules
for extension in self.config.extensions:
self.setup_extension(extension)
# the config file itself can be an extension
if self.config.setup:
self.config.setup(self)
# now that we know all config values, collect them from conf.py
self.config.init_values()
# check the Sphinx version if requested
if self.config.needs_sphinx and \
self.config.needs_sphinx > sphinx.__version__[:3]:
raise VersionRequirementError(
'This project needs at least Sphinx v%s and therefore cannot '
'be built with this version.' % self.config.needs_sphinx)
# set up translation infrastructure
self._init_i18n()
# set up the build environment
self._init_env(freshenv)
# set up the builder
self._init_builder(buildername)
def __init__(self,
srcdir,
confdir,
outdir,
doctreedir,
buildername,
confoverrides=None,
status=sys.stdout,
warning=sys.stderr,
freshenv=False,
warningiserror=False,
tags=None,
verbosity=0,
parallel=0,
keep_going=False):
# type: (str, str, str, str, str, Dict, IO, IO, bool, bool, List[str], int, int, bool) -> None # NOQA
self.phase = BuildPhase.INITIALIZATION
self.verbosity = verbosity
self.extensions = {} # type: Dict[str, Extension]
self.builder = None # type: Builder
self.env = None # type: BuildEnvironment
self.project = None # type: Project
self.registry = SphinxComponentRegistry()
self.html_themes = {} # type: Dict[str, str]
# validate provided directories
self.srcdir = abspath(srcdir)
self.outdir = abspath(outdir)
self.doctreedir = abspath(doctreedir)
self.confdir = confdir
if self.confdir: # confdir is optional
self.confdir = abspath(self.confdir)
if not path.isfile(path.join(self.confdir, 'conf.py')):
raise ApplicationError(
__("config directory doesn't contain a "
"conf.py file (%s)") % confdir)
if not path.isdir(self.srcdir):
raise ApplicationError(
__('Cannot find source directory (%s)') % self.srcdir)
if self.srcdir == self.outdir:
raise ApplicationError(
__('Source directory and destination '
'directory cannot be identical'))
self.parallel = parallel
if status is None:
self._status = StringIO() # type: IO
self.quiet = True
else:
self._status = status
self.quiet = False
if warning is None:
self._warning = StringIO() # type: IO
else:
self._warning = warning
self._warncount = 0
self.keep_going = warningiserror and keep_going
if self.keep_going:
self.warningiserror = False
else:
self.warningiserror = warningiserror
logging.setup(self, self._status, self._warning)
self.events = EventManager(self)
# keep last few messages for traceback
# This will be filled by sphinx.util.logging.LastMessagesWriter
self.messagelog = deque(maxlen=10) # type: deque
# say hello to the world
logger.info(bold(
__('Running Sphinx v%s') % sphinx.__display_version__))
# notice for parallel build on macOS and py38+
if sys.version_info > (
3, 8) and platform.system() == 'Darwin' and parallel > 1:
logger.info(
bold(
__("For security reason, parallel mode is disabled on macOS and "
"python3.8 and above. For more details, please read "
"https://github.com/sphinx-doc/sphinx/issues/6803")))
# status code for command-line application
self.statuscode = 0
# read config
self.tags = Tags(tags)
if self.confdir is None:
self.config = Config({}, confoverrides or {})
else:
self.config = Config.read(self.confdir, confoverrides or {},
self.tags)
# initialize some limited config variables before initialize i18n and loading
# extensions
self.config.pre_init_values()
# set up translation infrastructure
self._init_i18n()
# check the Sphinx version if requested
if self.config.needs_sphinx and self.config.needs_sphinx > sphinx.__display_version__:
raise VersionRequirementError(
__('This project needs at least Sphinx v%s and therefore cannot '
'be built with this version.') % self.config.needs_sphinx)
# set confdir to srcdir if -C given (!= no confdir); a few pieces
# of code expect a confdir to be set
if self.confdir is None:
self.confdir = self.srcdir
# load all built-in extension modules
for extension in builtin_extensions:
self.setup_extension(extension)
# load all user-given extension modules
for extension in self.config.extensions:
self.setup_extension(extension)
# preload builder module (before init config values)
self.preload_builder(buildername)
if not path.isdir(outdir):
with progress_message(__('making output directory')):
ensuredir(outdir)
# the config file itself can be an extension
if self.config.setup:
prefix = __('while setting up extension %s:') % "conf.py"
with prefixed_warnings(prefix):
if callable(self.config.setup):
self.config.setup(self)
else:
raise ConfigError(
__("'setup' as currently defined in conf.py isn't a Python callable. "
"Please modify its definition to make it a callable function. "
"This is needed for conf.py to behave as a Sphinx extension."
))
# now that we know all config values, collect them from conf.py
self.config.init_values()
self.events.emit('config-inited', self.config)
# create the project
self.project = Project(self.srcdir, self.config.source_suffix)
# create the builder
self.builder = self.create_builder(buildername)
# set up the build environment
self._init_env(freshenv)
# set up the builder
self._init_builder()
def __init__(self,
srcdir,
confdir,
outdir,
doctreedir,
buildername,
confoverrides=None,
status=sys.stdout,
warning=sys.stderr,
freshenv=False,
warningiserror=False,
tags=None,
verbosity=0,
parallel=0):
self.verbosity = verbosity
self.next_listener_id = 0
self._extensions = {}
self._extension_metadata = {}
self._additional_source_parsers = {}
self._listeners = {}
self._setting_up_extension = ['?']
self.domains = {}
self.buildername = buildername
self.builderclasses = {}
self.builder = None
self.env = None
self.enumerable_nodes = {}
self.srcdir = srcdir
self.confdir = confdir
self.outdir = outdir
self.doctreedir = doctreedir
self.parallel = parallel
if status is None:
self._status = cStringIO()
self.quiet = True
else:
self._status = status
self.quiet = False
if warning is None:
self._warning = cStringIO()
else:
self._warning = warning
self._warncount = 0
self.warningiserror = warningiserror
self._events = events.copy()
self._translators = {}
# keep last few messages for traceback
self.messagelog = deque(maxlen=10)
# say hello to the world
self.info(bold('Running Sphinx v%s' % sphinx.__display_version__))
# status code for command-line application
self.statuscode = 0
if not path.isdir(outdir):
self.info('making output directory...')
os.makedirs(outdir)
# read config
self.tags = Tags(tags)
self.config = Config(confdir, CONFIG_FILENAME, confoverrides or {},
self.tags)
self.config.check_unicode(self.warn)
# defer checking types until i18n has been initialized
# initialize some limited config variables before loading extensions
self.config.pre_init_values(self.warn)
# check the Sphinx version if requested
if self.config.needs_sphinx and self.config.needs_sphinx > sphinx.__display_version__:
raise VersionRequirementError(
'This project needs at least Sphinx v%s and therefore cannot '
'be built with this version.' % self.config.needs_sphinx)
# force preload html_translator_class
if self.config.html_translator_class:
translator_class = self.import_object(
self.config.html_translator_class,
'html_translator_class setting')
self.set_translator('html', translator_class)
# set confdir to srcdir if -C given (!= no confdir); a few pieces
# of code expect a confdir to be set
if self.confdir is None:
self.confdir = self.srcdir
# load all built-in extension modules
for extension in builtin_extensions:
self.setup_extension(extension)
# extension loading support for alabaster theme
# self.config.html_theme is not set from conf.py at here
# for now, sphinx always load a 'alabaster' extension.
if 'alabaster' not in self.config.extensions:
self.config.extensions.append('alabaster')
# load all user-given extension modules
for extension in self.config.extensions:
self.setup_extension(extension)
# the config file itself can be an extension
if self.config.setup:
self._setting_up_extension = ['conf.py']
# py31 doesn't have 'callable' function for below check
if hasattr(self.config.setup, '__call__'):
self.config.setup(self)
else:
raise ConfigError(
"'setup' that is specified in the conf.py has not been " +
"callable. Please provide a callable `setup` function " +
"in order to behave as a sphinx extension conf.py itself.")
# now that we know all config values, collect them from conf.py
self.config.init_values(self.warn)
# check extension versions if requested
if self.config.needs_extensions:
for extname, needs_ver in self.config.needs_extensions.items():
if extname not in self._extensions:
self.warn(
'needs_extensions config value specifies a '
'version requirement for extension %s, but it is '
'not loaded' % extname)
continue
has_ver = self._extension_metadata[extname]['version']
if has_ver == 'unknown version' or needs_ver > has_ver:
raise VersionRequirementError(
'This project needs the extension %s at least in '
'version %s and therefore cannot be built with the '
'loaded version (%s).' % (extname, needs_ver, has_ver))
# check primary_domain if requested
if self.config.primary_domain and self.config.primary_domain not in self.domains:
self.warn('primary_domain %r not found, ignored.' %
self.config.primary_domain)
# set up translation infrastructure
self._init_i18n()
# check all configuration values for permissible types
self.config.check_types(self.warn)
# set up source_parsers
self._init_source_parsers()
# set up the build environment
self._init_env(freshenv)
# set up the builder
self._init_builder(self.buildername)
# set up the enumerable nodes
self._init_enumerable_nodes()
def __init__(self, srcdir, confdir, outdir, doctreedir, buildername,
confoverrides=None, status=sys.stdout, warning=sys.stderr,
freshenv=False, warningiserror=False, tags=None, verbosity=0,
parallel=0):
# type: (unicode, unicode, unicode, unicode, unicode, Dict, IO, IO, bool, bool, List[unicode], int, int) -> None # NOQA
self.verbosity = verbosity
self.extensions = {} # type: Dict[unicode, Extension]
self._setting_up_extension = ['?'] # type: List[unicode]
self.builder = None # type: Builder
self.env = None # type: BuildEnvironment
self.registry = SphinxComponentRegistry()
self.enumerable_nodes = {} # type: Dict[nodes.Node, Tuple[unicode, Callable]] # NOQA
self.post_transforms = [] # type: List[Transform]
self.html_themes = {} # type: Dict[unicode, unicode]
self.srcdir = srcdir
self.confdir = confdir
self.outdir = outdir
self.doctreedir = doctreedir
self.parallel = parallel
if status is None:
self._status = cStringIO() # type: IO
self.quiet = True
else:
self._status = status
self.quiet = False
if warning is None:
self._warning = cStringIO() # type: IO
else:
self._warning = warning
self._warncount = 0
self.warningiserror = warningiserror
logging.setup(self, self._status, self._warning)
self.events = EventManager()
# keep last few messages for traceback
# This will be filled by sphinx.util.logging.LastMessagesWriter
self.messagelog = deque(maxlen=10) # type: deque
# say hello to the world
logger.info(bold('Running Sphinx v%s' % sphinx.__display_version__))
# status code for command-line application
self.statuscode = 0
if not path.isdir(outdir):
logger.info('making output directory...')
os.makedirs(outdir)
# read config
self.tags = Tags(tags)
self.config = Config(confdir, CONFIG_FILENAME,
confoverrides or {}, self.tags)
self.config.check_unicode()
# defer checking types until i18n has been initialized
# initialize some limited config variables before initialize i18n and loading
# extensions
self.config.pre_init_values()
# set up translation infrastructure
self._init_i18n()
# check the Sphinx version if requested
if self.config.needs_sphinx and self.config.needs_sphinx > sphinx.__display_version__:
raise VersionRequirementError(
_('This project needs at least Sphinx v%s and therefore cannot '
'be built with this version.') % self.config.needs_sphinx)
# set confdir to srcdir if -C given (!= no confdir); a few pieces
# of code expect a confdir to be set
if self.confdir is None:
self.confdir = self.srcdir
# load all built-in extension modules
for extension in builtin_extensions:
self.setup_extension(extension)
# load all user-given extension modules
for extension in self.config.extensions:
self.setup_extension(extension)
# preload builder module (before init config values)
self.preload_builder(buildername)
# the config file itself can be an extension
if self.config.setup:
self._setting_up_extension = ['conf.py']
# py31 doesn't have 'callable' function for below check
if hasattr(self.config.setup, '__call__'):
self.config.setup(self)
else:
raise ConfigError(
_("'setup' as currently defined in conf.py isn't a Python callable. "
"Please modify its definition to make it a callable function. This is "
"needed for conf.py to behave as a Sphinx extension.")
)
# now that we know all config values, collect them from conf.py
self.config.init_values()
# check extension versions if requested
verify_required_extensions(self, self.config.needs_extensions)
# check primary_domain if requested
primary_domain = self.config.primary_domain
if primary_domain and not self.registry.has_domain(primary_domain):
logger.warning(_('primary_domain %r not found, ignored.'), primary_domain)
# create the builder
self.builder = self.create_builder(buildername)
# check all configuration values for permissible types
self.config.check_types()
# set up source_parsers
self._init_source_parsers()
# set up the build environment
self._init_env(freshenv)
# set up the builder
self._init_builder()
# set up the enumerable nodes
self._init_enumerable_nodes()
def __init__(self,
srcdir,
confdir,
outdir,
doctreedir,
buildername,
confoverrides,
status,
warning=sys.stderr,
freshenv=False,
warningiserror=False,
tags=None):
self.next_listener_id = 0
self._extensions = {}
self._listeners = {}
self.builderclasses = BUILTIN_BUILDERS.copy()
self.builder = None
self.srcdir = srcdir
self.confdir = confdir
self.outdir = outdir
self.doctreedir = doctreedir
if status is None:
self._status = StringIO()
self.quiet = True
else:
self._status = status
self.quiet = False
if warning is None:
self._warning = StringIO()
else:
self._warning = warning
self._warncount = 0
self.warningiserror = warningiserror
self._events = events.copy()
# say hello to the world
self.info(bold('Running Sphinx v%s' % sphinx.__version__))
# status code for command-line application
self.statuscode = 0
# read config
self.tags = Tags(tags)
self.config = Config(confdir, CONFIG_FILENAME, confoverrides,
self.tags)
# load all extension modules
for extension in self.config.extensions:
self.setup_extension(extension)
# the config file itself can be an extension
if self.config.setup:
self.config.setup(self)
# now that we know all config values, collect them from conf.py
self.config.init_values()
if buildername is None:
print >> status, 'No builder selected, using default: html'
buildername = 'html'
if buildername not in self.builderclasses:
raise SphinxError('Builder name %s not registered' % buildername)
builderclass = self.builderclasses[buildername]
if isinstance(builderclass, tuple):
# builtin builder
mod, cls = builderclass
builderclass = getattr(
__import__('sphinx.builders.' + mod, None, None, [cls]), cls)
self.builder = builderclass(self, freshenv=freshenv)
self.builder.tags = self.tags
self.builder.tags.add(self.builder.format)
self.emit('builder-inited')
from sphinx.cmd import build
sphinx_build = build.main
except ImportError:
from sphinx import build_main as sphinx_build
argv_prefix = ["sphinx-build"]
from sphinx import config as sphinx_config
if not hasattr(sphinx_config.Config, "read"):
from sphinx.util.tags import Tags
sphinx_config.Config.read = staticmethod(
lambda path: sphinx_config.Config(
path, os.path.join(path, "conf.py"), {}, Tags()
)
)
if len(sys.argv) < 5:
print(
"versionselector.py DOCSFOLDER CURRENT LATEST METADATA [ ADDITIONAL ]",
file=sys.stderr,
)
sys.exit(-1)
docsfolder = sys.argv[1]
current = sys.argv[2]
latest = sys.argv[3]
metadata = sys.argv[4]
add_argv = sys.argv[5:] if len(sys.argv) > 5 else []
