Documentation (#42)

* Add dev packages for documentation

* Add __version__ to project __init__ module

- Not quite sure why this wasn't there to begin with.

* Initial documentation

* Run pre-commit

Apparently my pre-commit wasn't installed correcly.

* Make the sphinx packages an optional install dep

- This is need for readthedocs support

* Select the docstring checks

* Add docstrings to project __init__

* Add config for readthedocs

* Add docstring for creator & creator_list

* Add docstring for issue & issue_list

* Add docstring for publisher & publisher_list

* Add basic docstring to docs conf

* Initial docstrings for session module

* Add docstring for story_arc & story_arc_list

* Add docstring for sqlite_cache

* Add docstring for volume & volume_list

* Fix return type for story_arc_list method

* Add docstring for exceptions

* Add docstring for generic_entries

* Add some basic docstring to test configs

* Add docstring to the creator tests

* Add missing newline

* Add blank line to docstring to quite flake8

* Add docstring to test_init

* Add docstring for test_issues

* Add docstring for test_publishers

* Add dosctrings for test_volumes

* Add docstring for test_story_arcs

* Add additional flake8 deps to pre-commit

- Add check so new code adds/formats docstrings

* Add missing newline

* Fix some copy paste errors

* Update tests/test_issues.py

Yup, tho the function name should probably be change to `test_issue_list_has_staff_review`

Co-authored-by: Buried-In-Code <6057651+Buried-In-Code@users.noreply.github.com>

Co-authored-by: Buried-In-Code <6057651+Buried-In-Code@users.noreply.github.com>

.flake8

@@ -1,5 +1,5 @@
 [flake8]
 max-line-length = 120
 max-complexity = 18
-select = B,C,E,F,W,T4,B9
+select = B,C,D,E,F,W,T4,B9
 extend-ignore = E203

.pre-commit-config.yaml

@@ -15,6 +15,7 @@ repos:
     rev: 3.9.2
     hooks:
       - id: flake8
+        additional_dependencies: [flake8-docstrings, flake8-rst-docstrings]
   - repo: https://github.com/asottile/pyupgrade
     rev: v2.26.0
     hooks:

.readthedocs.yml

@@ -0,0 +1,19 @@
+# .readthedocs.yml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Build documentation in the docs/ directory with Sphinx
+sphinx:
+  configuration: docs/source/conf.py
+
+# Optionally set the version of Python and requirements required to build your docs
+python:
+  version: "3.7"
+  install:
+    - method: pip
+      path: .
+      extra_requirements:
+        - docs

Simyan/__init__.py

@@ -1,3 +1,6 @@
+"""Project entry file."""
+__version__ = "0.5.1"
+
 from typing import Optional
 
 from Simyan.exceptions import AuthenticationError
@@ -6,6 +9,11 @@
 
 
 def api(api_key: Optional[str] = None, cache: SqliteCache = None) -> Session:
+    """Entry function that sets credentials to use the Comic Vine API, and whether to use a database cache for results.
+
+    :param str, optional api_key: User's api key to access the Comic Vine api.
+    :param SqliteCache optional: SqliteCache to use
+    """
     if api_key is None:
         raise AuthenticationError("Missing API Key.")
 

Simyan/creator.py

@@ -1,15 +1,32 @@
+"""
+Creator module.
+
+This module provides the following classes:
+
+- Creator
+- CreatorSchema
+"""
 from marshmallow import EXCLUDE, Schema, fields, post_load, pre_load
 
 from Simyan.generic_entries import GenericEntrySchema, ImageEntrySchema
 
 
 class Creator:
+    """
+    The Creator object contains information for creators.
+
+    :param `**kwargs`: The keyword arguments is used for setting creator data from Comic Vine.
+    """
+
     def __init__(self, **kwargs):
+        """Intialize a new Creator."""
         for k, v in kwargs.items():
             setattr(self, k, v)
 
 
 class CreatorSchema(Schema):
+    """Schema for the Creator API."""
+
     aliases = fields.Str(allow_none=True)
     api_url = fields.Url(data_key="api_detail_url")
     country = fields.Str()
@@ -34,12 +51,21 @@ class CreatorSchema(Schema):
     website = fields.Str(allow_none=True)
 
     class Meta:
+        """Any unknown fields will be excluded."""
+
         unknown = EXCLUDE
         dateformat = "%Y-%m-%d %H:%M:%S"
         datetimeformat = "%Y-%m-%d %H:%M:%S"
 
     @pre_load
     def process_input(self, data, **kwargs):
+        """
+        Only keep the date of death information from Comic Vine.
+
+        The time zone info they include is not of any use.
+
+        :param data: Data from the Comic Vine response
+        """
         new_data = data
 
         if "death" in new_data and new_data["death"] is not None:
@@ -49,4 +75,12 @@ def process_input(self, data, **kwargs):
 
     @post_load
     def make_object(self, data, **kwargs) -> Creator:
+        """
+        Make the Creator object.
+
+        :param data: Data from Comic Vine reponse.
+
+        :returns: :class:`Creator` object
+        :rtype: Creator
+        """
         return Creator(**data)

Simyan/creator_list.py

@@ -1,16 +1,34 @@
+"""
+CreatorList module.
+
+This module provides the following classes:
+
+- CreatorResult
+- CreatorResultSchema
+- CreatorList
+"""
 from marshmallow import EXCLUDE, Schema, ValidationError, fields, post_load
 
 from Simyan.exceptions import APIError
 from Simyan.generic_entries import ImageEntrySchema
 
 
 class CreatorResult:
+    """
+    The CreatorResult object.
+
+    :param `**kwargs`: The keyword arguments is used for setting data from Comic Vine.
+    """
+
     def __init__(self, **kwargs):
+        """Intialize a new CreatorResult."""
         for k, v in kwargs.items():
             setattr(self, k, v)
 
 
 class CreatorResultSchema(Schema):
+    """Schema for the CreatorResult API."""
+
     aliases = fields.Str(allow_none=True)
     api_url = fields.Url(data_key="api_detail_url")
     country = fields.Str()
@@ -31,17 +49,30 @@ class CreatorResultSchema(Schema):
     website = fields.Str(allow_none=True)
 
     class Meta:
+        """Any unknown fields will be exclude."""
+
         unknown = EXCLUDE
         dateformat = "%Y-%m-%d %H:%M:%S"
         datetimeformat = "%Y-%m-%d %H:%M:%S"
 
     @post_load
     def make_object(self, data, **kwargs) -> CreatorResult:
+        """
+        Make the CreatorResult object.
+
+        :param data: Data from the Comic Vine reponse.
+
+        :returns: :class:`CreatorResult` object
+        :rtype: CreatorResult
+        """
         return CreatorResult(**data)
 
 
 class CreatorList:
+    """The CreatorList object contains a list of `CreatorResult` objects."""
+
     def __init__(self, response):
+        """Initialize a new CreatorList."""
         self.creators = []
 
         schema = CreatorResultSchema()
@@ -54,10 +85,13 @@ def __init__(self, response):
             self.creators.append(result)
 
     def __iter__(self):
+        """Return an iterator object."""
         return iter(self.creators)
 
     def __len__(self):
+        """Return the length of the object."""
         return len(self.creators)
 
     def __getitem__(self, index: int):
+        """Return the object of a at index."""
         return self.creators[index]

Simyan/exceptions.py

@@ -1,10 +1,27 @@
+"""
+Exceptions module.
+
+This module provides the following classes:
+
+- ApiError
+- AuthenticationError
+- CacheError
+"""
+
+
 class APIError(Exception):
+    """Class for any api errors."""
+
     pass
 
 
 class AuthenticationError(APIError):
+    """Class for any authentication errors."""
+
     pass
 
 
 class CacheError(APIError):
+    """Class for any database cache errors."""
+
     pass