[Doc] MISC docstrings

README.rst

@@ -30,16 +30,15 @@ AnkiPandas: Open your Anki database as a pandas DataFrame in just one line!
 Description
 -----------
 
-With this small python package, you can easily load all of your Anki_ flashcards
-as a all-in-one pandas_ DataFrame_!
+Analyze and manipulate your Anki_ flashcards as a pandas_ DataFrame_!
 
 .. _anki: https://apps.ankiweb.net/
 .. _pandas: https://pandas.pydata.org/
 .. _DataFrame: https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html
 
 **Pros**:
 
-* Use pandas to easily analize or manipulate your Anki collection
+* Use pandas to easily analyze or manipulate your Anki collection
 * Just one line of code to get started
 * Bring together information about cards_, notes_, models_, decks_ in just one table!
 * Easy installation (independent from your anki installation)

ankipandas/convenience_functions.py

@@ -155,10 +155,15 @@ def find_database(
         search_paths: Search path as string or pathlib object or list/iterable
             thereof. If None, some search paths are set by default.
         maxdepth: Maximal search depth.
-        filename: Filename of the collection.
+        filename: Filename of the collection (default: ``collections.anki2``)
         user: Username to which the collection belongs. If None, search for
             databases of any user.
-        break_on_first: Stop searching once a database is found.
+        break_on_first: Stop searching once a database is found. This is
+            obviously faster, but you will not get any errors if there are
+            multiple databases matching your criteria.
+
+    Raises:
+        :class:`ValueError` if none ore more than one result is found.
 
     Returns:
         pathlib.Path to the anki2 database

ankipandas/util/docstring_utils.py

@@ -1,16 +1,23 @@
 #!/usr/bin/env python3
 
+# std
 import collections
+from typing import Dict, Tuple
 
 
-def parse_docstring(string):
-    """ Parses docstring
+def parse_docstring(string: str) -> Tuple[str, Dict[str, str], str]:
+    """ Parses google style docstring.
 
     Args:
         string: docstring
 
     Returns: Description [str], description of arguments [Dict[str, str]],
         description of return value [str]
+
+    .. warning::
+
+        Experimental. This is not yet well tested but for this very module.
+
     """
     if not string:
         return "", {}, ""
@@ -36,14 +43,15 @@ def parse_docstring(string):
                 _arg = kv[0]
                 args[_arg] = ":".join(kv[1:])
             else:
-                args[_arg] += kv[0].strip()
+                args[_arg] += kv[0]
         else:
             raise AssertionError
     return desc, args, returns
 
 
-def format_docstring(desc, args, returns, drop_arg=()):
-    """ Format docstring.
+def format_docstring(desc: str, args: Dict[str, str], returns: str,
+                     drop_arg=()) -> str:
+    """ Format google style docstring.
 
     Args:
         desc: Description [str]
@@ -54,6 +62,11 @@ def format_docstring(desc, args, returns, drop_arg=()):
 
     Returns:
         Docstring with the info supplied in the parameters.
+
+    .. warning::
+
+        Experimental. This is not yet well tested but for this very module.
+
     """
     ret = desc
     ret += "\n\nArgs:\n"
@@ -68,5 +81,5 @@ def format_docstring(desc, args, returns, drop_arg=()):
             continue
         ret += "{}: {}\n".format(arg, argdesc)
     ret += "\nReturns:\n"
-    ret += returns.strip()
+    ret += returns
     return ret

doc/ankidf.rst

@@ -1,7 +1,6 @@
 AnkiDataFrame
 =============
 
-.. automodule:: ankipandas.ankidf
+.. autoclass:: ankipandas.ankidf.AnkiDataFrame
     :members:
     :undoc-members:
-