improve doc strings

src/metadata.py

@@ -41,10 +41,14 @@ def to_dict(self):
 
 
 class Metadata:
-    '''
-    This class retrieve and organise book and chapters metadata
-    associated to the user given ISBN.
-    '''
+    """Class retrieve and organise book and chapters metadata
+
+    Data is retrieved from a selected source (database) and the result is
+    stored in Book and Chapter objects. These objects live inside this class:
+    every time data is sent to other modules is converted into a dictionary
+    representation. Same applies when data in fetched.
+    """
+
     def __init__(self, database="thoth", doi=None):
         if database == "thoth":
             self.db = Thoth(doi)
@@ -69,9 +73,7 @@ def get_chapters(self) -> List[Dict]:
 
     @staticmethod
     def write_metadata(chapter_dict, output_file_path):
-        """
-        Writes metadata to file_name
-        """
+        """Writes metadata to file_name"""
 
         arguments = [f"-Title={chapter_dict.get('title')}",
                      f"-Author={chapter_dict.get('author')}",
@@ -97,12 +99,11 @@ def write_metadata(chapter_dict, output_file_path):
 
     @staticmethod
     def get_rights(chapter_data):
-        '''
-        Compose a simple copyright statement, just like:
-        '© John Doe https://creativecommons.org/licenses/by/2.0/'
+        """Compose a simple copyright statement
 
-        Author name and licence link are pulled out from chapter_data
-        '''
+        This method return a copyright statement which looks like:
+        '© John Doe https://creativecommons.org/licenses/by/2.0/'
+        """
 
         data = {'authors_names': chapter_data.get('author'),
                 'copyright_url': chapter_data.get('licence')}

src/pdf.py

@@ -14,8 +14,9 @@ def __init__(self, input_file, output_folder):
         self.copyright_page_n = environ.get('COPYRIGHT_PAGE', 4)
 
     def merge_pdfs(self, page_range, output_file_name):
-        """
-        Create the chapter PDF by merging toghether extracts of the original
+        """Compose a PDF by merging sections together
+
+        Create the chapter PDF by merging together extracts of the original
         PDF. These parts are front cover, copyright page and chapter body text.
         """