Autodoc typehints (#350)

* Add autodoc typehints module

* Remove doc typehints in favour of signature

* Remove numpydoc comment

Author: oerc0122

docs/source/conf.py

@@ -24,16 +24,21 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
-    "numpydoc",
     "sphinx.ext.autodoc",
     "sphinx.ext.intersphinx",
+    "sphinx.ext.napoleon",
     "sphinx.ext.mathjax",
     "sphinx.ext.viewcode",
     "sphinxcontrib.contentui",
     "sphinx_copybutton",
+    "sphinx_autodoc_typehints",
 ]
 
-numpydoc_validation_checks = {"all", "EX01", "SA01", "ES01"}
+always_use_bars_union = True
+napoleon_include_special_with_doc = True
+napoleon_use_param = True
+
+numpydoc_validation_checks = {"all", "EX01", "SA01", "ES01", "PR04"}
 numpydoc_validation_exclude = {
     r"\.__weakref__$",
     r"\.__repr__$",
@@ -190,6 +195,7 @@
 
 # Warnings to ignore when using the -n (nitpicky) option
 # We should ignore any python built-in exception, for instance
+nitpicky = True
 nitpick_ignore = [
     ("py:class", "Logger"),
     ("py:class", "numpy.float64"),

janus_core/calculations/base.py

@@ -39,43 +39,43 @@ class BaseCalculation(FileNameMixin):
 
     Parameters
     ----------
-    calc_name : str
+    calc_name
         Name of calculation being run, used for name of logger. Default is "base".
-    struct : MaybeSequence[Atoms] | None
+    struct
         ASE Atoms structure(s) to simulate. Required if `struct_path` is None.
         Default is None.
-    struct_path : PathLike | None
+    struct_path
         Path of structure to simulate. Required if `struct` is None.
         Default is None.
-    arch : Architectures
+    arch
         MLIP architecture to use for calculations. Default is "mace_mp".
-    device : Devices
+    device
         Device to run model on. Default is "cpu".
-    model_path : PathLike | None
+    model_path
         Path to MLIP model. Default is `None`.
-    read_kwargs : ASEReadArgs
+    read_kwargs
         Keyword arguments to pass to ase.io.read. Default is {}.
-    sequence_allowed : bool
+    sequence_allowed
         Whether a sequence of Atoms objects is allowed. Default is True.
-    calc_kwargs : dict[str, Any] | None
+    calc_kwargs
         Keyword arguments to pass to the selected calculator. Default is {}.
-    set_calc : bool | None
+    set_calc
         Whether to set (new) calculators for structures. Default is None.
-    attach_logger : bool | None
+    attach_logger
         Whether to attach a logger. Default is True if "filename" is passed in
         log_kwargs, else False.
-    log_kwargs : dict[str, Any] | None
+    log_kwargs
             Keyword arguments to pass to `config_logger`. Default is {}.
-    track_carbon : bool | None
+    track_carbon
         Whether to track carbon emissions of calculation. Requires attach_logger.
         Default is True if attach_logger is True, else False.
-    tracker_kwargs : dict[str, Any] | None
+    tracker_kwargs
             Keyword arguments to pass to `config_tracker`. Default is {}.
-    file_prefix : PathLike | None
+    file_prefix
         Prefix for output filenames. Default is None.
-    additional_prefix : str | None
+    additional_prefix
         Component to add to default file_prefix (joined by hyphens). Default is None.
-    param_prefix : str | None
+    param_prefix
         Additional parameters to add to default file_prefix. Default is None.
 
     Attributes
@@ -112,44 +112,44 @@ def __init__(
 
         Parameters
         ----------
-        calc_name : str
+        calc_name
             Name of calculation being run, used for name of logger. Default is "base".
-        struct : MaybeSequence[Atoms] | None
+        struct
             ASE Atoms structure(s) to simulate. Required if `struct_path` is None.
             Default is None.
-        struct_path : PathLike | None
+        struct_path
             Path of structure to simulate. Required if `struct` is None. Default is
             None.
-        arch : Architectures
+        arch
             MLIP architecture to use for calculations. Default is "mace_mp".
-        device : Devices
+        device
             Device to run MLIP model on. Default is "cpu".
-        model_path : PathLike | None
+        model_path
             Path to MLIP model. Default is `None`.
-        read_kwargs : ASEReadArgs | None
+        read_kwargs
             Keyword arguments to pass to ase.io.read. Default is {}.
-        sequence_allowed : bool
+        sequence_allowed
             Whether a sequence of Atoms objects is allowed. Default is True.
-        calc_kwargs : dict[str, Any] | None
+        calc_kwargs
             Keyword arguments to pass to the selected calculator. Default is {}.
-        set_calc : bool | None
+        set_calc
             Whether to set (new) calculators for structures. Default is None.
-        attach_logger : bool | None
+        attach_logger
             Whether to attach a logger. Default is True if "filename" is passed in
             log_kwargs, else False.
-        log_kwargs : dict[str, Any] | None
+        log_kwargs
             Keyword arguments to pass to `config_logger`. Default is {}.
-        track_carbon : bool | None
+        track_carbon
             Whether to track carbon emissions of calculation. Requires attach_logger.
             Default is True if attach_logger is True, else False.
-        tracker_kwargs : dict[str, Any] | None
+        tracker_kwargs
             Keyword arguments to pass to `config_tracker`. Default is {}.
-        file_prefix : PathLike | None
+        file_prefix
             Prefix for output filenames. Default is None.
-        additional_prefix : str | None
+        additional_prefix
             Component to add to default file_prefix (joined by hyphens). Default is
             None.
-        param_prefix : str | None
+        param_prefix
             Additional parameters to add to default file_prefix. Default is None.
         """
         read_kwargs, calc_kwargs, log_kwargs, tracker_kwargs = none_to_dict(
@@ -232,7 +232,7 @@ def _set_info_units(
 
         Parameters
         ----------
-        keys : Sequence
+        keys
             Keys for which to add units to structure info. Default is
             ("energy", "forces", "stress").
         """

janus_core/calculations/descriptors.py

@@ -28,44 +28,44 @@ class Descriptors(BaseCalculation):
 
     Parameters
     ----------
-    struct : MaybeSequence[Atoms] | None
+    struct
         ASE Atoms structure(s) to calculate descriptors for. Required if `struct_path`
         is None. Default is None.
-    struct_path : PathLike | None
+    struct_path
         Path of structure to calculate descriptors for. Required if `struct` is None.
         Default is None.
-    arch : Architectures
+    arch
         MLIP architecture to use for calculations. Default is "mace_mp".
-    device : Devices
+    device
         Device to run MLIP model on. Default is "cpu".
-    model_path : PathLike | None
+    model_path
         Path to MLIP model. Default is `None`.
-    read_kwargs : ASEReadArgs | None
+    read_kwargs
         Keyword arguments to pass to ase.io.read. By default,
         read_kwargs["index"] is -1.
-    calc_kwargs : dict[str, Any] | None
+    calc_kwargs
         Keyword arguments to pass to the selected calculator. Default is {}.
-    set_calc : bool | None
+    set_calc
         Whether to set (new) calculators for structures. Default is None.
-    attach_logger : bool | None
+    attach_logger
         Whether to attach a logger. Default is True if "filename" is passed in
         log_kwargs, else False.
-    log_kwargs : dict[str, Any] | None
+    log_kwargs
         Keyword arguments to pass to `config_logger`. Default is {}.
-    track_carbon : bool | None
+    track_carbon
         Whether to track carbon emissions of calculation. Default is True if
         attach_logger is True, else False.
-    tracker_kwargs : dict[str, Any] | None
+    tracker_kwargs
         Keyword arguments to pass to `config_tracker`. Default is {}.
-    invariants_only : bool
+    invariants_only
         Whether only the invariant descriptors should be returned. Default is True.
-    calc_per_element : bool
+    calc_per_element
         Whether to calculate mean descriptors for each element. Default is False.
-    calc_per_atom : bool
+    calc_per_atom
         Whether to calculate descriptors for each atom. Default is False.
-    write_results : bool
+    write_results
         True to write out structure with results of calculations. Default is False.
-    write_kwargs : ASEWriteArgs | None
+    write_kwargs
         Keyword arguments to pass to ase.io.write if saving structure with
         results of calculations. Default is {}.
 
@@ -100,44 +100,44 @@ def __init__(
 
         Parameters
         ----------
-        struct : MaybeSequence[Atoms] | None
+        struct
             ASE Atoms structure(s) to calculate descriptors for. Required if
             `struct_path` is None. Default is None.
-        struct_path : PathLike | None
+        struct_path
             Path of structure to calculate descriptors for. Required if `struct` is
             None. Default is None.
-        arch : Architectures
+        arch
             MLIP architecture to use for calculations. Default is "mace_mp".
-        device : Devices
+        device
             Device to run MLIP model on. Default is "cpu".
-        model_path : PathLike | None
+        model_path
             Path to MLIP model. Default is `None`.
-        read_kwargs : ASEReadArgs | None
+        read_kwargs
             Keyword arguments to pass to ase.io.read. By default,
             read_kwargs["index"] is -1.
-        calc_kwargs : dict[str, Any] | None
+        calc_kwargs
             Keyword arguments to pass to the selected calculator. Default is {}.
-        set_calc : bool | None
+        set_calc
             Whether to set (new) calculators for structures. Default is None.
-        attach_logger : bool | None
+        attach_logger
             Whether to attach a logger. Default is True if "filename" is passed in
             log_kwargs, else False.
-        log_kwargs : dict[str, Any] | None
+        log_kwargs
             Keyword arguments to pass to `config_logger`. Default is {}.
-        track_carbon : bool | None
+        track_carbon
             Whether to track carbon emissions of calculation. Requires attach_logger.
             Default is True if attach_logger is True, else False.
-        tracker_kwargs : dict[str, Any] | None
+        tracker_kwargs
             Keyword arguments to pass to `config_tracker`. Default is {}.
-        invariants_only : bool
+        invariants_only
             Whether only the invariant descriptors should be returned. Default is True.
-        calc_per_element : bool
+        calc_per_element
             Whether to calculate mean descriptors for each element. Default is False.
-        calc_per_atom : bool
+        calc_per_atom
             Whether to calculate descriptors for each atom. Default is False.
-        write_results : bool
+        write_results
             True to write out structure with results of calculations. Default is False.
-        write_kwargs : ASEWriteArgs | None
+        write_kwargs
             Keyword arguments to pass to ase.io.write if saving structure with
             results of calculations. Default is {}.
         """
@@ -229,7 +229,7 @@ def _calc_descriptors(self, struct: Atoms) -> None:
 
         Parameters
         ----------
-        struct : Atoms
+        struct
             Structure to calculate descriptors for.
         """
         if "arch" in struct.calc.parameters: