Updates docs and adds linter

.github/workflows/test.yml

@@ -27,14 +27,17 @@ jobs:
           python-version: 3.13
 
       - name: Install linters
-        run: python -m pip install --upgrade pip black zizmor
+        run: python -m pip install --upgrade pip black zizmor pydoctor
 
       - name: Black
         run: black . --check
 
       - name: Zizmor
         run: find .github/workflows -name '*.yml' | xargs zizmor --config .github/zizmor.yml
 
+      - name: Pydoctor
+        run: pydoctor ./configargparse.py --intersphinx=https://docs.python.org/3/objects.inv --docformat=google -W
+
   test:
     name: ${{ matrix.os }} py${{ matrix.python-version }} ${{ matrix.use-docker && '(docker)' || '' }}
     runs-on: ${{ matrix.os }}

apidocs.sh

@@ -14,11 +14,8 @@ project_version="$(python3 setup.py -V)"
 
 # Figure commit ref
 git_sha="$(git rev-parse HEAD)"
-if ! git describe --exact-match --tags > /dev/null 2>&1 ; then
-    is_tag=false
-else
+if git describe --exact-match --tags > /dev/null 2>&1 ; then
     git_sha="$(git describe --exact-match --tags)"
-    is_tag=true
 fi
 
 # Init output folder
@@ -44,6 +41,6 @@ pydoctor \
     --project-base-dir=.\
     --docformat=google \
     --html-output="${docs_folder}" \
-    ./argparse.py ./configargparse.py || true 
+    ./argparse.py ./configargparse.py || true
 
-echo "API docs generated in ${docs_folder}"
+echo "API docs generated in ${docs_folder}"

configargparse.py

@@ -107,7 +107,7 @@ def parse(self, stream):
         one of: "yes", "no", "on", "off", "true", "false". Otherwise an error will be raised.
 
         Args:
-            stream (IO): A config file input stream (such as an open file object).
+            stream (io.IOBase): A config file input stream (such as an open file object).
 
         Returns:
             OrderedDict: Items where the keys are strings and the
@@ -421,7 +421,7 @@ def unquote_str(text, triple=True):
     It supports all kinds of python quotes: ``\"\"\"``, ``'''``, ``"`` and ``'``.
 
     :param triple: Also unquote tripple quoted strings.
-    @raises ValueError: If the string is detected as beeing quoted but literal_eval() fails to evaluate it as string.
+    :raises ValueError: If the string is detected as beeing quoted but literal_eval() fails to evaluate it as string.
         This would be a bug in the regex.
     """
     if is_quoted(text, triple=triple):
@@ -458,7 +458,7 @@ def parse_toml_section_name(section_name):
 
 def get_toml_section(data, section):
     """
-    Given some TOML data (as loaded with `toml.load()`), returns the requested section of the data.
+    Given some TOML data (as loaded with toml.load()), returns the requested section of the data.
     Returns ``None`` if the section is not found.
     """
     sections = parse_toml_section_name(section) if isinstance(section, str) else section
@@ -479,6 +479,7 @@ class TomlConfigParser(ConfigFileParser):
     Create a TOML parser bounded to the list of provided sections.
 
     Example::
+
         # this is a comment
         [tool.my-software] # TOML section table.
         # how to specify a key-value pair
@@ -489,7 +490,7 @@ class TomlConfigParser(ConfigFileParser):
         verbosity = 1
         # how to specify a list arg (eg. arg which has action="append")
         repeatable-option = ["https://docs.python.org/3/objects.inv",
-                       "https://twistedmatrix.com/documents/current/api/objects.inv"]
+                             "https://twistedmatrix.com/documents/current/api/objects.inv"]
         # how to specify a multiline text:
         multi-line-text = '''
             Lorem ipsum dolor sit amet, consectetur adipiscing elit.
@@ -500,7 +501,7 @@ class TomlConfigParser(ConfigFileParser):
     Note that the config file fragment above is also valid for the `IniConfigParser` class and would be parsed the same manner.
     Thought, any valid TOML config file will not be necessarly parsable with `IniConfigParser` (INI files must be rigorously indented whereas TOML files).
 
-    See the `TOML specification <>`_ for details.
+    See the `TOML specification <https://toml.io/en/>`_ for details.
     """
 
     def __init__(self, sections):
@@ -597,7 +598,7 @@ class IniConfigParser(ConfigFileParser):
     def __init__(self, sections, split_ml_text_to_list):
         """
         :param sections: The section names bounded to the new parser.
-        :split_ml_text_to_list: Wether to convert multiline strings to list
+        :param split_ml_text_to_list: Wether to convert multiline strings to list
         """
         super().__init__()
         self.sections = sections
@@ -673,10 +674,10 @@ def get_syntax_description(self):
 
 class CompositeConfigParser(ConfigFileParser):
     """
-    Createa a config parser composed by others `ConfigFileParser`s.
+    Create a config parser composed by other ConfigFileParser instances.
 
     The composite parser will successively try to parse the file with each parser,
-    until it succeeds, else raise execption with all encountered errors.
+    until it succeeds, else raise exception with all encountered errors.
     """
 
     def __init__(self, config_parser_types):
@@ -731,7 +732,7 @@ def __init__(self, *args, **kwargs):
         r"""Supports args of the `argparse.ArgumentParser` constructor
         as \*\*kwargs, as well as the following additional args.
 
-        Arguments:
+        Keyword Arguments:
             add_config_file_help: Whether to add a description of config file
                 syntax to the help message.
             add_env_var_help: Whether to add something to the help message for
@@ -1339,7 +1340,7 @@ def _open_config_files(self, command_line_args):
             command_line_args: List of all args
 
         Returns:
-            list[IO]: open config files
+            list[io.IOBase]: open config files
         """
         # open any default config files
         config_files = []
@@ -1525,7 +1526,7 @@ def add_argument(self, *args, **kwargs):
     This method supports the same args as ArgumentParser.add_argument(..)
     as well as the additional args below.
 
-    Arguments:
+    Keyword Arguments:
         env_var: If set, the value of this environment variable will override
             any config file or default values for this arg (but can itself
             be overridden on the commandline). Also, if auto_env_var_prefix is