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

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!

[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.

[soapraj]

For Beta release we should consider

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