Build documentation with the --nitpicky option

.github/workflows/sphinx.yaml

@@ -45,7 +45,7 @@ jobs:
       - name: Run sphinx
         run: |
           cd docs
-          python -m sphinx -M html . _build -W --keep-going --fresh-env
+          python -m sphinx -M html . _build -W --keep-going --fresh-env --nitpicky
       - name: Upload artifact
         uses: actions/upload-pages-artifact@v3
         with:

docs/Makefile

@@ -3,7 +3,7 @@
 
 # You can set these variables from the command line, and also
 # from the environment for the first two.
-SPHINXOPTS    ?=
+SPHINXOPTS    ?= -W --keep-going --nitpicky
 SPHINXBUILD   ?= sphinx-build
 SOURCEDIR     = .
 BUILDDIR      = _build

docs/conf.py

@@ -7,6 +7,7 @@
 import runpy
 import sys
 
+from intersphinx_registry import get_intersphinx_mapping
 from packaging.version import Version
 from sphinx.ext.apidoc import main as main_api_doc
 
@@ -38,6 +39,7 @@
 
 templates_path = ["_templates"]
 exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+intersphinx_mapping = get_intersphinx_mapping(packages={"python", "numpy", "scipy"})
 
 
 # -- Options for HTML output -------------------------------------------------
@@ -56,8 +58,7 @@
     "inherited-members": True,
     "ignore-module-all": True,
 }
-
-
+napoleon_use_rtype = False
 add_module_names = False
 
 

docs/gen_inputs.py

@@ -63,7 +63,7 @@ def main():
             for line in lines[2:]:
                 print(line, file=file)
 
-            print_section(f":py:func:`iodata.formats.{modname}.write_input`", "-", file=file)
+            print_section(f":py:func:`iodata.inputs.{modname}.write_input`", "-", file=file)
             fn = getattr(module, "write_input", None)
             print("- Requires", format_words(fn.required), file=file)
             if fn.optional:

docs/make.bat

@@ -4,6 +4,7 @@ pushd %~dp0
 
 REM Command file for Sphinx documentation
 
+set SPHINXOPTS="-W --keep-going --nitpicky"
 if "%SPHINXBUILD%" == "" (
 	set SPHINXBUILD=sphinx-build
 )

docs/requirements.txt

@@ -1,5 +1,6 @@
 # Requirements for building documentation on RTD
 furo
+intersphinx-registry
 packaging
 setuptools_scm
 sphinx_autodoc_typehints

iodata/api.py

@@ -61,8 +61,7 @@ def _select_format_module(filename: str, attrname: str, fmt: Optional[str] = Non
 
     Returns
     -------
-    format_module
-        The module implementing the required file format.
+    The module implementing the required file format.
 
     """
     basename = os.path.basename(filename)
@@ -101,8 +100,7 @@ def _select_input_module(fmt: str) -> ModuleType:
 
     Returns
     -------
-    format_module
-        The module implementing the required input format.
+    The module implementing the required input format.
 
     """
     if fmt in INPUT_MODULES:
@@ -131,8 +129,7 @@ def load_one(filename: str, fmt: Optional[str] = None, **kwargs) -> IOData:
 
     Returns
     -------
-    out
-        The instance of IOData with data loaded from the input files.
+    The instance of IOData with data loaded from the input files.
 
     """
     format_module = _select_format_module(filename, "load_one", fmt)
@@ -163,7 +160,7 @@ def load_many(filename: str, fmt: Optional[str] = None, **kwargs) -> Iterator[IO
 
     Yields
     ------
-    out
+    IOData
         An instance of IOData with data for one frame loaded for the file.
 
     """

iodata/attrutils.py

@@ -18,6 +18,8 @@
 # --
 """Utilities for building attr classes."""
 
+from typing import Callable
+
 import numpy as np
 
 __all__ = ["convert_array_to", "validate_shape"]
@@ -34,7 +36,7 @@ def converter(array):
     return converter
 
 
-def validate_shape(*shape_requirements: tuple):
+def validate_shape(*shape_requirements: tuple) -> Callable:
     """Return a validator for the shape of an array or the length of an iterable.
 
     Parameters
@@ -49,8 +51,7 @@ def validate_shape(*shape_requirements: tuple):
 
     Returns
     -------
-    validator
-        A validator function for the attr library.
+    A validator function for the attr library.
 
     Notes
     -----

iodata/basis.py

@@ -72,9 +72,8 @@ def angmom_sti(char: Union[str, list[str]]) -> Union[int, list[int]]:
 
     Returns
     -------
-    angmom
-        An integer representation of the angular momentum. If a list of str
-        char is given, a list of integers in returned.
+    An integer representation of the angular momentum.
+    If a list of str char is given, a list of integers in returned.
 
     """
     return ANGMOM_CHARS.index(char.lower())
@@ -91,9 +90,8 @@ def angmom_its(angmom: Union[int, list[int]]) -> Union[str, list[str]]:
 
     Returns
     -------
-    char
-        The string representation of the angular momentum. If a list of integer
-        angmom is given, a list of str is returned.
+    The string representation of the angular momentum.
+    If a list of integer angmom is given, a list of str is returned.
 
     """
     if angmom < 0:
@@ -113,15 +111,16 @@ class Shell:
 
     kinds: list[str] = attrs.field(validator=validate_shape(("coeffs", 1)))
     """
-    List of strings describing the kind of contractions: 'c' for Cartesian
-    and 'p' for pure. Pure functions are only allowed for angmom>1.
-    The length equals the number of contractions: len(angmoms)=ncon.
+    List of strings describing the kind of contractions:
+    ``'c'`` for Cartesian and ``'p'`` for pure.
+    Pure functions are only allowed for ``angmom > 1``.
+    The length equals the number of contractions (``ncon = len(kinds)``).
     """
 
-    exponents: NDArray = attrs.field(validator=validate_shape(("coeffs", 0)))
+    exponents: NDArray[float] = attrs.field(validator=validate_shape(("coeffs", 0)))
     """The array containing the exponents of the primitives, with shape (nprim,)."""
 
-    coeffs: NDArray = attrs.field(validator=validate_shape(("exponents", 0), ("kinds", 0)))
+    coeffs: NDArray[float] = attrs.field(validator=validate_shape(("exponents", 0), ("kinds", 0)))
     """
     The array containing the coefficients of the normalized primitives in each contraction;
     shape = (nprim, ncon).
@@ -222,7 +221,7 @@ def get_segmented(self):
 
 def convert_convention_shell(
     conv1: list[str], conv2: list[str], reverse=False
-) -> tuple[NDArray, NDArray]:
+) -> tuple[NDArray[int], NDArray[int]]:
     """Return a permutation vector and sign changes to convert from 1 to 2.
 
     The transformation from convention 1 to convention 2 can be done applying
@@ -284,7 +283,7 @@ def convert_convention_shell(
 
 def convert_conventions(
     molbasis: MolecularBasis, new_conventions: dict[str, list[str]], reverse=False
-) -> tuple[NDArray, NDArray]:
+) -> tuple[NDArray[int], NDArray[int]]:
     """Return a permutation vector and sign changes to convert from 1 to 2.
 
     The transformation from molbasis.convention to the new convention can be done
@@ -334,7 +333,7 @@ def convert_conventions(
     return np.array(permutation), np.array(signs)
 
 
-def iter_cart_alphabet(n: int) -> NDArray:
+def iter_cart_alphabet(n: int) -> NDArray[int]:
     """Loop over powers of Cartesian basis functions in alphabetical order.
 
     See https://theochem.github.io/horton/2.1.1/tech_ref_gaussian_basis.html