feat: parse docstrings in the epydoc format (#82)

Closes #16.
Closes #17.

### Summary of Changes

* Parse docstrings in the `epydoc` format
* Add a flag to the CLI to choose the docstring format (supports the
settings `plaintext`, `numpy` and `epydoc` at the moment)
* Refactor the parser for `Numpydoc` to use the `docstring_parser`

.github/linters/.ruff.toml

@@ -37,7 +37,6 @@ select = [
     "INT",
     "ARG",
     "PTH",
-    "ERA",
     "PGH",
     "PL",
     "TRY",

pyproject.toml

@@ -20,9 +20,9 @@ python = "^3.10,<3.12"
 astroid = "^2.14.2"
 black = "^23.1.0"
 levenshtein = "^0.20.9"
-numpydoc = "^1.5"
 scipy = "^1.10.1"
 spacy = "^3.5.1"
+docstring-parser = "^0.15"
 
 [tool.poetry.group.dev.dependencies]
 pytest = "^7.2.1"

src/library_analyzer/cli/_cli.py

@@ -10,6 +10,7 @@
 from library_analyzer.cli._run_api import _run_api_command
 from library_analyzer.cli._run_migrate import _run_migrate_command
 from library_analyzer.cli._run_usages import _run_usages_command
+from library_analyzer.processing.api.docstring_parsing import DocstringStyle
 
 _API_COMMAND = "api"
 _USAGES_COMMAND = "usages"
@@ -24,7 +25,7 @@ def cli() -> None:
         logging.basicConfig(level=logging.INFO)
 
     if args.command == _API_COMMAND:
-        _run_api_command(args.package, args.src, args.out)
+        _run_api_command(args.package, args.src, args.out, args.docstyle)
     elif args.command == _USAGES_COMMAND:
         _run_usages_command(args.package, args.client, args.out, args.processes, args.batchsize)
     elif args.command == _ANNOTATIONS_COMMAND:
@@ -35,6 +36,7 @@ def cli() -> None:
             args.src,
             args.client,
             args.out,
+            args.docstyle,
             args.processes,
             args.batchsize,
         )
@@ -76,6 +78,14 @@ def _add_api_subparser(subparsers: _SubParsersAction) -> None:
         default=None,
     )
     api_parser.add_argument("-o", "--out", help="Output directory.", type=Path, required=True)
+    api_parser.add_argument(
+        "--docstyle",
+        help="The docstring style.",
+        type=DocstringStyle.from_string,
+        choices=list(DocstringStyle),
+        required=False,
+        default=DocstringStyle.PLAINTEXT.name,
+    )
 
 
 def _add_usages_subparser(subparsers: _SubParsersAction) -> None:
@@ -159,6 +169,14 @@ def _add_all_subparser(subparsers: _SubParsersAction) -> None:
         required=True,
     )
     all_parser.add_argument("-o", "--out", help="Output directory.", type=Path, required=True)
+    all_parser.add_argument(
+        "--docstyle",
+        help="The docstring style.",
+        type=DocstringStyle.from_string,
+        choices=list(DocstringStyle),
+        required=False,
+        default=DocstringStyle.PLAINTEXT.name,
+    )
     all_parser.add_argument(
         "--processes",
         help="How many processes should be spawned during processing.",

src/library_analyzer/cli/_run_all.py

@@ -7,19 +7,21 @@
 from library_analyzer.cli._run_api import _run_api_command
 from library_analyzer.cli._run_usages import _run_usages_command
 from library_analyzer.cli._shared_constants import _API_KEY, _USAGES_KEY
+from library_analyzer.processing.api.docstring_parsing import DocstringStyle
 
 
 def _run_all_command(
     package: str,
     src_dir_path: Path,
     client_dir_path: Path,
     out_dir_path: Path,
+    docstring_style: DocstringStyle,
     n_processes: int,
     batch_size: int,
 ) -> None:
     out_file_annotations = out_dir_path.joinpath("annotations.json")
     results = _run_in_parallel(
-        partial(_run_api_command, package, src_dir_path, out_dir_path),
+        partial(_run_api_command, package, src_dir_path, out_dir_path, docstring_style),
         partial(
             _run_usages_command,
             package,

src/library_analyzer/cli/_run_api.py

@@ -1,6 +1,7 @@
 from pathlib import Path
 
 from library_analyzer.processing.api import get_api
+from library_analyzer.processing.api.docstring_parsing import DocstringStyle
 from library_analyzer.processing.dependencies import get_dependencies
 
 from ._read_and_write_file import _write_api_dependency_file, _write_api_file
@@ -11,9 +12,10 @@ def _run_api_command(
     package: str,
     src_dir_path: Path,
     out_dir_path: Path,
+    docstring_style: DocstringStyle,
     result_dict: dict | None = None,
 ) -> None:
-    api = get_api(package, src_dir_path)
+    api = get_api(package, src_dir_path, docstring_style)
     api_dependencies = get_dependencies(api)
 
     api_file_path = _write_api_file(api, out_dir_path)