def build(config, live_server=False, dump_json=False, clean_site_dir=False):
"""
Perform a full site build.
"""
if clean_site_dir:
print("Cleaning site directory")
utils.clean_directory(config['site_dir'])
if not live_server:
print("Building documentation to directory: %s" % config['site_dir'])
if not clean_site_dir and site_directory_contains_stale_files(config['site_dir']):
print("Directory %s contains stale files. Use --clean to remove them." % config['site_dir'])
if dump_json:
build_pages(config, dump_json=True)
return
# Reversed as we want to take the media files from the builtin theme
# and then from the custom theme_dir so the custom versions take take
# precedence.
for theme_dir in reversed(config['theme_dir']):
log.debug("Copying static assets from theme: %s", theme_dir)
utils.copy_media_files(theme_dir, config['site_dir'])
log.debug("Copying static assets from the docs dir.")
utils.copy_media_files(config['docs_dir'], config['site_dir'])
log.debug("Building markdown pages.")
build_pages(config)
def build(config, live_server=False, dump_json=False, dirty=False):
"""
Perform a full site build.
"""
if not dirty:
log.info("Cleaning site directory")
utils.clean_directory(config['site_dir'])
else:
# Warn user about problems that may occur with --dirty option
log.warning("A 'dirty' build is being performed, this will likely lead to inaccurate navigation and other"
" links within your site. This option is designed for site development purposes only.")
if not live_server:
log.info("Building documentation to directory: %s", config['site_dir'])
if dirty and site_directory_contains_stale_files(config['site_dir']):
log.info("The directory contains stale files. Use --clean to remove them.")
if dump_json:
build_pages(config, dump_json=True, dirty=dirty)
return
# Reversed as we want to take the media files from the builtin theme
# and then from the custom theme_dir so that the custom versions take
# precedence.
for theme_dir in reversed(config['theme_dir']):
log.debug("Copying static assets from theme: %s", theme_dir)
utils.copy_media_files(
theme_dir, config['site_dir'], exclude=['*.py', '*.pyc', '*.html'], dirty=dirty
)
log.debug("Copying static assets from the docs dir.")
utils.copy_media_files(config['docs_dir'], config['site_dir'], dirty=dirty)
log.debug("Building markdown pages.")
build_pages(config, dirty=dirty)
def build(config, live_server=False, dump_json=False, clean_site_dir=False):
"""
Perform a full site build.
"""
if clean_site_dir:
print("Cleaning site directory")
utils.clean_directory(config['site_dir'])
if not live_server:
print("Building documentation to directory: %s" % config['site_dir'])
if not clean_site_dir and site_directory_contains_stale_files(
config['site_dir']):
print(
"Directory %s contains stale files. Use --clean to remove them."
% config['site_dir'])
if dump_json:
build_pages(config, dump_json=True)
return
# Reversed as we want to take the media files from the builtin theme
# and then from the custom theme_dir so the custom versions take take
# precedence.
for theme_dir in reversed(config['theme_dir']):
log.debug("Copying static assets from theme: %s", theme_dir)
utils.copy_media_files(theme_dir, config['site_dir'])
log.debug("Copying static assets from the docs dir.")
utils.copy_media_files(config['docs_dir'], config['site_dir'])
log.debug("Building markdown pages.")
build_pages(config)
def build(config, live_server=False, dump_json=False, dirty=False):
"""
Perform a full site build.
"""
if not dirty:
log.info("Cleaning site directory")
utils.clean_directory(config['site_dir'])
else:
# Warn user about problems that may occur with --dirty option
log.warning("A 'dirty' build is being performed, this will likely lead to inaccurate navigation and other"
" links within your site. This option is designed for site development purposes only.")
if not live_server:
log.info("Building documentation to directory: %s", config['site_dir'])
if dirty and site_directory_contains_stale_files(config['site_dir']):
log.info("The directory contains stale files. Use --clean to remove them.")
if dump_json:
build_pages(config, dump_json=True, dirty=dirty)
return
# Reversed as we want to take the media files from the builtin theme
# and then from the custom theme_dir so that the custom versions take
# precedence.
for theme_dir in reversed(config['theme_dir']):
log.debug("Copying static assets from theme: %s", theme_dir)
utils.copy_media_files(
theme_dir, config['site_dir'], exclude=['*.py', '*.pyc', '*.html'], dirty=dirty
)
log.debug("Copying static assets from the docs dir.")
utils.copy_media_files(config['docs_dir'], config['site_dir'], dirty=dirty)
log.debug("Building markdown pages.")
build_pages(config, dirty=dirty)
def test_unicode_clean_directory(self):
temp_dir = tempfile.mkdtemp()
utf8_temp_dir = os.path.join(dec('tmp'), dec('tmp_utf8'))
utf8_directory = os.path.join(utf8_temp_dir, '导航')
utf8_utf8_directory = os.path.join(utf8_directory, '导航')
ascii_directory = os.path.join(temp_dir, 'bar')
ascii_ascii_directory = os.path.join(ascii_directory, 'bar')
os.makedirs(utf8_utf8_directory)
os.makedirs(ascii_ascii_directory)
utf_8_path = os.path.join(utf8_utf8_directory, 'foo.txt')
ascii_path = os.path.join(ascii_ascii_directory, 'foo.txt')
with open(utf_8_path, 'w') as f:
f.write('content')
with open(ascii_path, 'w') as f:
f.write('content')
try:
utils.clean_directory(utf8_directory)
utils.clean_directory(ascii_directory)
self.assertFalse(os.path.exists(utf_8_path))
self.assertFalse(os.path.exists(ascii_path))
self.assertFalse(os.path.exists(utf8_utf8_directory))
self.assertFalse(os.path.exists(ascii_ascii_directory))
finally:
shutil.rmtree(temp_dir)
shutil.rmtree(utf8_temp_dir)
def build(config, live_server=False, dump_json=False, clean_site_dir=False):
"""
Perform a full site build.
"""
if clean_site_dir:
print("Cleaning site directory")
utils.clean_directory(config['site_dir'])
if not live_server:
print("Building documentation to directory: %s" % config['site_dir'])
if not clean_site_dir and site_directory_contains_stale_files(config['site_dir']):
print("Directory %s contains stale files. Use --clean to remove them." % config['site_dir'])
if dump_json:
build_pages(config, dump_json=True)
else:
for theme_dir in config['theme_dir']:
utils.copy_media_files(theme_dir, config['site_dir'])
utils.copy_media_files(config['docs_dir'], config['site_dir'])
build_pages(config)
def build(config, live_server=False, dump_json=False, clean_site_dir=False):
"""
Perform a full site build.
"""
if clean_site_dir:
print("Cleaning site directory")
utils.clean_directory(config["site_dir"])
if not live_server:
print("Building documentation to directory: %s" % config["site_dir"])
if not clean_site_dir and site_directory_contains_stale_files(config["site_dir"]):
print("Directory %s contains stale files. Use --clean to remove them." % config["site_dir"])
if dump_json:
build_pages(config, dump_json=True)
else:
# Reversed as we want to take the media files from the builtin theme
# and then from the custom theme_dir so the custom versions take take
# precedence.
for theme_dir in reversed(config["theme_dir"]):
utils.copy_media_files(theme_dir, config["site_dir"])
utils.copy_media_files(config["docs_dir"], config["site_dir"])
build_pages(config)
def build(config, live_server=False, dirty=False):
""" Perform a full site build. """
try:
from time import time
start = time()
# Run `config` plugin events.
config = config['plugins'].run_event('config', config)
# Run `pre_build` plugin events.
config['plugins'].run_event('pre_build', config=config)
if not dirty:
log.info("Cleaning site directory")
utils.clean_directory(config['site_dir'])
else: # pragma: no cover
# Warn user about problems that may occur with --dirty option
log.warning(
"A 'dirty' build is being performed, this will likely lead to inaccurate navigation and other"
" links within your site. This option is designed for site development purposes only."
)
if not live_server: # pragma: no cover
log.info("Building documentation to directory: %s",
config['site_dir'])
if dirty and site_directory_contains_stale_files(
config['site_dir']):
log.info(
"The directory contains stale files. Use --clean to remove them."
)
# First gather all data from all files/pages to ensure all data is consistent across all pages.
files = get_files(config)
env = config['theme'].get_env()
files.add_files_from_theme(env, config)
# Run `files` plugin events.
files = config['plugins'].run_event('files', files, config=config)
nav = get_navigation(files, config)
# Run `nav` plugin events.
nav = config['plugins'].run_event('nav',
nav,
config=config,
files=files)
log.debug("Reading markdown pages.")
for file in files.documentation_pages():
log.debug("Reading: " + file.src_path)
_populate_page(file.page, config, files, dirty)
# Run `env` plugin events.
env = config['plugins'].run_event('env',
env,
config=config,
files=files)
# Start writing files to site_dir now that all data is gathered. Note that order matters. Files
# with lower precedence get written first so that files with higher precedence can overwrite them.
log.debug("Copying static assets.")
files.copy_static_files(dirty=dirty)
for template in config['theme'].static_templates:
_build_theme_template(template, env, files, config, nav)
for template in config['extra_templates']:
_build_extra_template(template, files, config, nav)
log.debug("Building markdown pages.")
doc_files = files.documentation_pages()
for file in doc_files:
_build_page(file.page, config, doc_files, nav, env, dirty)
# Run `post_build` plugin events.
config['plugins'].run_event('post_build', config=config)
if config['strict'] and utils.warning_filter.count:
raise SystemExit(
'\nExited with {} warnings in strict mode.'.format(
utils.warning_filter.count))
log.info('Documentation built in %.2f seconds', time() - start)
except Exception as e:
# Run `build_error` plugin events.
config['plugins'].run_event('build_error', error=e)
if isinstance(e, BuildError):
raise SystemExit('\n' + str(e))
raise
def build(config, live_server=False, dirty=False):
""" Perform a full site build. """
from time import time
start = time()
# Run `config` plugin events.
config = config['plugins'].run_event('config', config)
# Run `pre_build` plugin events.
config['plugins'].run_event('pre_build', config=config)
if not dirty:
log.info("Cleaning site directory")
utils.clean_directory(config['site_dir'])
else: # pragma: no cover
# Warn user about problems that may occur with --dirty option
log.warning("A 'dirty' build is being performed, this will likely lead to inaccurate navigation and other"
" links within your site. This option is designed for site development purposes only.")
if not live_server: # pragma: no cover
log.info("Building documentation to directory: %s", config['site_dir'])
if dirty and site_directory_contains_stale_files(config['site_dir']):
log.info("The directory contains stale files. Use --clean to remove them.")
# First gather all data from all files/pages to ensure all data is consistent across all pages.
files = get_files(config)
env = config['theme'].get_env()
files.add_files_from_theme(env, config)
# Run `files` plugin events.
files = config['plugins'].run_event('files', files, config=config)
nav = get_navigation(files, config)
# Run `nav` plugin events.
nav = config['plugins'].run_event('nav', nav, config=config, files=files)
log.debug("Reading markdown pages.")
for file in files.documentation_pages():
log.debug("Reading: " + file.src_path)
_populate_page(file.page, config, files, dirty)
# Run `env` plugin events.
env = config['plugins'].run_event(
'env', env, config=config, files=files
)
# Start writing files to site_dir now that all data is gathered. Note that order matters. Files
# with lower precedence get written first so that files with higher precedence can overwrite them.
log.debug("Copying static assets.")
files.copy_static_files(dirty=dirty)
for template in config['theme'].static_templates:
_build_theme_template(template, env, files, config, nav)
for template in config['extra_templates']:
_build_extra_template(template, files, config, nav)
log.debug("Building markdown pages.")
for file in files.documentation_pages():
_build_page(file.page, config, files, nav, env, dirty)
# Run `post_build` plugin events.
config['plugins'].run_event('post_build', config=config)
if config['strict'] and utils.warning_filter.count:
raise SystemExit('\nExited with {} warnings in strict mode.'.format(utils.warning_filter.count))
log.info('Documentation built in %.2f seconds', time() - start)
