Merge pull request #189 from machow/yaml-validation

[WIP] Yaml validation

Author: machow

quartodoc/autosummary.py

@@ -14,10 +14,12 @@
 from plum import dispatch  # noqa
 from pathlib import Path
 from types import ModuleType
+from pydantic import ValidationError
 
 from .inventory import create_inventory, convert_inventory
 from . import layout
 from .renderers import Renderer
+from .validation import fmt
 
 from typing import Any
 
@@ -446,7 +448,14 @@ def load_layout(self, sections: dict, package: str):
         # TODO: currently returning the list of sections, to make work with
         # previous code. We should make Layout a first-class citizen of the
         # process.
-        return layout.Layout(sections=sections, package=package)
+        try:
+            return layout.Layout(sections=sections, package=package)
+        except ValidationError as e:
+            msg = 'Configuration error for YAML:\n - '
+            errors = [fmt(err) for err in e.errors() if fmt(err)]
+            first_error = errors[0] # we only want to show one error at a time b/c it is confusing otherwise
+            msg += first_error           
+            raise ValueError(msg) from None
 
     # building ----------------------------------------------------------------
 

quartodoc/tests/test_validation.py

@@ -0,0 +1,65 @@
+import pytest, copy
+from quartodoc.autosummary import Builder
+
+EXAMPLE_SECTIONS = [
+                  {'title':  'Preperation Functions',
+                   'desc': 'Functions that fetch objects.\nThey prepare a representation of the site.\n', 
+                   'contents': ['Auto', 'blueprint', 'collect', 'get_object', 'preview']}, 
+                  {'title': 'Docstring Renderers', 
+                   'desc': 'Renderers convert parsed docstrings into a target format, like markdown.\n', 
+                   'contents': [{'name': 'MdRenderer', 'children': 'linked'}, 
+                                {'name': 'MdRenderer.render', 'dynamic': True}, 
+                                {'name': 'MdRenderer.render_annotation', 'dynamic': True}, 
+                                {'name': 'MdRenderer.render_header', 'dynamic': True}]
+                    }, 
+                    {'title': 'API Builders', 
+                     'desc': 'Builders build documentation. They tie all the pieces\nof quartodoc together.\n', 
+                     'contents': [{'kind': 'auto', 'name': 'Builder', 'members': []}, 
+                                   'Builder.from_quarto_config', 'Builder.build', 'Builder.write_index']
+                    },
+                ]
+
+@pytest.fixture
+def sections():
+    return copy.deepcopy(EXAMPLE_SECTIONS)
+
+def check_ValueError(sections):
+    "Check that a ValueError is raised when creating a `Builder` instance. Return the error message as a string."
+    with pytest.raises(ValueError) as e:
+        Builder(sections=sections, package='quartodoc')
+    return str(e.value)
+
+def test_valid_yaml(sections):
+    "Test that valid YAML passes validation"
+    Builder(sections=sections, package='quartodoc')
+
+def test_missing_title(sections):
+    "Test that missing title raises an error"
+    del sections[0]['title']
+    msg = check_ValueError(sections)
+    assert '- Missing field `title` for element 0 in the list for `sections`' in msg
+
+def test_missing_desc(sections):
+    "Test that a missing description raises an error"
+    sections = copy.deepcopy(EXAMPLE_SECTIONS)
+    del sections[2]['desc']
+    msg = check_ValueError(sections)
+    assert '- Missing field `desc` for element 2 in the list for `sections`' in msg
+
+def test_missing_name_contents_1(sections):
+    "Test that a missing name in contents raises an error"
+    del sections[2]['contents'][0]['name']
+    msg = check_ValueError(sections)
+    assert '- Missing field `name` for element 0 in the list for `contents` located in element 2 in the list for `sections`' in msg
+
+def test_missing_name_contents_2(sections):
+    "Test that a missing name in contents raises an error in a different section."
+    del sections[1]['contents'][0]['name']
+    msg = check_ValueError(sections)
+    assert '- Missing field `name` for element 0 in the list for `contents` located in element 1 in the list for `sections`' in msg
+
+def test_misplaced_kindpage(sections):
+    "Test that a misplaced kind: page raises an error"
+    sections[0]['kind'] = 'page'
+    msg = check_ValueError(sections)
+    assert ' - Missing field `path` for element 0 in the list for `sections`, which you need when setting `kind: page`.' in msg

quartodoc/validation.py

@@ -0,0 +1,27 @@
+
+def fmt(err:dict):
+    "format error messages from pydantic."
+    msg = ""
+    if err['msg'].startswith('Discriminator'):
+        return msg
+    if err['type'] == 'value_error.missing':
+        msg += 'Missing field'
+    else:
+        msg += err['msg'] + ':'
+        
+    if 'loc' in err:
+        if len(err['loc']) == 1:
+            msg += f" from root level: `{err['loc'][0]}`"
+        elif len(err['loc']) == 3:
+            msg += f" `{err['loc'][2]}` for element {err['loc'][1]} in the list for `{err['loc'][0]}`"
+        elif len(err['loc']) == 4 and err['loc'][2] == 'Page':
+            msg += f" `{err['loc'][3]}` for element {err['loc'][1]} in the list for `{err['loc'][0]}`, which you need when setting `kind: page`."
+        elif len(err['loc']) == 5:
+            msg += f" `{err['loc'][4]}` for element {err['loc'][3]} in the list for `{err['loc'][2]}` located in element {err['loc'][1]} in the list for `{err['loc'][0]}`"
+        elif len(err['loc']) == 6 and err['loc'][4] == 'Auto':
+            msg += f" `{err['loc'][5]}` for element {err['loc'][3]} in the list for `{err['loc'][2]}` located in element {err['loc'][1]} in the list for `{err['loc'][0]}`"
+        else:
+            return str(err) # so we can debug and include more cases
+    else:
+        msg += str(err)
+    return msg