def on_post_build(self, config: Config) -> None:
"""
Post build event handler.
Populates and builds pages with navigation for each translation.
:param config: mkdocs global config.
"""
logger.info("Building translations.")
for language in self.config.get("languages"):
logger.info(f"Building {language} documentation")
files = self.i18pages[language]
nav = config["plugins"].run_event(
"nav",
self.i18navs[language],
config=config,
files=files,
)
# Cycles are separated cause at first we need to populate all pages.
for populate_page in files.documentation_pages():
_populate_page(populate_page.page, config, files, dirty=False)
for build_page in self.i18pages[language].documentation_pages():
_build_page(
build_page.page,
config,
files,
nav,
env=config["theme"].get_env(),
dirty=False,
)
def test_build_page_dirty_not_modified(self, site_dir, mock_write_file):
cfg = load_config(site_dir=site_dir, nav=['testing.md'], plugins=[])
files = Files([File('testing.md', cfg['docs_dir'], cfg['site_dir'], cfg['use_directory_urls'])])
nav = get_navigation(files, cfg)
page = files.documentation_pages()[0].page
# Fake populate page
page.title = 'Title'
page.markdown = 'page content'
page.content = '<p>page content</p>'
build._build_page(page, cfg, files, nav, self._get_env_with_null_translations(cfg), dirty=True)
self.assert_mock_called_once(mock_write_file)
def test_build_page(self, site_dir):
cfg = load_config(site_dir=site_dir, nav=['index.md'], plugins=[])
files = Files([File('index.md', cfg['docs_dir'], cfg['site_dir'], cfg['use_directory_urls'])])
nav = get_navigation(files, cfg)
page = files.documentation_pages()[0].page
# Fake populate page
page.title = 'Title'
page.markdown = 'page content'
page.content = '<p>page content</p>'
build._build_page(page, cfg, files, nav, self._get_env_with_null_translations(cfg))
self.assertPathIsFile(site_dir, 'index.html')
def test_build_page_dirty_modified(self, site_dir, docs_dir, mock_write_file):
cfg = load_config(docs_dir=docs_dir, site_dir=site_dir, nav=['index.md'], plugins=[])
files = Files([File('index.md', cfg['docs_dir'], cfg['site_dir'], cfg['use_directory_urls'])])
nav = get_navigation(files, cfg)
page = files.documentation_pages()[0].page
# Fake populate page
page.title = 'Title'
page.markdown = 'new page content'
page.content = '<p>new page content</p>'
build._build_page(page, cfg, files, nav, cfg['theme'].get_env(), dirty=True)
mock_write_file.assert_not_called()
def test_build_page_dirty_not_modified(self, site_dir, mock_write_file):
cfg = load_config(site_dir=site_dir, nav=['index.md'], plugins=[])
files = Files([File('testing.md', cfg['docs_dir'], cfg['site_dir'], cfg['use_directory_urls'])])
nav = get_navigation(files, cfg)
page = files.documentation_pages()[0].page
# Fake populate page
page.title = 'Title'
page.markdown = 'page content'
page.content = '<p>page content</p>'
build._build_page(page, cfg, files, nav, cfg['theme'].get_env(), dirty=True)
mock_write_file.assert_called_once()
def test_build_page(self, site_dir):
cfg = load_config(site_dir=site_dir, nav=['index.md'], plugins=[])
files = Files([File('index.md', cfg['docs_dir'], cfg['site_dir'], cfg['use_directory_urls'])])
nav = get_navigation(files, cfg)
page = files.documentation_pages()[0].page
# Fake populate page
page.title = 'Title'
page.markdown = 'page content'
page.content = '<p>page content</p>'
build._build_page(page, cfg, files, nav, cfg['theme'].get_env())
self.assertPathIsFile(site_dir, 'index.html')
def test_build_page_custom_template(self, site_dir):
cfg = load_config(site_dir=site_dir, nav=['index.md'], plugins=[])
files = Files([File('index.md', cfg['docs_dir'], cfg['site_dir'], cfg['use_directory_urls'])])
nav = get_navigation(files, cfg)
page = files.documentation_pages()[0].page
# Fake populate page
page.title = 'Title'
page.meta = {'template': '404.html'}
page.markdown = 'page content'
page.content = '<p>page content</p>'
build._build_page(page, cfg, files, nav, cfg['theme'].get_env())
self.assertPathIsFile(site_dir, 'index.html')
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)
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 site to directory: %s", config['site_dir'])
if dirty and mkdocs_build.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 = mkdocs_build.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)
mkdocs_build._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.
for f in files:
print(f.page)
log.debug("Copying static assets.")
files.copy_static_files(dirty=dirty)
for template in config['theme'].static_templates:
mkdocs_build._build_theme_template(template, env, files, config, nav)
for template in config['extra_templates']:
mkdocs_build._build_extra_template(template, files, config, nav)
log.debug("Building markdown pages.")
for file in files.documentation_pages():
mkdocs_build._build_page(file.page, config, files, nav, env, dirty)
# Run `post_build` plugin events.
config['plugins'].run_event('post_build', config)
if config['strict'] and utils.warning_filter.count:
raise SystemExit('\nExited with {} warnings in strict mode.'.format(
utils.warning_filter.count))
log.info('site built in %.2f seconds', time() - start)
