def test_get_themes(self):
self.assertEqual(
sorted(utils.get_theme_names()),
sorted(['flatly', 'cerulean', 'slate', 'bootstrap', 'yeti',
'spacelab', 'united', 'readable', 'simplex', 'mkdocs',
'cosmo', 'journal', 'cyborg', 'readthedocs', 'amelia']))
def run_validation(self, value):
themes = utils.get_theme_names()
if value in themes:
# These themes have been moved to the mkdocs-bootstrap and
# mkdocs-bootswatch packages. At some point we wont depend on
# these by default.
moved_themes = [
'bootstrap', 'amelia', 'cerulean', 'cosmo', 'cyborg',
'flatly', 'journal', 'readable', 'simplex', 'slate',
'spacelab', 'united', 'yeti'
]
if value not in moved_themes:
return value
self.warnings.append(
("The theme '{0}' will be removed in an upcoming MkDocs "
"release. See http://www.mkdocs.org/about/release-notes/ "
"for more details").format(value)
)
return value
raise ValidationError(
"Unrecognised theme '{0}'. The available installed themes"
"are: ".format(value, ', '.join(themes))
)
def run_validation(self, value):
themes = utils.get_theme_names()
# These themes have been moved to the mkdocs-bootstrap and
# mkdocs-bootswatch packages. At some point we wont depend on
# these by default.
moved_themes = [
'bootstrap', 'amelia', 'cerulean', 'cosmo', 'cyborg',
'flatly', 'journal', 'readable', 'simplex', 'slate',
'spacelab', 'united', 'yeti'
]
if value in themes:
return value
elif value in moved_themes:
raise ValidationError(
("The theme '{0}' is no longer included in MkDocs by default "
"and must be installed with pip. See http://www.mkdocs.org"
"/about/release-notes/#add-support-for-installable-themes"
"for more details").format(value)
)
raise ValidationError(
"Unrecognised theme '{0}'. The available installed themes "
"are: {1}".format(value, ', '.join(themes))
)
def test_get_themes(self):
self.assertEqual(
sorted(utils.get_theme_names()),
sorted(['flatly', 'cerulean', 'slate', 'bootstrap', 'yeti',
'spacelab', 'united', 'readable', 'simplex', 'mkdocs',
'cosmo', 'journal', 'cyborg', 'readthedocs', 'amelia']))
def run_validation(self, value):
themes = utils.get_theme_names()
if value in themes:
# These themes have been moved to the mkdocs-bootstrap and
# mkdocs-bootswatch packages. At some point we wont depend on
# these by default.
moved_themes = [
'bootstrap', 'amelia', 'cerulean', 'cosmo', 'cyborg', 'flatly',
'journal', 'readable', 'simplex', 'slate', 'spacelab',
'united', 'yeti'
]
if value not in moved_themes:
return value
self.warnings.append(
("The theme '{0}' will be removed in an upcoming MkDocs "
"release. See http://www.mkdocs.org/about/release-notes/ "
"for more details").format(value))
return value
raise ValidationError(
"Unrecognised theme '{0}'. The available installed themes"
"are: ".format(value, ', '.join(themes)))
def test_get_themes_error(self, mock_iter):
theme1 = mock.Mock()
theme1.name = 'mkdocs'
theme1.dist.name = 'mkdocs'
theme1.load().__file__ = "some/path1"
theme2 = mock.Mock()
theme2.name = 'mkdocs'
theme2.dist.name = 'mkdocs2'
theme2.load().__file__ = "some/path2"
mock_iter.return_value = [theme1, theme2]
with self.assertRaises(exceptions.ConfigurationError):
utils.get_theme_names()
def run_validation(self, value):
themes = utils.get_theme_names()
# These themes have been moved to the mkdocs-bootstrap and
# mkdocs-bootswatch packages. At some point we wont depend on
# these by default.
moved_themes = [
'bootstrap', 'amelia', 'cerulean', 'cosmo', 'cyborg', 'flatly',
'journal', 'readable', 'simplex', 'slate', 'spacelab', 'united',
'yeti'
]
if value in themes:
return value
elif value in moved_themes:
raise ValidationError(
("The theme '{0}' is no longer included in MkDocs by default "
"and must be installed with pip. See http://www.mkdocs.org"
"/about/release-notes/#add-support-for-installable-themes"
"for more details").format(value))
raise ValidationError(
"Unrecognised theme '{0}'. The available installed themes "
"are: {1}".format(value, ', '.join(themes)))
def _load_theme_config(self, name):
""" Recursively load theme and any parent themes. """
theme_dir = utils.get_theme_dir(name)
self.dirs.append(theme_dir)
try:
file_path = os.path.join(theme_dir, 'mkdocs_theme.yml')
with open(file_path, 'rb') as f:
theme_config = utils.yaml_load(f)
except IOError as e:
log.debug(e)
raise ValidationError(
"The theme '{0}' does not appear to have a configuration file. "
"Please upgrade to a current version of the theme.".format(name)
)
log.debug("Loaded theme configuration for '%s' from '%s': %s", name, file_path, theme_config)
parent_theme = theme_config.pop('extends', None)
if parent_theme:
themes = utils.get_theme_names()
if parent_theme not in themes:
raise ValidationError(
"The theme '{0}' inherits from '{1}', which does not appear to be installed. "
"The available installed themes are: {2}".format(name, parent_theme, ', '.join(themes))
)
self._load_theme_config(parent_theme)
self.static_templates.update(theme_config.pop('static_templates', []))
self._vars.update(theme_config)
def _load_theme_config(self, name):
""" Recursively load theme and any parent themes. """
theme_dir = utils.get_theme_dir(name)
self.dirs.append(theme_dir)
try:
file_path = os.path.join(theme_dir, 'mkdocs_theme.yml')
with open(file_path, 'rb') as f:
theme_config = utils.yaml_load(f)
if theme_config is None:
theme_config = {}
except IOError as e:
log.debug(e)
raise ValidationError(
"The theme '{0}' does not appear to have a configuration file. "
"Please upgrade to a current version of the theme.".format(name)
)
log.debug("Loaded theme configuration for '%s' from '%s': %s", name, file_path, theme_config)
parent_theme = theme_config.pop('extends', None)
if parent_theme:
themes = utils.get_theme_names()
if parent_theme not in themes:
raise ValidationError(
"The theme '{0}' inherits from '{1}', which does not appear to be installed. "
"The available installed themes are: {2}".format(name, parent_theme, ', '.join(themes))
)
self._load_theme_config(parent_theme)
self.static_templates.update(theme_config.pop('static_templates', []))
self._vars.update(theme_config)
def run_validation(self, value):
themes = utils.get_theme_names()
if value in themes:
if value in ['mkdocs', 'readthedocs']:
return value
self.warnings.append(
("The theme '{0}' will be removed in an upcoming MkDocs "
"release. See http://www.mkdocs.org/about/release-notes/ "
"for more details").format(value))
return value
raise ValidationError("Unrecognised theme.")
def run_validation(self, value):
themes = utils.get_theme_names()
if value in themes:
if value in ['mkdocs', 'readthedocs']:
return value
self.warnings.append(
("The theme '{0}' will be removed in an upcoming MkDocs "
"release. See http://www.mkdocs.org/about/release-notes/ "
"for more details").format(value)
)
return value
raise ValidationError("Unrecognised theme.")
def test_get_themes_warning(self, mock_iter):
theme1 = mock.Mock()
theme1.name = 'mkdocs2'
theme1.dist.key = 'mkdocs2'
theme1.load().__file__ = "some/path1"
theme2 = mock.Mock()
theme2.name = 'mkdocs2'
theme2.dist.key = 'mkdocs3'
theme2.load().__file__ = "some/path2"
mock_iter.return_value = iter([theme1, theme2])
self.assertEqual(
sorted(utils.get_theme_names()),
sorted(['mkdocs2', ]))
def test_get_themes_warning(self, mock_iter):
theme1 = mock.Mock()
theme1.name = 'mkdocs2'
theme1.dist.key = 'mkdocs2'
theme1.load().__file__ = "some/path1"
theme2 = mock.Mock()
theme2.name = 'mkdocs2'
theme2.dist.key = 'mkdocs3'
theme2.load().__file__ = "some/path2"
mock_iter.return_value = iter([theme1, theme2])
self.assertEqual(sorted(utils.get_theme_names()), sorted([
'mkdocs2',
]))
def validate(self, value):
if value is None and self.default is not None:
value = {'name': self.default}
if isinstance(value, utils.string_types):
value = {'name': value}
themes = utils.get_theme_names()
if isinstance(value, dict):
if 'name' in value:
if value['name'] is None or value['name'] in themes:
return value
raise ValidationError(
"Unrecognised theme name: '{0}'. The available installed themes "
"are: {1}".format(value['name'], ', '.join(themes))
)
raise ValidationError("No theme name set.")
raise ValidationError('Invalid type "{0}". Expected a string or key/value pairs.'.format(type(value)))
def validate(self, value):
if value is None and self.default is not None:
value = {'name': self.default}
if isinstance(value, str):
value = {'name': value}
themes = utils.get_theme_names()
if isinstance(value, dict):
if 'name' in value:
if value['name'] is None or value['name'] in themes:
return value
raise ValidationError(
"Unrecognised theme name: '{}'. The available installed themes "
"are: {}".format(value['name'], ', '.join(themes))
)
raise ValidationError("No theme name set.")
raise ValidationError('Invalid type "{}". Expected a string or key/value pairs.'.format(type(value)))
def test_get_themes(self):
self.assertEqual(
sorted(utils.get_theme_names()),
['mkdocs', 'readthedocs'])
def test_get_themes(self):
self.assertEqual(sorted(utils.get_theme_names()),
['mkdocs', 'readthedocs'])
- Build with different configuration options.
- Build documentation other than just MkDocs as it is relatively simple.
"""
from __future__ import print_function
import click
import logging
import os
import sys
from mkdocs import cli, config, build, utils
DIR = os.path.dirname(__file__)
MKDOCS_CONFIG = os.path.abspath(os.path.join(DIR, '../../mkdocs.yml'))
MKDOCS_THEMES = utils.get_theme_names()
def silence_logging(is_verbose=False):
'''When a --verbose flag is passed, increase the verbosity of mkdocs'''
logger = logging.getLogger('mkdocs')
logger.setLevel(logging.WARNING)
def run_build(theme_name, output, config_file, quiet):
"""
Given a theme name and output directory use the configuration
for the MkDocs documentation and overwrite the site_dir and
theme. If no output is provided, serve the documentation on
each theme, one at a time.
self.counter = utils.log_counter
self.counter.setLevel(logging.WARNING)
self.logger.addHandler(self.counter)
pass_state = click.make_pass_decorator(State, ensure=True)
clean_help = "Remove old files from the site_dir before building (the default)."
config_help = "Provide a specific MkDocs config"
dev_addr_help = (
"IP address and port to serve documentation locally (default: "
"localhost:8000)")
strict_help = ("Enable strict mode. This will cause MkDocs to abort the build "
"on any warnings.")
theme_help = "The theme to use when building your documentation."
theme_choices = utils.get_theme_names()
site_dir_help = "The directory to output the result of the documentation build."
use_directory_urls_help = "Use directory URLs when building pages (the default)."
reload_help = "Enable the live reloading in the development server (this is the default)"
no_reload_help = "Disable the live reloading in the development server."
dirty_reload_help = "Enable the live reloading in the development server, but only re-build files that have changed"
commit_message_help = (
"A commit message to use when committing to the "
"Github Pages remote branch. Commit {sha} and MkDocs {version} are available as expansions"
)
remote_branch_help = ("The remote branch to commit to for Github Pages. This "
"overrides the value specified in config")
remote_name_help = ("The remote name to commit to for Github Pages. This "
"overrides the value specified in config")
force_help = "Force the push to the repository."
ignore_version_help = "Ignore check that build is not being deployed with an older version of MkDocs."
def common_options(f):
f = verbose_option(f)
f = quiet_option(f)
return f
clean_help = "Remove old files from the site_dir before building"
config_help = "Provide a specific MkDocs config"
dev_addr_help = ("IP address and port to serve documentation locally (default: "
"localhost:8000)")
strict_help = ("Enable strict mode. This will cause MkDocs to abort the build "
"on any warnings.")
theme_dir_help = "The theme directory to use when building your documentation."
theme_help = "The theme to use when building your documentation."
theme_choices = utils.get_theme_names()
site_dir_help = "The directory to output the result of the documentation build."
reload_help = "Enable and disable the live reloading in the development server."
commit_message_help = ("A commit message to use when commiting to the "
"Github Pages remote branch")
remote_branch_help = ("The remote branch to commit to for Github Pages. This "
"overrides the value specified in config")
remote_name_help = ("The remote name to commit to for Github Pages. This "
"overrides the value specified in config")
@click.group(context_settings={'help_option_names': ['-h', '--help']})
@click.version_option(__version__, '-V', '--version')
@common_options
def cli():
"""
- Build with different configuration options.
- Build documentation other than just MkDocs as it is relatively simple.
"""
import click
import logging
import os
import subprocess
from mkdocs import utils
log = logging.getLogger('mkdocs')
DIR = os.path.dirname(__file__)
MKDOCS_CONFIG = os.path.abspath(os.path.join(DIR, '../../mkdocs.yml'))
MKDOCS_THEMES = utils.get_theme_names()
TEST_PROJECTS = os.path.abspath(os.path.join(DIR, 'integration'))
@click.command()
@click.option('--output',
help="The output directory to use when building themes",
type=click.Path(file_okay=False, writable=True),
required=True)
def main(output=None):
log.propagate = False
stream = logging.StreamHandler()
formatter = logging.Formatter(
"\033[1m\033[1;32m *** %(message)s *** \033[0m")
stream.setFormatter(formatter)
