Projects using build.commands to build their documentation can make usage of the $READTHEDOCS_OUTPUT directory to expose offline formats like PDF, ePUB, HTMLZip as documented in https://docs.readthedocs.io/en/latest/build-customization.html

Currently, we support one and only one file per offline format. We have an in-progress work at #10438, but the work required there is not trivial and it may be off from our roadmap/prioritization for some time now. I think that feature is important for big projects like CPython documentation and we should work on that as soon as possible, tho.

In the meantime, we could make the build process a little simpler by allowing any filename for the PDF saved under $READTHEDOCS_OUTPUT/pdf/ since right now it requires to exactly be $READTHEDOCS_OUTPUT/pdf/$READTHEDOCS_PROJECT.pdf --which is not documented anywhere 😄

I'd say that, as long as there is one and only one PDF file inside the output directory, we shouldn't care about the filename and rename it internally (probably at upload time) to be what we need it to be.

Code references:

• readthedocs.org/readthedocs/projects/tasks/builds.py

  Lines 605 to 623 in 90f1791

  	if artifact_type in ARTIFACT_TYPES_WITHOUT_MULTIPLE_FILES_SUPPORT:
  	artifact_format_files = len(os.listdir(artifact_directory))
  	if artifact_format_files > 1:
  	log.error(
  	"Multiple files are not supported for this format. "
  	"Skipping this output format.",
  	output_format=artifact_type,
  	)
  	raise BuildUserError(
  	BuildUserError.BUILD_OUTPUT_HAS_MULTIPLE_FILES.format(
  	artifact_type=artifact_type
  	)
  	)
  	if artifact_format_files == 0:
  	raise BuildUserError(
  	BuildUserError.BUILD_OUTPUT_HAS_0_FILES.format(
  	artifact_type=artifact_type
  	)
  	)

• readthedocs.org/readthedocs/projects/tasks/builds.py

  Lines 904 to 935 in 90f1791

  	# Upload formats
  	for media_type in types_to_copy:
  	from_path = self.data.project.artifact_path(
  	version=self.data.version.slug,
  	type_=media_type,
  	)
  	to_path = self.data.project.get_storage_path(
  	type_=media_type,
  	version_slug=self.data.version.slug,
  	include_file=False,
  	version_type=self.data.version.type,
  	)
  	self._log_directory_size(from_path, media_type)
  	try:
  	build_media_storage.rclone_sync_directory(from_path, to_path)
  	except Exception as exc:
  	# NOTE: the exceptions reported so far are:
  	# - botocore.exceptions:HTTPClientError
  	# - botocore.exceptions:ClientError
  	# - readthedocs.doc_builder.exceptions:BuildCancelled
  	log.exception(
  	"Error copying to storage",
  	media_type=media_type,
  	from_path=from_path,
  	to_path=to_path,
  	)
  	# Re-raise the exception to fail the build and handle it
  	# automatically at `on_failure`.
  	# It will clearly communicate the error to the user.
  	raise BuildAppError("Error uploading files to the storage.") from exc