Fix docstrings for API doc generation.

Author: sebpuetz

src/finalfusion/compat/text.py

@@ -48,9 +48,10 @@ def load_text(file: Union[str, bytes, int, PathLike]) -> Embeddings:
     l2-normalized per default and the corresponding norms are stored in the Norms.
 
     Expects a file with utf-8 encoded lines with:
-        * word at the start of the line
-        * followed by whitespace
-        * followed by whitespace separated vector components
+
+    * word at the start of the line
+    * followed by whitespace
+    * followed by whitespace separated vector components
 
     Parameters
     ----------

src/finalfusion/compat/word2vec.py

@@ -54,7 +54,7 @@ def load_word2vec(file: Union[str, bytes, int, PathLike]) -> Embeddings:
 
 def write_word2vec(file: Union[str, bytes, int, PathLike],
                    embeddings: Embeddings):
-    """
+    r"""
     Write embeddings in word2vec binary format.
 
     If the embeddings are not compatible with the w2v format (e.g. include a SubwordVocab), only
@@ -67,10 +67,11 @@ def write_word2vec(file: Union[str, bytes, int, PathLike],
     This is followed by the embeddings.
 
     Each embedding consists of:
-        * utf-8 encoded word
-        * single space `' '` following the word
-        * `cols` single-precision floating point numbers
-        * `'\n'` newline at the end of each line.
+
+    * utf-8 encoded word
+    * single space ``' '`` following the word
+    * ``cols`` single-precision floating point numbers
+    *  ``'\n'`` newline at the end of each line.
 
     Parameters
     ----------

src/finalfusion/embeddings.py

@@ -37,14 +37,18 @@ class Embeddings:  # pylint: disable=too-many-instance-attributes
 
     Embeddings are composed of the 4 chunk types:
 
-    1. :class:`~finalfusion.storage.Storage` *(required)*:
+    1. :class:`~finalfusion.storage.storage.Storage` *(required)*:
+
         * :class:`~finalfusion.storage.ndarray.NdArray`
         * :class:`~finalfusion.storage.ndarray.QuantizedArray`
-    2. :class:`~finalfusion.vocab.Vocab` *(required)*:
-        * :class:`~finalfusion.vocab.simple_vocab.SimpleVocab`,
+
+    2. :class:`~finalfusion.vocab.vocab.Vocab` *(required)*:
+
+        * :class:`~finalfusion.vocab.simple_vocab.SimpleVocab`
         * :class:`~finalfusion.vocab.subword.FinalfusionBucketVocab`
         * :class:`~finalfusion.vocab.subword.FastTextVocab`
         * :class:`~finalfusion.vocab.subword.ExplicitVocab`
+
     3. :class:`~finalfusion.metadata.Metadata`
     4. :class:`~finalfusion.norms.Norms`
 
@@ -81,7 +85,7 @@ def __init__(self,
         Initializes Embeddings with the given chunks.
 
         :Conditions:
-            The following conditions need to hold if the respective chunks are passed.
+            The following conditions need to hold if the respective chunks are passed:
 
             * Chunks need to have the expected type.
             * ``vocab.idx_bound == storage.shape[0]``
@@ -103,6 +107,7 @@ def __init__(self,
         ------
         AssertionError
             If any of the conditions don't hold.
+
         """
         Embeddings._check_requirements(storage, vocab, norms, metadata)
         self._storage = storage
@@ -112,7 +117,7 @@ def __init__(self,
 
     def __getitem__(self, item: str) -> np.ndarray:
         """
-        Returns an embeddings.
+        Returns an embedding.
 
         Parameters
         ----------
@@ -347,10 +352,11 @@ def chunks(self) -> List[Chunk]:
         Get the Embeddings Chunks as a list.
 
         The Chunks are ordered in the expected serialization order:
-        1. Metadata (optional)
-        2. Vocabulary
-        3. Storage
-        4. Norms (optional)
+
+            1. Metadata (optional)
+            2. Vocabulary
+            3. Storage
+            4. Norms (optional)
 
         Returns
         -------
@@ -435,7 +441,7 @@ def analogy(  # pylint: disable=too-many-arguments
         query `word1` is to `word2` as `word3` is to `?`. More concretely,
         it searches embeddings that are similar to:
 
-        *embedding(word2) - embedding(word1) + embedding(word3)*
+        ``embedding(word2) - embedding(word1) + embedding(word3)``
 
         Words specified in ``skip`` are not considered as answers. If ``skip``
         is None, the query words ``word1``, ``word2`` and ``word3`` are

src/finalfusion/storage/ndarray.py

@@ -20,6 +20,23 @@ class NdArray(np.ndarray, Storage):
     Array storage.
 
     Wraps an numpy matrix, either in-memory or memory-mapped.
+
+    Examples
+    --------
+    >>> storage = NdArray(np.array([[1., 0.5], [0.5, 1.], [0.3, 0.4]],
+    ...                            dtype=np.float32))
+    >>> # slicing an NdArray returns a storage backed by the same array
+    >>> storage[:2]
+    NdArray([[1. , 0.5],
+             [0.5, 1. ]], dtype=float32)
+    >>> # NdArray storage can be treated as numpy arrays
+    >>> storage * 2
+    NdArray([[2. , 1. ],
+             [1. , 2. ],
+             [0.6, 0.8]], dtype=float32)
+    >>> # Indexing with arrays, lists or ints returns numpy.ndarray
+    >>> storage[0]
+    array([1. , 0.5], dtype=float32)
     """
     def __new__(cls, array: np.ndarray):
         """