Fixes and improvements to API docs (#832)

Author: mauvilsa

DOCUMENTATION.rst

@@ -91,7 +91,7 @@ Then in a shell you could run:
     >>> auto_cli(Main, args=["--max_prize=1000", "person", "Lucky"])  # doctest: +ELLIPSIS
     'Lucky won ...€!'
 
-If the given class does not have any methods, there will be no sub-commands and
+If the given class does not have any methods, there will be no subcommands and
 :func:`.auto_cli` will return an instance of the class. For example:
 
 .. testcode::
@@ -129,11 +129,11 @@ run via :ref:`sub-commands` similar to the single class example above, i.e.
 ``example.py function [arguments]`` where ``function`` is the name of the
 function to execute. If multiple classes or a mixture of functions and classes
 is given to :func:`.auto_cli`, to execute a method of a class, two levels of
-:ref:`sub-commands` are required. The first sub-command would be the name of the
+:ref:`sub-commands` are required. The first subcommand would be the name of the
 class and the second the name of the method, i.e. ``example.py class
 [init_arguments] method [arguments]``.
 
-Arbitrary levels of sub-commands with custom names can be defined by providing a
+Arbitrary levels of subcommands with custom names can be defined by providing a
 ``dict``. For example:
 
 .. testcode::
@@ -2560,7 +2560,7 @@ Experimental ``omegaconf+`` mode
 An experimental ``omegaconf+`` parser mode is available, which addresses the
 limitations of the ``omegaconf`` mode mentioned earlier. Instead of applying
 OmegaConf resolvers to each YAML config individually, the resolving is performed
-once at the end of the parsing process. As a result, in nested sub-configs,
+once at the end of the parsing process. As a result, in nested subconfigs,
 references to nodes must be either relative or parser-level absolute to function
 correctly. Alternatively, you can
 ``set_parsing_settings(omegaconf_absolute_to_relative_paths=True)`` to enable
@@ -2569,7 +2569,7 @@ that this automatic conversion does not work for every possible case.
 
 Based on community feedback, this mode may become the default ``omegaconf`` mode
 in version 5.0.0. This change would introduce a breaking modification, as
-absolute node references would no longer work in nested sub-configs.
+absolute node references would no longer work in nested subconfigs.
 
 
 .. _environment-variables:
@@ -2625,19 +2625,19 @@ variables.
 
 .. _sub-commands:
 
-Sub-commands
-============
+Subcommands
+===========
 
 A way to define parsers in a modular way is what in argparse is known as
-`sub-commands <https://docs.python.org/3/library/argparse.html#sub-commands>`__.
-However, to promote modularity, in jsonargparse sub-commands work a bit
-different than in argparse. To add sub-commands to a parser, the
+`subcommands <https://docs.python.org/3/library/argparse.html#subcommands>`__.
+However, to promote modularity, in jsonargparse subcommands work a bit
+different than in argparse. To add subcommands to a parser, the
 :py:meth:`.ArgumentParser.add_subcommands` method is used. Then an existing
-parser is added as a sub-command using :func:`.add_subcommand`. In a parsed
-config object the sub-command will be stored in the ``subcommand`` entry (or
-whatever ``dest`` was set to), and the values of the sub-command will be in an
-entry with the same name as the respective sub-command. An example of defining a
-parser with sub-commands is the following:
+parser is added as a subcommand using :func:`.add_subcommand`. In a parsed
+config object the subcommand will be stored in the ``subcommand`` entry (or
+whatever ``dest`` was set to), and the values of the subcommand will be in an
+entry with the same name as the respective subcommand. An example of defining a
+parser with subcommands is the following:
 
 .. testcode::
 
@@ -2680,29 +2680,29 @@ valid YAML would be:
 Parsing of environment variables works similar to :class:`.ActionParser`. For
 the example parser above, all environment variables for ``subcomm1`` would have
 as prefix ``APP_SUBCOMM1_`` and likewise for ``subcomm2`` as prefix
-``APP_SUBCOMM2_``. The sub-command to use could be chosen by setting environment
+``APP_SUBCOMM2_``. The subcommand to use could be chosen by setting environment
 variable ``APP_SUBCOMMAND``.
 
-It is possible to have multiple levels of sub-commands. With multiple levels
-there is one basic requirement: the sub-commands must be added in the order of
+It is possible to have multiple levels of subcommands. With multiple levels
+there is one basic requirement: the subcommands must be added in the order of
 the levels. This is, first call :func:`add_subcommands` and
 :func:`add_subcommand` for the first level. Only after do the same for the
 second level, and so on.
 
 
 .. _json-schemas:
 
-Json schemas
+JSON Schemas
 ============
 
 The :class:`.ActionJsonSchema` class is provided to allow parsing and validation
 of values using a JSON Schema. This class requires the `jsonschema
 <https://pypi.org/project/jsonschema/>`__ Python package. Though note that
-jsonschema is not a requirement of the minimal jsonargparse install. To enable
-this functionality install with the ``jsonschema`` extra as explained in section
-:ref:`installation`.
+``jsonschema`` is not a requirement of the minimal jsonargparse install. To
+enable this functionality install with the ``jsonschema`` extra as explained in
+section :ref:`installation`.
 
-Check out the `jsonschema documentation
+Check out the `JSON Schema documentation
 <https://python-jsonschema.readthedocs.io/>`__ to learn how to write a schema.
 The current version of jsonargparse uses Draft7Validator. Parsing an argument
 using a JSON Schema is done like in the following example:

jsonargparse/_actions.py

@@ -442,7 +442,7 @@ def __init__(self, message: str = "option unavailable", **kwargs):
         """Initializer for ActionFail instance.
 
         Args:
-            message: Text for the error to show. Use `%(option)s`/`%(value)s` to include the option and/or value.
+            message: Text for the error to show. Use ``%(option)s``/``%(value)s`` to include the option and/or value.
         """
         if len(kwargs) == 0:
             self._message = message
@@ -464,7 +464,7 @@ def __call__(self, *args, **kwargs):
 
 
 class ActionYesNo(Action):
-    """Paired options --[yes_prefix]opt, --[no_prefix]opt to set True or False respectively."""
+    """Paired options ``--[yes_prefix]opt``, ``--[no_prefix]opt`` to set ``True`` or ``False`` respectively."""
 
     def __init__(self, yes_prefix: str = "", no_prefix: str = "no_", **kwargs):
         """Initializer for ActionYesNo instance.
@@ -547,12 +547,12 @@ class ActionParser:
 
     def __init__(
         self,
-        parser: Optional[ArgumentParser] = None,
+        parser: ArgumentParser,
     ):
         """Initializer for ActionParser instance.
 
         Args:
-            parser (Optional[ArgumentParser]): A parser to parse the option with.
+            parser: A parser to parse the option with.
 
         Raises:
             ValueError: If the parser parameter is invalid.
@@ -643,7 +643,7 @@ def add_parser(self, name, **kwargs):
         raise NotImplementedError("In jsonargparse subcommands are added using the add_subcommand method.")
 
     def add_subcommand(self, name, parser, **kwargs):
-        """Adds a parser as a sub-command parser.
+        """Adds a parser as a subcommand parser.
 
         In contrast to `argparse.ArgumentParser.add_subparsers
         <https://docs.python.org/3/library/argparse.html#argparse.ArgumentParser.add_subparsers>`_
@@ -680,7 +680,7 @@ def add_subcommand(self, name, parser, **kwargs):
         return parser
 
     def __call__(self, parser, namespace, values, option_string=None):
-        """Adds sub-command dest and parses sub-command arguments."""
+        """Adds subcommand dest and parses subcommand arguments."""
         subcommand = values[0]
         arg_strings = values[1:]
 

jsonargparse/_cli.py

@@ -39,22 +39,22 @@ def auto_cli(
 ):
     """Simple creation of command line interfaces.
 
-    Previously CLI, renamed to follow the standard of functions in lowercase.
+    Previously called ``jsonargparse.CLI``, renamed to follow the standard of functions in lowercase.
 
     Creates an argument parser from one or more functions/classes, parses
     arguments and runs one of the functions or class methods depending on what
-    was parsed. If the 'components' parameter is not given, then the components
+    was parsed. If the ``components`` parameter is not given, then the components
     will be all the locals in the context and defined in the same module as from
-    where auto_cli is called.
+    where ``auto_cli`` is called.
 
     Args:
         components: One or more functions/classes to include in the command line interface.
-        args: List of arguments to parse or None to use sys.argv.
+        args: List of arguments to parse or ``None`` to use ``sys.argv``.
         config_help: Help string for config file option in help.
         set_defaults: Dictionary of values to override components defaults.
         as_positional: Whether to add required parameters as positional arguments.
         fail_untyped: Whether to raise exception if a required parameter does not have a type.
-        parser_class: The ArgumentParser class to use.
+        parser_class: The :class:`ArgumentParser` subclass to use.
         **kwargs: Used to instantiate :class:`.ArgumentParser`.
 
     Returns:
@@ -130,7 +130,7 @@ def auto_cli(
 
 
 def auto_parser(*args, **kwargs) -> ArgumentParser:
-    """Same as auto_cli, but returns the parser, so doesn't parse arguments or run.
+    """Same as :func:`.auto_cli`, but returns the parser, doesn't parse arguments or run.
 
     This is a shorthand for ``capture_parser(lambda: auto_cli(*args, **kwargs))``.
     """

jsonargparse/_common.py

@@ -120,25 +120,25 @@ def set_parsing_settings(
 
     Args:
         validate_defaults: Whether default values must be valid according to the
-            argument type. The default is False, meaning no default validation,
-            like in argparse.
+            argument type. The default is ``False``, meaning no default
+            validation, like in argparse.
         config_read_mode_urls_enabled: Whether to read config files from URLs
-            using requests package. Default is False.
+            using requests package. Default is ``False``.
         config_read_mode_fsspec_enabled: Whether to read config files from
-            fsspec supported file systems. Default is False.
+            fsspec supported file systems. Default is ``False``.
         docstring_parse_style: The docstring style to expect. Default is
-            DocstringStyle.AUTO.
+            ``DocstringStyle.AUTO``.
         docstring_parse_attribute_docstrings: Whether to parse attribute
-            docstrings (slower). Default is False.
-        parse_optionals_as_positionals: If True, the parser will take extra
+            docstrings (slower). Default is ``False``.
+        parse_optionals_as_positionals: If ``True``, the parser will take extra
             positional command line arguments as values for optional arguments.
-            This means that optional arguments can be given by name --key=value
-            as usual, but also as positional. The extra positionals are applied
-            to optionals in the order that they were added to the parser. By
-            default, this is False.
+            This means that optional arguments can be given by name
+            ``--key=value`` as usual, but also as positional. The extra
+            positionals are applied to optionals in the order that they were
+            added to the parser. By default, this is ``False``.
         stubs_resolver_allow_py_files: Whether the stubs resolver should search
             in ``.py`` files in addition to ``.pyi`` files.
-        omegaconf_absolute_to_relative_paths: If True, when loading configs
+        omegaconf_absolute_to_relative_paths: If ``True``, when loading configs
             with ``omegaconf+`` parser mode, absolute interpolation paths are
             converted to relative. This is only intended for backward
             compatibility with ``omegaconf`` parser mode.
@@ -433,7 +433,6 @@ class LoggerProperty:
     """Class designed to be inherited by other classes to add a logger property."""
 
     def __init__(self, *args, logger: Union[bool, str, dict, logging.Logger] = False, **kwargs):
-        """Initializer for LoggerProperty class."""
         self.logger = logger
         super().__init__(*args, **kwargs)