docs: refactor docstrings (#97)

Co-authored-by: Alex Kanitz <alexander.kanitz@unibas.ch>

foca/__init__.py

@@ -1 +1,3 @@
+"""FOCA root package."""
+
 __version__ = '0.6.0'

foca/api/register_openapi.py

@@ -1,4 +1,4 @@
-"""Tests for modifying/registering OpenAPI specs."""
+"""Register and modify OpenAPI specifications."""
 
 import logging
 from typing import List
@@ -18,19 +18,20 @@ def register_openapi(
         specs: List[SpecConfig],
 ) -> App:
     """
-    Register OpenAPI specs with Connexion app.
+    Register OpenAPI specifications with Connexion application instance.
 
     Args:
-        app: A Connexion app instance.
-        specs: A sequence of `SpecConfig` config models describing OpenAPI 2.x
-            and/or 3.x specifications to be registered with `app`.
+        app: Connexion application instance.
+        specs: Sequence of :py:class:`foca.models.config.SpecConfig` instances
+            describing OpenAPI 2.x and/or 3.x specifications to be registered
+            with `app`.
 
     Returns:
-        A Connexion app instance.
+        Connexion application instance with registered OpenAPI specifications.
 
     Raises:
-        OSError: File cannot be read from or written to.
-        yaml.YAMLError: YAML cannot be (de)serialized.
+        OSError: Modified specification cannot be written.
+        yaml.YAMLError: Modified specification cannot be serialized.
     """
     # Iterate over OpenAPI specs
     for spec in specs:

foca/config/config_parser.py

@@ -13,7 +13,7 @@
 
 
 class ConfigParser():
-    """Parser for FOCA config files.
+    """Parse FOCA config files.
 
     Args:
         config_file: Path to config file in YAML format.
@@ -35,10 +35,10 @@ def __init__(
         else:
             self.config = Config()
         if format_logs:
-            self.configure_logging()
+            self._configure_logging()
         logger.debug(f"Parsed config: {self.config.dict(by_alias=True)}")
 
-    def configure_logging(self) -> None:
+    def _configure_logging(self) -> None:
         """Configure logging."""
         try:
             dictConfig(self.config.log.dict(by_alias=True))
@@ -51,17 +51,17 @@ def configure_logging(self) -> None:
 
     @staticmethod
     def parse_yaml(conf: str) -> Dict:
-        """Load YAML file.
+        """Parse YAML file.
 
         Args:
             conf: Path to YAML file.
 
         Returns:
-            Dictionary of YAML file contents.
+            Dictionary of `conf` contents.
 
         Raises:
-            OSError: file cannot be accessed.
-            yaml.YAMLError: file cannot not be parsed.
+            OSError: File cannot be accessed.
+            yaml.YAMLError: File contents cannot be parsed.
         """
         try:
             with open(conf) as config_file:
@@ -80,17 +80,17 @@ def parse_yaml(conf: str) -> Dict:
     def merge_yaml(*args: str) -> Optional[Dict]:
         """Parse and merge a set of YAML files.
 
-        Merging is done iteratively, from the first, second to the nth
-        argument. Dict items are updated, not overwritten. For exact behavior
-        cf. https://github.com/mewwts/addict.
+        Merging is done iteratively, from the first, second to the n-th
+        argument. Dictionary items are updated, not overwritten. For exact
+        behavior cf. https://github.com/mewwts/addict.
 
         Args:
             *args: One or more paths to YAML files.
 
         Returns:
-            Dictionary of merged YAML file contents, or `None` if no arguments
-            have been supplied; if only a single YAML file path is provided, no
-            merging is done.
+            Dictionary of merged YAML file contents, or ``None`` if no
+            arguments have been supplied; if only a single YAML file path is
+            provided, no merging is done.
         """
         args_list = list(args)
         if not args_list:

foca/database/register_mongodb.py

@@ -1,4 +1,4 @@
-"""Register MongoDB with a Flask app."""
+"""Register MongoDB database and collections."""
 
 import logging
 import os
@@ -15,25 +15,24 @@ def register_mongodb(
     app: Flask,
     conf: MongoConfig,
 ) -> MongoConfig:
-    """
-    Instantiates a MongoDB database, initializes collections and adds the
-    database and collections to a Flask app.
+    """Register MongoDB databases and collections with Flask application
+    instance.
 
     Args:
-        app: Flask application object.
-        conf: MongoDB configuration object.
+        app: Flask application instance.
+        conf: :py:class:`foca.models.config.MongoConfig` instance describing
+            databases and collections to be registered with `app`.
 
     Returns:
-        Flask application with updated config: `config['database']['database']`
-            contains the database object; `config['database']['collections']`
-            contains a dictionary of collection objects.
+        Flask application instance with registered MongoDB databases and
+        collections.
     """
     # Iterate over databases
     if conf.dbs is not None:
         for db_name, db_conf in conf.dbs.items():
 
             # Instantiate PyMongo client
-            mongo = create_mongo_client(
+            mongo = _create_mongo_client(
                 app=app,
                 host=conf.host,
                 port=conf.port,
@@ -67,24 +66,22 @@ def register_mongodb(
     return conf
 
 
-def create_mongo_client(
+def _create_mongo_client(
         app: Flask,
         host: str = 'mongodb',
         port: int = 27017,
         db: str = 'database',
 ) -> PyMongo:
-    """Register MongoDB database with Flask app.
-
-    Optionally, basic authorization can be set by environment variables.
+    """Create MongoDB client for Flask application instance.
 
     Args:
-        app: Flask application object.
-        host: Host at which the MongoDB database is exposed.
-        port: Port at which the MongoDB database is exposed.
-        db: Name of the database to be accessed/created.
+        app: Flask application instance.
+        host: Host at which MongoDB database is exposed.
+        port: Port at which MongoDB database is exposed.
+        db: Name of database to be accessed/created.
 
     Returns:
-        Client for the MongoDB database specified by `host`, `port` and `db`.
+        MongoDB client for Flask application instance.
     """
     auth = ''
     user = os.environ.get('MONGO_USERNAME')