def load_yaml_config(self):
"""
Load a YAML config.
:raises: ``MkDocsYAMLParseError`` if failed due to syntax errors.
"""
try:
config = yaml_load_safely(open(self.yaml_file, 'r'))
if not config:
raise MkDocsYAMLParseError(
MkDocsYAMLParseError.EMPTY_CONFIG
)
if not isinstance(config, dict):
raise MkDocsYAMLParseError(
MkDocsYAMLParseError.CONFIG_NOT_DICT
)
return config
except IOError:
log.info(
'Creating default MkDocs config file for project: %s:%s',
self.project.slug,
self.version.slug,
)
return {
'site_name': self.version.project.name,
}
except yaml.YAMLError as exc:
note = ''
if hasattr(exc, 'problem_mark'):
mark = exc.problem_mark
note = ' (line %d, column %d)' % (
mark.line + 1,
mark.column + 1,
)
raise MkDocsYAMLParseError(
'Your mkdocs.yml could not be loaded, '
'possibly due to a syntax error{note}'.format(note=note),
)
def load_yaml_config(self):
"""
Load a YAML config.
Raise BuildEnvironmentError if failed due to syntax errors.
"""
try:
return yaml.safe_load(open(self.yaml_file, 'r'))
except IOError:
return {
'site_name': self.version.project.name,
}
except yaml.YAMLError as exc:
note = ''
if hasattr(exc, 'problem_mark'):
mark = exc.problem_mark
note = ' (line %d, column %d)' % (mark.line + 1,
mark.column + 1)
raise MkDocsYAMLParseError(
'Your mkdocs.yml could not be loaded, '
'possibly due to a syntax error{note}'.format(note=note))
def append_conf(self, **__):
"""
Set mkdocs config values.
:raises: ``MkDocsYAMLParseError`` if failed due to known type errors
(i.e. expecting a list and a string is found).
"""
if not self.yaml_file:
self.yaml_file = os.path.join(self.root_path, 'mkdocs.yml')
user_config = self.load_yaml_config()
# Handle custom docs dirs
user_docs_dir = user_config.get('docs_dir')
if not isinstance(user_docs_dir, (type(None), str)):
raise MkDocsYAMLParseError(
MkDocsYAMLParseError.INVALID_DOCS_DIR_CONFIG,
)
docs_dir = self.docs_dir(docs_dir=user_docs_dir)
self.create_index(extension='md')
user_config['docs_dir'] = docs_dir
# Set mkdocs config values
static_url = get_absolute_static_url()
for config in ('extra_css', 'extra_javascript'):
user_value = user_config.get(config, [])
if not isinstance(user_value, list):
raise MkDocsYAMLParseError(
MkDocsYAMLParseError.INVALID_EXTRA_CONFIG.format(
config=config,
),
)
extra_javascript_list = [
'readthedocs-data.js',
'%score/js/readthedocs-doc-embed.js' % static_url,
'%sjavascript/readthedocs-analytics.js' % static_url,
]
extra_css_list = [
'%scss/badge_only.css' % static_url,
'%scss/readthedocs-doc-embed.css' % static_url,
]
# Only add static file if the files are not already in the list
user_config.setdefault('extra_javascript', []).extend(
[js for js in extra_javascript_list if js not in user_config.get(
'extra_javascript')]
)
user_config.setdefault('extra_css', []).extend(
[css for css in extra_css_list if css not in user_config.get(
'extra_css')]
)
# The docs path is relative to the location
# of the mkdocs configuration file.
docs_path = os.path.join(
os.path.dirname(self.yaml_file),
docs_dir,
)
# RTD javascript writing
rtd_data = self.generate_rtd_data(
docs_dir=os.path.relpath(docs_path, self.root_path),
mkdocs_config=user_config,
)
with open(os.path.join(docs_path, 'readthedocs-data.js'), 'w') as f:
f.write(rtd_data)
# Use Read the Docs' analytics setup rather than mkdocs'
# This supports using RTD's privacy improvements around analytics
user_config['google_analytics'] = None
# README: make MkDocs to use ``readthedocs`` theme as default if the
# user didn't specify a specific theme manually
if self.project.has_feature(Feature.MKDOCS_THEME_RTD):
if 'theme' not in user_config:
# mkdocs<0.17 syntax
user_config['theme'] = self.DEFAULT_THEME_NAME
# Write the modified mkdocs configuration
yaml.safe_dump(
user_config,
open(self.yaml_file, 'w'),
)
# Write the mkdocs.yml to the build logs
self.run(
'cat',
os.path.relpath(self.yaml_file, self.root_path),
cwd=self.root_path,
)