Cleaned up docstring again, use a prettier HTML theme.

docs/conf.py

@@ -183,7 +183,7 @@
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-html_theme = "alabaster"
+html_theme = "furo"
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
@@ -313,4 +313,4 @@
     "pyscaffold": ("https://pyscaffold.org/en/stable", None),
 }
 
-print(f"loading configurations for {project} {version} ...", file=sys.stderr)
+print(f"loading configurations for {project} {version} ...", file=sys.stderr)

src/biocutils/Factor.py

@@ -83,8 +83,8 @@ def __init__(self, codes: Sequence[int], levels: Sequence[str], ordered: bool =
                 List of names. This should have same length as ``codes``.
                 Alternatively None, if the factor has no names yet.
 
-            validate:
-                Whether to validate the arguments. Internal use only.
+            _validate:
+                Internal use only.
         """
         if _validate:
             levels = _sanitize_levels(levels)
@@ -110,13 +110,13 @@ def get_codes(self) -> numpy.ndarray:
         """
         Returns:
             Array of integer codes, used as indices into the levels from
-            :py:attr:`~get_levels`. Missing values are marked with -1.
+            :py:meth:`~get_levels`. Missing values are marked with -1.
         """
         return self._codes
 
     @property
     def codes(self) -> numpy.ndarray:
-        """Alias for :py:attr:`~get_codes`."""
+        """Alias for :py:meth:`~get_codes`."""
         return self.get_codes()
 
     def set_codes(self, codes: Sequence[int], in_place: bool = False) -> "Factor":
@@ -148,7 +148,7 @@ def get_levels(self) -> StringList:
 
     @property
     def levels(self) -> StringList:
-        """Alias for :py:attr:`~get_levels`."""
+        """Alias for :py:meth:`~get_levels`."""
         return self.get_levels()
 
     def get_ordered(self) -> bool:
@@ -160,7 +160,7 @@ def get_ordered(self) -> bool:
 
     @property
     def ordered(self) -> bool:
-        """Alias for :py:attr:`~get_ordered`."""
+        """Alias for :py:meth:`~get_ordered`."""
         return self.get_ordered()
 
     def set_ordered(self, ordered: bool, in_place: bool = False) -> "Factor":
@@ -189,7 +189,7 @@ def get_names(self) -> Names:
 
     @property
     def names(self) -> Names:
-        """Alias for :py:attr:`~get_names`."""
+        """Alias for :py:meth:`~get_names`."""
         return self.get_names()
 
     def set_names(self, names: Optional[Names], in_place: bool = False) -> "NamedList":
@@ -294,9 +294,9 @@ def get_slice(self, index: SubscriptTypes) -> "Factor":
 
     def __getitem__(self, index: SubscriptTypes) -> Union[str, "Factor"]:
         """
-        If ``index`` is a scalar, this is an alias for :py:attr:`~get_value`.
+        If ``index`` is a scalar, this is an alias for :py:meth:`~get_value`.
 
-        If ``index`` is a sequence, this is an alias for :py:attr:`~get_slice`.
+        If ``index`` is a sequence, this is an alias for :py:meth:`~get_slice`.
         """
         index, scalar = normalize_subscript(index, len(self), self._names)
         if scalar:
@@ -396,9 +396,9 @@ def set_slice(self, index: SubscriptTypes, value: "Factor", in_place: bool = Fal
 
     def __setitem__(self, index: SubscriptTypes, value: Union[str, "Factor"]):
         """
-        If ``index`` is a scalar, this is an alias for :py:attr:`~set_value`.
+        If ``index`` is a scalar, this is an alias for :py:meth:`~set_value`.
 
-        If ``index`` is a sequence, this is an alias for :py:attr:`~set_slice`.
+        If ``index`` is a sequence, this is an alias for :py:meth:`~set_slice`.
         """
         index, scalar = normalize_subscript(index, len(self), self._names)
         if scalar:
@@ -584,7 +584,7 @@ def from_sequence(x: Sequence[str], levels: Optional[Sequence[str]] = None, sort
                 the levels are kept in order of their appearance in ``x``.  Not
                 used if ``levels`` is explicitly supplied.
 
-            ordered (bool):
+            ordered:
                 Whether the levels should be assumed to be ordered.  Note that
                 this refers to their importance and has nothing to do with
                 their sorting order or with the setting of ``sort_levels``.

src/biocutils/NamedList.py

@@ -98,7 +98,7 @@ def get_names(self) -> Names:
 
     @property
     def names(self) -> Names:
-        """Alias for :py:attr:`~get_names`."""
+        """Alias for :py:meth:`~get_names`."""
         return self.get_names()
 
     def _shallow_copy(self):
@@ -166,9 +166,9 @@ def get_slice(self, index: SubscriptTypes) -> "NamedList":
 
     def __getitem__(self, index: SubscriptTypes) -> Union["NamedList", Any]:
         """
-        If ``index`` is a scalar, this is an alias for :py:attr:`~get_value`.
+        If ``index`` is a scalar, this is an alias for :py:meth:`~get_value`.
 
-        If ``index`` is a sequence, this is an alias for :py:attr:`~get_slice`.
+        If ``index`` is a sequence, this is an alias for :py:meth:`~get_slice`.
         """
         index, scalar = normalize_subscript(index, len(self), self._names)
         if scalar:
@@ -248,7 +248,7 @@ def set_slice(self, index: SubscriptTypes, value: Sequence, in_place: bool = Fal
             the contents of ``value``. If ``in_place = False``, this is a new
             object, otherwise it is a reference to the current object.
 
-            Unlike :py:attr:`~set_value`, this will not add new elements if
+            Unlike :py:meth:`~set_value`, this will not add new elements if
             ``index`` contains names that do not already exist in the object;
             a missing name error is raised instead.
         """
@@ -267,10 +267,10 @@ def set_slice(self, index: SubscriptTypes, value: Sequence, in_place: bool = Fal
 
     def __setitem__(self, index: SubscriptTypes, value: Any):
         """
-        If ``index`` is a scalar, this is an alias for :py:attr:`~set_value`
+        If ``index`` is a scalar, this is an alias for :py:meth:`~set_value`
         with ``in_place = True``.
 
-        If ``index`` is a sequence, this is an alias for :py:attr:`~set_slice`
+        If ``index`` is a sequence, this is an alias for :py:meth:`~set_slice`
         with ``in_place = True``.
         """
         if isinstance(index, str):
@@ -321,7 +321,7 @@ def safe_insert(self, index: Union[int, str], value: Any, in_place: bool = False
         return output
 
     def insert(self, index: Union[int, str], value: Any):
-        """Alias for :py:attr:`~safe_insert` with `in_place = True`."""
+        """Alias for :py:meth:`~safe_insert` with ``in_place = True``."""
         self.safe_insert(index, value, in_place=True)
 
     def safe_append(self, value: Any, in_place: bool = False) -> "NamedList":
@@ -346,13 +346,13 @@ def safe_append(self, value: Any, in_place: bool = False) -> "NamedList":
         return output
 
     def append(self, value: Any):
-        """Alias for :py:attr:`~safe_append` with `in_place = True`."""
+        """Alias for :py:meth:`~safe_append` with ``in_place = True``."""
         self.safe_append(value, in_place=True)
 
     def safe_extend(self, other: Iterable, in_place: bool = False) -> "NamedList":
         """
         Args:
-            iterable: 
+            other: 
                 Some iterable object. If this is a ``NamedList``, its names are
                 used to extend the names of the current object; otherwise the
                 extended names are set to empty strings.
@@ -361,8 +361,8 @@ def safe_extend(self, other: Iterable, in_place: bool = False) -> "NamedList":
                 Whether to perform the modification in place.
 
         Returns:
-            A ``NamedList`` where items in ``iterable`` are added to the end.
-            If ``in_place = False``, this is a new object, otherwise a reference
+            A ``NamedList`` where items in ``other`` are added to the end. If
+            ``in_place = False``, this is a new object, otherwise a reference
             to the current object is returned.
         """
         output = self._define_output(in_place)
@@ -379,15 +379,15 @@ def safe_extend(self, other: Iterable, in_place: bool = False) -> "NamedList":
         return output
 
     def extend(self, other: Iterable):
-        """Alias for :py:attr:`~safe_extend` with ``in_place = True``."""
+        """Alias for :py:meth:`~safe_extend` with ``in_place = True``."""
         self.safe_extend(other, in_place=True)
 
     def __add__(self, other: list) -> "NamedList":
-        """Alias for :py:attr:`~safe_extend`."""
+        """Alias for :py:meth:`~safe_extend`."""
         return self.safe_extend(other)
 
     def __iadd__(self, other: list):
-        """Alias for :py:attr:`~extend`, returning a reference to the current
+        """Alias for :py:meth:`~extend`, returning a reference to the current
         object after the in-place modification."""
         self.extend(other)
         return self
@@ -401,7 +401,7 @@ def copy(self) -> "NamedList":
         Returns:
             A shallow copy of a ``NamedList`` with the same contents.  This
             will copy the underlying list (and names, if any exist) so that any
-            in-place operations like :py:attr:`~append`, etc., on the new
+            in-place operations like :py:meth:`~append`, etc., on the new
             object will not change the original object.
         """
         newnames = self._names

src/biocutils/Names.py

@@ -244,7 +244,7 @@ def safe_append(self, value: str, in_place: bool = False) -> "Names":
         return output
 
     def append(self, value: str):
-        """Alias for :py:attr:`~safe_append` with `in_place = True`."""
+        """Alias for :py:attr:`~safe_append` with ``in_place = True``."""
         self.safe_append(value, in_place=True)
 
     def safe_insert(self, index: int, value: str, in_place: bool = False) -> "Names":
@@ -266,7 +266,7 @@ def safe_insert(self, index: int, value: str, in_place: bool = False) -> "Names"
         return output
 
     def insert(self, index: int, value: str):
-        """Alias for :py:attr:`~safe_insert` with `in_place = True`."""
+        """Alias for :py:attr:`~safe_insert` with ``in_place = True``."""
         self.safe_insert(index, value, in_place=True)
 
     def safe_extend(self, value: Sequence[str], in_place: bool = False) -> "Names":
@@ -294,7 +294,7 @@ def safe_extend(self, value: Sequence[str], in_place: bool = False) -> "Names":
         return output
 
     def extend(self, value: Sequence[str]):
-        """Alias for :py:attr:`~safe_extend` with `in_place = True`."""
+        """Alias for :py:attr:`~safe_extend` with ``in_place = True``."""
         self.safe_extend(value, in_place=True)
 
     def __add__(self, other: list):

src/biocutils/StringList.py

@@ -52,21 +52,21 @@ def __init__(self, data: Optional[Iterable] = None, names: Optional[Names] = Non
         super().__init__(data, names, _validate=_validate)
 
     def set_value(self, index: Union[int, str], value: Any, in_place: bool = False) -> "StringList":
-        """Calls :py:meth:`~NamedList.NamedList.set_value` after coercing ``value`` to a string."""
+        """Calls :py:meth:`~biocutils.NamedList.NamedList.set_value` after coercing ``value`` to a string."""
         return super().set_value(index, _coerce_to_str(value), in_place=in_place) 
 
     def set_slice(self, index: SubscriptTypes, value: Sequence, in_place: bool = False) -> "StringList":
-        """Calls :py:meth:`~NamedList.NamedList.set_slice` after coercing ``value`` to strings."""
+        """Calls :py:meth:`~biocutils.NamedList.NamedList.set_slice` after coercing ``value`` to strings."""
         return super().set_slice(index, _SubscriptCoercer(value), in_place=in_place) 
 
     def safe_insert(self, index: Union[int, str], value: Any, in_place: bool = False) -> "StringList":
-        """Calls :py:meth:`~NamedList.NamedList.safe_insert` after coercing ``value`` to a string."""
+        """Calls :py:meth:`~biocutils.NamedList.NamedList.safe_insert` after coercing ``value`` to a string."""
         return super().safe_insert(index, _coerce_to_str(value), in_place=in_place) 
 
     def safe_append(self, value: Any, in_place: bool = False) -> "StringList":
-        """Calls :py:meth:`~NamedList.NamedList.safe_append` after coercing ``value`` to a string."""
+        """Calls :py:meth:`~biocutils.NamedList.NamedList.safe_append` after coercing ``value`` to a string."""
         return super().safe_append(_coerce_to_str(value), in_place=in_place)
 
     def safe_extend(self, other: Iterable, in_place: bool = True) -> "StringList":
-        """Calls :py:meth:`~NamedList.NamedList.safe_extend` after coercing elements of ``other`` to strings."""
+        """Calls :py:meth:`~biocutils.NamedList.NamedList.safe_extend` after coercing elements of ``other`` to strings."""
         return super().safe_extend((_coerce_to_str(y) for y in other), in_place=in_place)

src/biocutils/map_to_index.py

@@ -15,8 +15,9 @@ def map_to_index(x: Sequence, duplicate_method: DUPLICATE_METHOD = "first") -> d
             Sequence of hashable values. We ignore missing values defined by 
             :py:meth:`~biocutils.is_missing_scalar.is_missing_scalar`.
 
-        duplicate_method (DUPLICATE_METHOD): Whether to consider the first or
-            last occurrence of a duplicated value in ``x``.
+        duplicate_method:
+            Whether to consider the first or last occurrence of a duplicated
+            value in ``x``.
 
     Returns:
         dict: Dictionary that maps values of ``x`` to their position inside ``x``.

src/biocutils/match.py

@@ -8,17 +8,21 @@ def match(x: Sequence, targets: Union[dict, Sequence], duplicate_method: DUPLICA
     """Find a matching value of each element of ``x`` in ``target``.
 
     Args:
-        x (Sequence): Sequence of values to match.
+        x: Squence of values to match.
 
-        targets (Union[dict, Sequence]):
+        targets:
             Sequence of targets to be matched against. Alternatively, a
             dictionary generated by passing a sequence of targets to
             :py:meth:`~biocutils.map_to_index.map_to_index`.
 
+        duplicate_method:
+            How to handle duplicate entries in ``targets``. Matches can
+            be reported to the first or last occurrence of duplicates.
+
     Returns:
-        list[Union[int, None]]: List of length equal to ``x``, containing the
-        integer position of each entry of ``x`` inside ``target``; or None,
-        if the entry of ``x`` is None or cannot be found in ``target``.
+        Array of length equal to ``x``, containing the integer position of each
+        entry of ``x`` inside ``target``; or -1, if the entry of ``x`` is
+        None or cannot be found in ``target``.
     """
     if not isinstance(targets, dict):
         targets = map_to_index(targets, duplicate_method=duplicate_method)