def test_get_files_exclude_readme_with_index(self, tdir):
config = load_config(docs_dir=tdir)
files = get_files(config)
expected = ['index.md', 'foo.md']
self.assertIsInstance(files, Files)
self.assertEqual(len(files), len(expected))
self.assertEqual([f.src_path for f in files], expected)
def test_get_files(self, tdir):
config = load_config(docs_dir=tdir,
extra_css=['bar.css'],
extra_javascript=['bar.js'])
files = get_files(config)
expected = [
'index.md', 'bar.css', 'bar.html', 'bar.jpg', 'bar.js', 'bar.md'
]
self.assertIsInstance(files, Files)
self.assertEqual(len(files), len(expected))
self.assertEqual([f.src_path for f in files], expected)
def test_add_files_from_theme(self, tdir, ddir):
config = load_config(docs_dir=ddir,
theme={
'name': None,
'custom_dir': tdir
})
env = config['theme'].get_env()
files = get_files(config)
self.assertEqual([file.src_path for file in files],
['index.md', 'favicon.ico'])
files.add_files_from_theme(env, config)
self.assertEqual([file.src_path for file in files],
['index.md', 'favicon.ico', 'style.css'])
# Ensure theme file does not override docs_dir file
self.assertEqual(
files.get_file_from_path('favicon.ico').abs_src_path,
os.path.normpath(os.path.join(ddir, 'favicon.ico')))
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