Better error handling for tech-docs when folder or mkdocs.yml is missing

[O5ten]

The better error-handling or messages there are the less confused users of backstage we'll have.
Right now when the folder docs or the file mkdocs.yml is missing or named mkdocs.yaml ot gets cryptic error messages like this one.

Failed to generate docs from /tmp/backstage-YEeOfY into /tmp/techdocs-tmp-t8WrEp with error undefined

Right now users seem to believe that this is due to backstage being buggy instead of having incorrect data in their repos.
Most of these can be solved by some simple precondition-checks in the folder where the project is cloned to.

Expected Behavior

Missing docs folder:

Precondition:

fs.existsSync(docsFolder);

Message:

This project is missing the docs folder in the repository, you need to add it to be able to generate tech-docs

Missing mkdocs.yml:

Precondition

fs.existsSync('mkdocs.yml');

Message

The mkdocs.yml is missing in the root of this repository, making tech-docs unable to generate docs.

Incorrectly named mkdocs.yaml

Optionally it would be possible to rename mkdocs.yaml to mkdocs.yml in the cloned folder.

Precondition

!fs.existsSync('mkdocs.yml') && fs.existsSync('mkdocs.yaml'))

Message

The mkdocs.yaml file should be named mkdocs.yml in order to generate tech-docs for this project

Current Behavior

Errors like this are returned in the browser, while the message in the backend logs are a little better.

Failed to generate docs from /tmp/backstage-YEeOfY into /tmp/techdocs-tmp-t8WrEp with error undefined

Possible Solution

Use preconditions on folder before attempting to run mkdocs.

Context

Less confused users mean more and happy users!

[OrkoHunter]

Sweet! Thanks for listing multiple cases of improved error messages ☺️

[adamdmharvey]

Looks like this type of error is trapped by the techdocs-common stages generator helpers class:

backstage/packages/techdocs-common/src/stages/generate/helpers.ts

Lines 233 to 240 in a22fc19

	try {
	mkdocsYmlFileString = await fs.readFile(mkdocsYmlPath, 'utf8');
	} catch (error) {
	logger.warn(
	`Could not read file ${mkdocsYmlPath} before running the generator. ${error.message}`,
	);
	return;
	}

There are other good catch functions in there. Somehow I think those should catch, warn, and then throw a custom error specific to the type of issue. If done, then they could be caught up in the UI in plugins/techdocs maybe?

[dtuite]

We have a user who was quite confused by this today so adding my +1.

The logs do have some extra information which is helpful, but it is not exposed to the user.

Could not read file /tmp/backstage-18z0vE/mkdocs.yml before running the generator. ENOENT: no such file or directory, open '/tmp/backstage-18z0vE/mkdocs.yml

I suggest that mkdocs.yaml is renamed to mkdoks.yml if the .yaml file exists and the .yml file doesn't. In my mind it is commonly accepted that YAML files can end in either .yml or .yaml. The only error case should be if BOTH mkdocs.yaml and mkdocs.yml exist.

[OrkoHunter]

Totally. We have been waiting for mkdocs to allow this natively for us (mkdocs/mkdocs#2206) - but I don't think they are prioritising it anymore.

So, yes agree with you @dtuite that TechDocs should allow both yaml and yml on its own. I am imagining the following step to happen before running "generate" and after "prepare" step.

Check if `mkdocs.yml` exists
	If yes, proceed.
	If no, check if `mkdocs.yaml` exists.
		If yes, rename to `mkdocs.yml` and proceed.
		If no, existing error that neither mkdocs.yaml nor mkdocs.yml was found.

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[soapraj]

For Beta release we should consider

• supporting yaml and yml extensions
• better error messages when the yaml file or the folder is missing

[iamEAP]

Let's come back to this after #6341 and (to a lesser extent) mkdocs/mkdocs#2478 are in.

[iamEAP]

^ MkDocs PR was merged, but it's not released yet. This PR is related to the update we'll need to do though: backstage/mkdocs-techdocs-core#27