From e6eb1e7bbfcc883f76bdd2f899dce7037dbc96bb Mon Sep 17 00:00:00 2001 From: milde Date: Mon, 6 May 2024 12:41:07 +0000 Subject: [PATCH] Doctree validation: New configuration setting "validate". New parser configuration setting "validate". If True, the parser calls `document.validate()` in `finish_parse()`. Useful for testing/debugging purposes and with the upcoming "Docutils XML" parser. git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk@9690 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docutils/docs/user/config.txt | 22 ++++++++++++++++------ docutils/docutils/parsers/__init__.py | 9 +++++++++ docutils/test/data/help/docutils.txt | 2 ++ docutils/test/data/help/rst2html.txt | 2 ++ docutils/test/data/help/rst2latex.txt | 2 ++ 5 files changed, 31 insertions(+), 6 deletions(-) diff --git a/docutils/docs/user/config.txt b/docutils/docs/user/config.txt index 2eae932d3..0aabd80c6 100644 --- a/docutils/docs/user/config.txt +++ b/docutils/docs/user/config.txt @@ -635,7 +635,7 @@ An explicit URL for a "View document source" link, used verbatim. strict_visitor -------------- -When processing a document tree with the Visitor pattern, raise an +When processing a `document tree`_ with the Visitor pattern, raise an error if a writer does not support a node type listed as optional. For transitional development use. @@ -647,7 +647,7 @@ strip_classes ------------- List of "classes" attribute values (comma-separated_) that will be -removed from all elements in the document tree. +removed from all elements in the `document tree`_. Values are appended. [#append-values]_ Allows eliding class values that interfere with, e.g, CSS rules from 3rd @@ -662,7 +662,7 @@ party tools/frameworks. strip_comments -------------- -Enable or disable the removal of comment elements from the document tree. +Enable or disable the removal of comment elements from the `document tree`_. :Default: None (disabled). :Options: ``--strip-comments``, ``--leave-comments``. @@ -673,7 +673,7 @@ strip_elements_with_classes List of "classes" attribute values (comma-separated_). Values are appended. [#append-values]_ -Matching elements are removed from the document tree. +Matching elements are removed from the `document tree`_. .. WARNING:: Potentially dangerous: may lead to an invalid document tree and subsequent writer errors. Use with caution. @@ -723,8 +723,6 @@ caught and reported (in a user-friendly way) by Docutils. .. [#] unless Docutils is run programmatically using the `Publisher Interface`_ -.. _Publisher Interface: ../api/publisher.html - warning_stream -------------- @@ -776,6 +774,14 @@ file_insertion_enabled_ for another security-relevant setting. *Default*: True. *Options*: ``--raw-enabled``, ``--no-raw``. +validate +-------- + +Validate the parsing result. + +*Default*: False. *Options*: ``--validate``, ``--no-validation``. + + [restructuredtext parser] ------------------------- @@ -2410,9 +2416,13 @@ pep_template [pep_html writer] template .. References +.. _Document Tree: ../ref/doctree.html + .. _Docutils Runtime Settings: .. _runtime settings: ../api/runtime-settings.html +.. _Publisher Interface: ../api/publisher.html + .. RestructuredText Directives .. _"class" directive: ../ref/rst/directives.html#class .. _"code": ../ref/rst/directives.html#code diff --git a/docutils/docutils/parsers/__init__.py b/docutils/docutils/parsers/__init__.py index 1f61b3dd1..4052c2642 100644 --- a/docutils/docutils/parsers/__init__.py +++ b/docutils/docutils/parsers/__init__.py @@ -39,6 +39,13 @@ class Parser(Component): ['--line-length-limit'], {'metavar': '', 'type': 'int', 'default': 10000, 'validator': frontend.validate_nonnegative_int}), + ('Validate the document tree after parsing.', + ['--validate'], + {'action': 'store_true', + 'validator': frontend.validate_boolean}), + ('Do not validate the document tree. (default)', + ['--no-validation'], + {'action': 'store_false', 'dest': 'validate'}), ) ) component_type = 'parser' @@ -62,6 +69,8 @@ class Parser(Component): """Finalize parse details. Call at end of `self.parse()`.""" self.document.reporter.detach_observer( self.document.note_parse_message) + if self.document.settings.validate: + self.document.validate() _parser_aliases = { # short names for known parsers diff --git a/docutils/test/data/help/docutils.txt b/docutils/test/data/help/docutils.txt index 3cf41a5fa..ae0c1e451 100644 --- a/docutils/test/data/help/docutils.txt +++ b/docutils/test/data/help/docutils.txt @@ -99,6 +99,8 @@ Generic Parser Options --line-length-limit= Maximal number of characters in an input line. Default 10 000. +--validate Validate the document tree after parsing. +--no-validation Do not validate the document tree. (default) reStructuredText Parser Options ------------------------------- diff --git a/docutils/test/data/help/rst2html.txt b/docutils/test/data/help/rst2html.txt index ea383427a..cc4d17838 100644 --- a/docutils/test/data/help/rst2html.txt +++ b/docutils/test/data/help/rst2html.txt @@ -100,6 +100,8 @@ Generic Parser Options --line-length-limit= Maximal number of characters in an input line. Default 10 000. +--validate Validate the document tree after parsing. +--no-validation Do not validate the document tree. (default) reStructuredText Parser Options ------------------------------- diff --git a/docutils/test/data/help/rst2latex.txt b/docutils/test/data/help/rst2latex.txt index adf8551f9..482cc6c1a 100644 --- a/docutils/test/data/help/rst2latex.txt +++ b/docutils/test/data/help/rst2latex.txt @@ -100,6 +100,8 @@ Generic Parser Options --line-length-limit= Maximal number of characters in an input line. Default 10 000. +--validate Validate the document tree after parsing. +--no-validation Do not validate the document tree. (default) reStructuredText Parser Options ------------------------------- -- 2.11.4.GIT