MkDocs: remove mkdocs.yml manipulation

[ericholscher]

We're currently parsing mkdocs YAML, which has some issues. This is an OK solution in the short term. In the longer term, we'd really love to not do any YAML parsing/dumping, and instead find a better way to integrate with mkdocs via an extension, or some other way that isn't so error-prone.

The main reason we are doing this currently is to add some small things to the config file. We should research and find another way of handling this, probably talking with the mkdocs team to ensure it will be supported going forward.

We merged a custom YAML parser in #7507, but we should plan to remove it and integrate in a way that doesn't require complex YAML.

[stsewd]

I created an issue related to this (or the same?), about creating an extension for mkdocs #4924

[humitos]

The main reason we are doing this currently is to add some small things to the config file. We should research and find another way of handling this, probably talking with the mkdocs team to ensure it will be supported going forward.

We do this because we want to:

• inject JS and CSS files
• set our theme by default
• inject Google Analytics code

The code that performs these actions is at

readthedocs.org/readthedocs/doc_builder/backends/mkdocs.py

Lines 143 to 245 in 37650de

	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).
	"""
	user_config = self.load_yaml_config()
	# Handle custom docs dirs
	docs_dir = user_config.get('docs_dir', 'docs')
	if not isinstance(docs_dir, (type(None), str)):
	raise MkDocsYAMLParseError(
	MkDocsYAMLParseError.INVALID_DOCS_DIR_CONFIG,
	)
	user_config['docs_dir'] = docs_dir
	# MkDocs <=0.17.x doesn't support absolute paths,
	# it needs one with a full domain.
	if self.project.has_feature(Feature.DEFAULT_TO_MKDOCS_0_17_3):
	static_url = get_absolute_static_url()
	else:
	static_url = self.project.proxied_static_path
	# Set mkdocs config values.
	extra_assets = {
	'extra_javascript': [
	'readthedocs-data.js',
	f'{static_url}core/js/readthedocs-doc-embed.js',
	f'{static_url}javascript/readthedocs-analytics.js',
	],
	'extra_css': [
	f'{static_url}css/badge_only.css',
	f'{static_url}css/readthedocs-doc-embed.css',
	],
	}
	for config, extras in extra_assets.items():
	value = user_config.get(config, [])
	if value is None:
	value = []
	if not isinstance(value, list):
	raise MkDocsYAMLParseError(
	MkDocsYAMLParseError.INVALID_EXTRA_CONFIG.format(
	config=config,
	),
	)
	# Add the static file only if isn't already in the list.
	value.extend([
	extra
	for extra in extras
	if extra not in value
	])
	user_config[config] = value
	# 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,
	)
	# if user puts an invalid `docs_dir` path raise an Exception
	if not os.path.exists(docs_path):
	raise MkDocsYAMLParseError(
	MkDocsYAMLParseError.INVALID_DOCS_DIR_PATH,
	)
	# RTD javascript writing
	rtd_data = self.generate_rtd_data(
	docs_dir=os.path.relpath(docs_path, self.project_path),
	mkdocs_config=user_config,
	)
	with open(
	os.path.join(docs_path, "readthedocs-data.js"), "w", encoding="utf-8"
	) 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
	with open(self.yaml_file, "w", encoding="utf-8") as f:
	yaml_dump_safely(
	user_config,
	f,
	)
	# Write the mkdocs.yml to the build logs
	self.run(
	'cat',
	os.path.relpath(self.yaml_file, self.project_path),
	cwd=self.project_path,
	)

Note that none of these 3 actions will be required anymore, so we will be able to remove the manipulation of the YAML completely. I wrote a more extended comment in https://github.com/readthedocs/meta/issues/85#issuecomment-1616690964 that also touches this topic.

[ericholscher]

Note that none of these 3 actions will be required anymore, so we will be able to remove the manipulation of the YAML completely. I

Wonderful ❤️

[humitos]

Closing in favor of readthedocs/addons#72