Small enhancements to external parsing API documentation (#1283)

doc/userguide/src/ExtendingRobotFramework/ParserInterface.rst

@@ -1,7 +1,7 @@
 Parser interface
 ================
 
-Robot Framework supports custom parsers that can handle custom data formats or
+Robot Framework supports external parsers that can handle custom data formats or
 even override Robot Framework's own parser.
 
 .. note:: Custom parsers are new in Robot Framework 6.1.
@@ -13,10 +13,10 @@ even override Robot Framework's own parser.
 Taking parsers into use
 -----------------------
 
-Parsers are taken into use from the command line using the :option:`--parser`
+Parsers are taken into use from the command line with the :option:`--parser`
 option using exactly the same semantics as with listeners__. This includes
-specifying a parser as a name or as a path, how arguments can be given to
-parser classes, and so on::
+specifying parsers as names or paths, giving arguments to parser classes, and
+so on::
 
     robot --parser MyParser tests.custom
     robot --parser path/to/MyParser.py tests.custom
@@ -37,7 +37,8 @@ This attribute specifies what file extension or extensions the parser supports.
 Both `EXTENSION` and `extension` names are accepted, and the former has precedence
 if both exist. That attribute can be either a string or a sequence of strings.
 Extensions are case-insensitive and can be specified with or without the leading
-dot.
+dot. If a parser is implemented as a class, it is possible to set this attribute
+either as a class attribute or as an instance attribute.
 
 If a parser supports the :file:`.robot` extension, it will be used for parsing
 these files instead of the standard parser.
@@ -62,7 +63,7 @@ accept two arguments. In that case the second argument is a TestDefaults_ object
 ~~~~~~~~~~~~~~~~~~~
 
 The optional `parse_init` method is responsible for parsing `suite initialization
-files`_ i.e. files in in format `__init__.ext` where `.ext` is an extension
+files`_ i.e. files in format `__init__.ext` where `.ext` is an extension
 supported by the parser. The method must return a `TestSuite <running.TestSuite_>`__
 object representing the whole directory. Suites created from child suite files
 and directories will be added to its child suites.
@@ -72,8 +73,7 @@ depending on is it interested in test related default values or not. If it
 accepts defaults, it can manipulate the passed TestDefaults_ object and changes
 are seen when parsing child suite files.
 
-This method is optional and only needed if a parser needs to support suite
-initialization files.
+This method is only needed if a parser needs to support suite initialization files.
 
 Optional base class
 ~~~~~~~~~~~~~~~~~~~
@@ -173,10 +173,10 @@ initialization files, uses TestDefaults_ and registers multiple extensions.
 Parser as preprocessor
 ~~~~~~~~~~~~~~~~~~~~~~
 
-The final parser acts as a preprocessor for Robot Framework data files that
-supports headers in format `=== Test Cases ===` in addition to
+The final example parser acts as a preprocessor for Robot Framework data files
+that supports headers in format `=== Test Cases ===` in addition to
 `*** Test Cases ***`. In this kind of usage it is convenient to use
-`TestSuite.from_string`__, `TestSuite.from_model`__ or
+`TestSuite.from_string`__, `TestSuite.from_model`__ and
 `TestSuite.from_file_system`__ factory methods for constructing the returned suite.
 
 .. sourcecode:: python

src/robot/api/interfaces.py

@@ -21,7 +21,9 @@
 - :class:`HybridLibrary` for libraries using the `hybrid library API`__.
 - :class:`ListenerV2` for `listener interface version 2`__.
 - :class:`ListenerV3` for `listener interface version 3`__.
-- :class:`Parser` for `custom parsers`__.
+- :class:`Parser` for `custom parsers`__. Also
+  :class:`~robot.running.builder.settings.TestDefaults` used in ``Parser``
+  type hints can be imported via this module if needed.
 - Type definitions used by the aforementioned classes.
 
 Main benefit of using these base classes is that editors can provide automatic
@@ -35,7 +37,7 @@
 .. note:: Using this module requires having the typing_extensions__ module
           installed when using Python 3.6 or 3.7.
 
-New in Robot Framework 6.1.
+This module is new in Robot Framework 6.1.
 
 __ http://robotframework.org/robotframework/latest/RobotFrameworkUserGuide.html#dynamic-library-api
 __ http://robotframework.org/robotframework/latest/RobotFrameworkUserGuide.html#hybrid-library-api
@@ -586,6 +588,21 @@ class Parser(ABC):
     attribute can also be named ``EXTENSION``, which typically works better
     when a parser is implemented as a module.
 
+    Example::
+
+        from pathlib import Path
+        from robot.api import TestSuite
+        from robot.api.interfaces import Parser, TestDefaults
+
+
+        class ExampleParser(Parser):
+            extension = '.example'
+
+            def parse(self, source: Path, defaults: TestDefaults) -> TestSuite:
+                suite = TestSuite(TestSuite.name_from_source(source), source=source)
+                # parse the source file and add tests to the created suite
+                return suite
+
     The support for custom parsers is new in Robot Framework 6.1.
     """
     extension: Union[str, Sequence[str]]

src/robot/running/__init__.py

@@ -27,13 +27,19 @@
   classmethod that uses it internally.
 
 * Classes used by :class:`~robot.running.model.TestSuite`, such as
-  :class:`~robot.running.model.TestCase` and :class:`~robot.running.model.Keyword`,
-  that are defined in the :mod:`robot.running.model` module.
+  :class:`~robot.running.model.TestCase`, :class:`~robot.running.model.Keyword`
+  and :class:`~robot.running.model.If` that are defined in the
+  :mod:`robot.running.model` module. These classes are typically only needed
+  in type hints.
+
+* :class:`~robot.running.builder.settings.TestDefaults` that is part of the
+  `external parsing API`__ and also typically needed only in type hints.
+
+__ http://robotframework.org/robotframework/latest/RobotFrameworkUserGuide.html#parser-interface
 
 :class:`~robot.running.model.TestSuite` and
-:class:`~robot.running.builder.builders.TestSuiteBuilder` can be imported via
-the :mod:`robot.api` package. If other classes are needed directly, they can be
-imported via :mod:`robot.running`.
+:class:`~robot.running.builder.builders.TestSuiteBuilder` can be imported also via
+the :mod:`robot.api` package.
 
 .. note:: Prior to Robot Framework 6.1, only some classes in
           :mod:`robot.running.model` were exposed via :mod:`robot.running`.

src/robot/running/builder/settings.py

@@ -47,7 +47,7 @@ class TestDefaults:
     This class is part of the `public parser API`__. When implementing ``parse``
     or ``parse_init`` method so that they accept two arguments, the second is
     an instance of this class. If the class is needed as a type hint, it can
-    be imported via ``robot.running` or `robot.api.interfaces``.
+    be imported via :mod:`robot.running` or :mod:`robot.api.interfaces`.
 
     __ http://robotframework.org/robotframework/latest/RobotFrameworkUserGuide.html#parser-interface
     """