Notifications: improve copy on error messages (#11062)

* Notifications: de-duplicate/standardize concurrency limit reached

* Notifications: improve copy

* Remove unused `message_id`

* Improve missing/not found `mkdocs.yml` file

Closes #7707

* Improve `sphinx.configuration` file not found error message

This validation should eventually happen at the Read the Docs config file.
We are not there, but at least we are giving a better error message to users.

Closes #8352

* Improve copy for error messages

* Pass `format_values` to format the filename properly in the message

* Apply suggestions from code review

Co-authored-by: Anthony <[email protected]>

* Show the type of the received value

* Better header

* Lint

* Render class name via custom template filter

```
In [4]: n.get_message().get_rendered_body()
Out[4]: '\n\n\nConfig validation error in <code></code>.\nExpected a list, got
type <code>int</code> (<code>422</code>).'
```

* Make the title clearer

* Remove "\n\n\n" due to tests failing

---------

Co-authored-by: Anthony <[email protected]>

Author: humitos

readthedocs/config/exceptions.py

@@ -11,7 +11,6 @@ class ConfigError(BuildUserError):
         "config:python:use-system-site-packages-removed"
     )
     INVALID_VERSION = "config:base:invalid-version"
-    GENERIC_INVALID_CONFIG_KEY = "config:key:generic-invalid-config-key"
     NOT_BUILD_TOOLS_OR_COMMANDS = "config:build:missing-build-tools-commands"
     BUILD_JOBS_AND_COMMANDS = "config:build:jobs-and-commands"
     APT_INVALID_PACKAGE_NAME_PREFIX = "config:apt:invalid-package-name-prefix"

readthedocs/config/notifications.py

@@ -29,7 +29,8 @@
         body=_(
             textwrap.dedent(
                 """
-            No default configuration file found at repository's root.
+            The required <code>readthedocs.yaml</code> configuration file was not found at repository's root.
+            Learn how to use this file in our <a href="https://docs.readthedocs.io/en/stable/config-file/index.html">configuration file tutorial</a>.
             """
             ).strip(),
         ),
@@ -66,8 +67,8 @@
             textwrap.dedent(
                 """
             The configuration key <code>python.system_packages</code> has been deprecated and removed.
-            Refer to https://blog.readthedocs.com/drop-support-system-packages/ to read more
-            about this change and how to upgrade your config file."
+            <a href="https://blog.readthedocs.com/drop-support-system-packages/">Read our blog post</a>
+            to learn more about this change and how to upgrade your configuration file."
             """
             ).strip(),
         ),
@@ -80,8 +81,8 @@
             textwrap.dedent(
                 """
             The configuration key <code>python.use_system_site_packages</code> has been deprecated and removed.
-            Refer to https://blog.readthedocs.com/drop-support-system-packages/ to read more
-            about this change and how to upgrade your config file."
+            <a href="https://blog.readthedocs.com/drop-support-system-packages/">Read our blog post</a>
+            to learn more about this change and how to upgrade your configuration file."
             """
             ).strip(),
         ),
@@ -99,29 +100,13 @@
         ),
         type=ERROR,
     ),
-    Message(
-        id=ConfigError.GENERIC_INVALID_CONFIG_KEY,
-        header=_("Invalid configuration option"),
-        body=_(
-            textwrap.dedent(
-                """
-            Invalid configuration option: <code>{{key}}</code>.
-
-            Read the Docs configuration file: <code>{{source_file}}</code>.
-
-            <code>{{error_message}}</code>
-            """
-            ).strip(),
-        ),
-        type=ERROR,
-    ),
     Message(
         id=ConfigError.NOT_BUILD_TOOLS_OR_COMMANDS,
-        header=_("Invalid configuration option: <code>build</code>"),
+        header=_("Missing configuration option"),
         body=_(
             textwrap.dedent(
                 """
-            At least one item should be provided in "tools" or "commands".
+            At least one of the following configuration options is required: <code>build.tools</code> or <code>build.commands</code>.
             """
             ).strip(),
         ),
@@ -169,19 +154,21 @@
         body=_(
             textwrap.dedent(
                 """
-            You need to install your project with pip to use <code>extra_requirements</code>.
+            You need to install your project with <code>python.install.method: pip</code>
+            to use <code>python.install.extra_requirements</code>.
             """
             ).strip(),
         ),
         type=ERROR,
     ),
     Message(
         id=ConfigError.PIP_PATH_OR_REQUIREMENT_REQUIRED,
-        header=_("Invalid configuration key"),
+        header=_("Missing configuration key"),
         body=_(
             textwrap.dedent(
                 """
-            <code>path</code> or <code>requirements</code> key is required for <code>python.install</code>.
+                When using <code>python.install</code>,
+                one of the following keys are required: <code>python.install.path</code> or <code>python.install.requirements</code>.
             """
             ).strip(),
         ),
@@ -205,7 +192,7 @@
         body=_(
             textwrap.dedent(
                 """
-            You can not have <code>exclude</code> and <code>include</code> submodules at the same time.
+            You can not have <code>submodules.exclude</code> and <code>submodules.include</code> at the same time.
             """
             ).strip(),
         ),
@@ -230,6 +217,7 @@
             textwrap.dedent(
                 """
             Error while parsing <code>{{filename}}</code>.
+            Make sure your configuration file doesn't have any errors.
 
             {{error_message}}
             """
@@ -261,7 +249,8 @@
             textwrap.dedent(
                 """
             Config validation error in <code>{{key}}</code>.
-            Expected one of (0, 1, true, false), got <code>{{value}}</code>.
+            Expected one of <code>[0, 1, true, false]</code>, got type <code>{{value|to_class_name}}</code> (<code>{{value}}</code>).
+            Make sure the type of the value is not a string.
             """
             ).strip(),
         ),
@@ -274,7 +263,9 @@
             textwrap.dedent(
                 """
             Config validation error in <code>{{key}}</code>.
-            Expected one of ({{choices}}), got <code>{{value}}</code>.
+            Expected one of ({{choices}}), got type <code>{{value|to_class_name}}</code> (<code>{{value}}</code>).
+            Double check the type of the value.
+            A string may be required (e.g. <code>"3.10"</code> insted of <code>3.10</code>)
             """
             ).strip(),
         ),
@@ -287,7 +278,7 @@
             textwrap.dedent(
                 """
             Config validation error in <code>{{key}}</code>.
-            Expected a dictionary, got <code>{{value}}</code>.
+            Expected a dictionary, got type <code>{{value|to_class_name}}</code> (<code>{{value}}</code>).
             """
             ).strip(),
         ),
@@ -326,7 +317,7 @@
             textwrap.dedent(
                 """
             Config validation error in <code>{{key}}</code>.
-            Expected a string, got <code>{{value}}</code>.
+            Expected a string, got type <code>{{value|to_class_name}}</code> (<code>{{value}}</code>).
             """
             ).strip(),
         ),
@@ -339,7 +330,7 @@
             textwrap.dedent(
                 """
             Config validation error in <code>{{key}}</code>.
-            Expected a list, got <code>{{value}}</code>.
+            Expected a list, got type <code>{{value|to_class_name}}</code> (<code>{{value}}</code>).
             """
             ).strip(),
         ),

readthedocs/doc_builder/backends/mkdocs.py

@@ -168,9 +168,10 @@ def append_conf(self):
                 value = []
             if not isinstance(value, list):
                 raise MkDocsYAMLParseError(
-                    MkDocsYAMLParseError.INVALID_EXTRA_CONFIG.format(
-                        config=config,
-                    ),
+                    message_id=MkDocsYAMLParseError.INVALID_EXTRA_CONFIG,
+                    format_values={
+                        "extra_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])

readthedocs/doc_builder/backends/sphinx.py

@@ -258,7 +258,10 @@ def append_conf(self):
 
         if not os.path.exists(self.config_file):
             raise UserFileNotFound(
-                UserFileNotFound.FILE_NOT_FOUND.format(self.config_file)
+                message_id=UserFileNotFound.FILE_NOT_FOUND,
+                format_values={
+                    "filename": os.path.relpath(self.config_file, self.project_path),
+                },
             )
 
         # Allow symlinks, but only the ones that resolve inside the base directory.

readthedocs/doc_builder/exceptions.py

@@ -35,7 +35,6 @@ class BuildAppError(BuildBaseException):
 class BuildUserError(BuildBaseException):
     GENERIC = "build:user:generic"
     SKIPPED_EXIT_CODE_183 = "build:user:exit-code-183"
-    MAX_CONCURRENCY = "build:user:max-concurrency"
 
     BUILD_COMMANDS_WITHOUT_OUTPUT = "build:user:output:no-html"
     BUILD_OUTPUT_IS_NOT_A_DIRECTORY = "build:user:output:is-no-a-directory"

readthedocs/doc_builder/python_environments.py

@@ -291,9 +291,10 @@ def _append_core_requirements(self):
             )
             if not inputfile:
                 raise UserFileNotFound(
-                    UserFileNotFound.FILE_NOT_FOUND.format(
-                        self.config.conda.environment
-                    )
+                    message_id=UserFileNotFound.FILE_NOT_FOUND,
+                    format_values={
+                        "filename": self.config.conda.environment,
+                    },
                 )
             environment = parse_yaml(inputfile)
         except IOError:
@@ -334,9 +335,10 @@ def _append_core_requirements(self):
                 )
                 if not outputfile:
                     raise UserFileNotFound(
-                        UserFileNotFound.FILE_NOT_FOUND.format(
-                            self.config.conda.environment
-                        )
+                        message_id=UserFileNotFound.FILE_NOT_FOUND,
+                        format_values={
+                            "filename": self.config.conda.environment,
+                        },
                     )
                 yaml.safe_dump(environment, outputfile)
             except IOError: