Documentation improvements for validation and XmlCheck

Author: nigelmegitt

docs/source/conf.py

@@ -51,11 +51,17 @@
 autosummary_generate = True
 todo_include_todos = True
 
+autodoc_default_options = {
+    # 'no-index-entry': ['src'],
+}
+
 language = 'en'
 # master_doc = 'docs/index'
 pygments_style = 'sphinx'
 source_suffix = '.rst'
 
+napoleon_google_docstring = True
+
 # -- Options for HTML output ----------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 

docs/source/validationLogging.rst

@@ -25,4 +25,12 @@ appropriate check codes, for example the
 :py:class:`XmlPassChecker<src.validationLogging.validationSummariser.XmlPassChecker>` has a ``_check_codes``
 list that contains all the appropriate ``ValidationCode`` values
 for which check failures would indicate that the input is not
-valid XML.
+valid XML, whereas the
+:py:class:`TtmlPassChecker<src.validationLogging.validationSummariser.TtmlPassChecker>` has TTML-specific check failures.
+
+Typically a :py:class:`ConstraintSet<src.constraintSets.constraintSet.ConstraintSet>`
+would check each appropriate ``ValidationPassChecker`` that is
+relevant for its purpose, in its static
+:py:meth:`summarise<src.constraintSets.constraintSet.ConstraintSet.summarise>` method, so that the results can be used to establish
+where the error lies, for example the input document might be valid
+XML but contain TTML errors.

docs/source/xmlChecks.rst

@@ -1,3 +1,27 @@
 XML (post-parsing) Checks
 =========================
 
+Assuming that parsing is successful, the validator creates an ``ElementTree``
+object that represents the parsed XML document. It then iterates through the
+list of :py:class:`XMLChecks<src.xmlChecks.xmlCheck.XmlCheck>`
+supplied by the selected
+:py:class:`ConstraintSet<src.constraintSets.constraintSet.ConstraintSet>`.
+
+Each of these ``XMLCheck`` objects must be a derived class that implements
+the :py:meth:`run<src.xmlChecks.xmlCheck.XmlCheck.run>` method,
+stores any validation results and returns a boolean,
+``True`` if the check passes, ``False`` otherwise.
+
+``XMLCheck`` objects are _not_ supposed to modify the ``input``.
+It may be that information can be derived during a check that is needed
+for a later check. This can be stored in the ``context`` dictionary.
+There is currently no dependency modelling to deal with checks that are
+dependent on other checks having already run; in that scenario the check
+should be written to proceed in some safe way, for example exiting
+without completing the check and logging a :py:obj:`SKIP<src.validationLogging.validationResult.SKIP>`
+:py:class:`ValidationResult<src.validationLogging.validationResult.ValidationResult>`.
+
+There are a large number of checks, some of which traverse the element tree,
+others that just check for a simple individual thing. Each derived
+class should document itself. They live in the
+:py:mod:`xmlChecks<src.xmlChecks>` module.

src/validationLogging/validationResult.py

@@ -2,10 +2,15 @@
 from .validationCodes import ValidationCode
 
 GOOD = 0
+"""Validation status code for a passed check, content is valid"""
 INFO = 1
+"""Validation status code for information generated by a check"""
 WARN = 2
+"""Validation status code for a warning generated by a check"""
 ERROR = 3
+"""Validation status code for a failed check, content is invalid"""
 SKIP = 4
+"""Validation status code for skipped check"""
 
 StatusStrings = {
     GOOD: 'Success',
@@ -14,6 +19,9 @@
     ERROR: 'Error',
     SKIP: 'Skip',
 }
+"""
+Map of Validation status codes to human readable strings
+"""
 
 
 @dataclass

src/validationLogging/validationSummariser.py

@@ -4,7 +4,7 @@
 
 
 class ValidationPassChecker():
-    _check_codes = []
+    _check_codes: list[ValidationCode] = []
 
     @classmethod
     def failuresAndWarningsAndSkips(
@@ -29,7 +29,7 @@ def failuresAndWarningsAndSkips(
 
 
 class XmlPassChecker(ValidationPassChecker):
-    _check_codes = [
+    _check_codes: list[ValidationCode] = [
         ValidationCode.preParse_nullBytes,
         ValidationCode.preParse_encoding,
         ValidationCode.preParse_byteOrderMark,
@@ -41,7 +41,7 @@ class XmlPassChecker(ValidationPassChecker):
 
 
 class TtmlPassChecker(ValidationPassChecker):
-    _check_codes = [
+    _check_codes: list[ValidationCode] = [
         ValidationCode.xml_root_element,
         ValidationCode.xml_tt_namespace,
         ValidationCode.ttml_idref_element_applicability,
@@ -67,7 +67,7 @@ class TtmlPassChecker(ValidationPassChecker):
 
 
 class DaptPassChecker(ValidationPassChecker):
-    _check_codes = [
+    _check_codes: list[ValidationCode] = [
         ValidationCode.xml_xsd,
         ValidationCode.xml_encoding_decl,
         ValidationCode.xml_entity_decl,
@@ -97,7 +97,7 @@ class DaptPassChecker(ValidationPassChecker):
 
 
 class EbuttdPassChecker(ValidationPassChecker):
-    _check_codes = [
+    _check_codes: list[ValidationCode] = [
         ValidationCode.xml_xsd,
         ValidationCode.ttml_attribute_styling_attribute,
         ValidationCode.ebuttd_parameter_timeBase,
@@ -123,7 +123,7 @@ class EbuttdPassChecker(ValidationPassChecker):
 
 
 class BbcPassChecker(ValidationPassChecker):
-    _check_codes = [
+    _check_codes: list[ValidationCode] = [
         ValidationCode.bbc_block_backgroundColor_constraint,
         ValidationCode.bbc_region_attributes_constraint,
         ValidationCode.bbc_region_backgroundColor_constraint,

src/xmlChecks/xmlCheck.py

@@ -9,4 +9,16 @@ def run(
             input: Element,
             context: dict,
             validation_results: ValidationLogger) -> bool:
+        """Runs the check.
+
+        Must be implemented in a derived class.
+
+        Args:
+            input: The parsed XML element to check
+            context: A context dictionary used across validation
+            validation_results: Object in which to store any validation results
+
+        Returns:
+            True if the input element passes the check, False otherwise 
+        """
         raise NotImplementedError()