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_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 on_files(self, files, config):
root = os.path.join(os.path.dirname(pheasant.__file__), "theme")
docs_dir = config["docs_dir"]
config["docs_dir"] = root
files_ = get_files(config)
config["docs_dir"] = docs_dir
css = []
js = []
for file in files_:
path = file.src_path.replace("\\", "/")
if path.endswith(".css"):
files.append(file)
css.append(path)
elif path.endswith(".js"):
files.append(file)
js.append(path)
elif path.endswith(".yml"):
path = os.path.normpath(os.path.join(root, path))
with open(path) as f:
data = yaml.safe_load(f)
css = data.get("extra_css", []) + css
js = data.get("extra_javascript", []) + js
css = [x for x in css if x not in self.config["extra_css"]]
js = [x for x in js if x not in self.config["extra_javascript"]]
config["extra_css"] = css + self.config["extra_css"]
config["extra_javascript"] = js + self.config["extra_javascript"]
for file in files:
normalize_file(file, config)
return files
def on_files(self, files, config):
"""Collects plugin CSS ans JavaScript and appends them to `files`."""
root = os.path.join(os.path.dirname(mkapi.__file__), "theme")
docs_dir = config["docs_dir"]
config["docs_dir"] = root
files_ = get_files(config)
config["docs_dir"] = docs_dir
theme_name = config["theme"].name
css = []
js = []
for file in files_:
path = file.src_path.replace("\\", "/")
if path.endswith(".css"):
if "common" in path or theme_name in path:
files.append(file)
css.append(path)
elif path.endswith(".js"):
files.append(file)
js.append(path)
elif path.endswith(".yml"):
path = os.path.normpath(os.path.join(root, path))
with open(path) as f:
data = yaml.safe_load(f)
css = data.get("extra_css", []) + css
js = data.get("extra_javascript", []) + js
css = [x for x in css if x not in config["extra_css"]]
js = [x for x in js if x not in config["extra_javascript"]]
config["extra_css"] = css + config["extra_css"]
config["extra_javascript"] = js + config["extra_javascript"]
return files
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 _walk_files_and_render(self, config):
pool = self._create_threadpool()
files = get_files(config)
jobs = []
for file in files:
if file.src_path.endswith(self.config["file_extension"]):
jobs.append(pool.submit(self._render_diagram, file))
for job in concurrent.futures.as_completed(jobs):
try:
job.result()
except Exception:
self.log.exception(
"Worker raised an exception while rendering a diagram")
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 files(config, plugin, env):
files = get_files(config)
files.add_files_from_theme(env, config)
files = plugin.on_files(files, config)
return files
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)