Docs (#7)

* docs: Added initial documentation for the package, magic methods and explicit hidden functions left out by sphinx

* docs: using pydata-theme for documentation

docs/conf.py

@@ -20,12 +20,20 @@
 # ones.
 extensions = [
     "myst_nb",
+    "sphinx.ext.autodoc",
     "autoapi.extension",
     "sphinx.ext.napoleon",
     "sphinx.ext.viewcode",
 ]
+autodoc_typehints = "both"
 autoapi_dirs = ["../masterblaster"]
-
+autoapi_options = [
+    "members",
+    "undoc-members",
+    "show-inheritance",
+    "show-module-summary",
+    "imported-members",
+]
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This pattern also affects html_static_path and html_extra_path.
@@ -36,4 +44,12 @@
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = "sphinx_rtd_theme"
+html_theme = "pydata_sphinx_theme"
+
+html_sidebars = {"<page_pattern>": ["list", "of", "templates"]}
+html_theme_options = {
+    "navbar_start": ["navbar-logo"],
+    "navbar_center": ["navbar-nav"],
+    "navbar_end": ["navbar-icon-links"],
+    "navbar_persistent": ["search-button"],
+}

masterblaster/gameaccount.py

@@ -5,8 +5,32 @@
 if TYPE_CHECKING:
     from _typeshed import SupportsRead
 
+__all__ = [
+    "GameAccount",
+]
+
 
 class GameAccount:
+    """
+    Class for GameAccount objects, related to one player
+
+    Supported games: ["Counter-Strike", "Rocket League", "Chess"]
+
+    :param id: The gameaccount id
+    :param nick: The gameaccount nickname
+    :param avatarUrl: The gameaccount avatar url
+    :param gameId: The game id
+    :param isConnected: Whether or not the gameaccount is connected
+    :param connectedAt: When the gameaccount was connected
+
+    :ivar id: The gameaccount id
+    :ivar nick: The gameaccount nickname
+    :ivar avatar_url: The gameaccount avatar url
+    :ivar gameId: The game id
+    :ivar isConnected: Whether or not the gameaccount is connected
+    :ivar connectedAt: When the gameaccount was connected
+    """
+
     def __init__(
         self,
         id: str,

masterblaster/headers.py

@@ -4,7 +4,18 @@
 from typing import Any, Iterator
 
 
+__all__ = [
+    "Header",
+]
+
+
 class Header(abc.MutableMapping):
+    """
+    Wrapper for http header-fields
+
+    :ivar fields: The header fields
+    """
+
     def __init__(self) -> None:
         self.fields: dict[str, Any] = {}
 

masterblaster/image.py

@@ -1,4 +1,16 @@
 class Image:
+    """
+    MasterBlaster Image Object
+
+    :param imageType: The type of image
+    :param imageId: The id of the image
+    :param originalImageId: The id of the original image
+
+    :ivar type: The type of image
+    :ivar id: The id of the image
+    :ivar original_id: The id of the original image
+    """
+
     def __init__(self, imageType: int, imageId: str, originalImageId: str) -> None:
         self.type: int = imageType
         self.id: str = imageId

masterblaster/masterblaster.py

@@ -6,8 +6,28 @@
 
 BASE = "https://app.masterblaster.gg/api"
 
+__all__ = [
+    "MasterBlaster",
+]
+
 
 class MasterBlaster:
+    """
+    MasterBlaster is the main class for interacting with the MasterBlaster API
+
+    :param access_token: The access token for the organization
+    :param org_name: The name of the organization
+
+    :ivar id: The id of the organization
+    :ivar name: The name of the organization
+    :ivar is_admin: Whether or not the current token is an admin for the organization
+    :ivar access_token: The access token for the organization
+    :ivar members: A list of all members in the organization
+    :ivar images: A list of all images in the organization
+    :ivar headers: The headers used for the session
+
+    """
+
     def __init__(self, access_token: Optional[str], org_name: str) -> None:
         self.id: str = ""
         self.name: str = org_name
@@ -19,10 +39,16 @@ def __init__(self, access_token: Optional[str], org_name: str) -> None:
         self._session: aiohttp.ClientSession | None = None
 
     async def __aenter__(self) -> "MasterBlaster":
+        """
+        :meta private:
+        """
         await self._setup(self.name)
         return self
 
     async def __aexit__(self, exc_type, exc_value, traceback) -> None:
+        """
+        :meta private:
+        """
         await self._session.close()
 
     async def teardown(self) -> None:
@@ -42,7 +68,7 @@ async def teardown(self) -> None:
     @classmethod
     async def create(cls, access_token: str, org_name: str) -> "MasterBlaster":
         """
-        Create a new MasterBlaster instance
+        Create a new fully setup MasterBlaster instance
 
         Parameters
         ----------
@@ -54,13 +80,15 @@ async def create(cls, access_token: str, org_name: str) -> "MasterBlaster":
         Returns
         -------
         MasterBlaster
-            A new MasterBlaster instance
         """
         self = cls(access_token, org_name)
         await self._setup(org_name)
         return self
 
     async def _setup(self, org_name: str) -> "MasterBlaster":
+        """
+        :meta private:
+        """
         if not self._session.closed:
             await self._session.close()
         self.name = org_name
@@ -139,6 +167,9 @@ async def change_org(self, org_name: str) -> None:
         await self._setup(org_name)
 
     async def _set_org_id(self, org_name: str) -> None:
+        """
+        :meta private:
+        """
         orgs = await self.get_all_orgs()
         for org in orgs:
             # Parse out the one we want
@@ -151,14 +182,23 @@ async def _set_org_id(self, org_name: str) -> None:
             raise Exception(f"Organization '{org_name}' not found for current token")
 
     async def _set_org_members(self) -> None:
+        """
+        :meta private:
+        """
         org_info = await self.get_org(self.id)
         self.members = [Member(**member) for member in org_info["members"]]
 
     async def _set_org_images(self) -> None:
+        """
+        :meta private:
+        """
         org_info = await self.get_org(self.id)
         self.images = [Image(**image) for image in org_info["images"]]
 
     async def _update_members(self) -> None:
+        """
+        :meta private:
+        """
         members = await self.get_org(self.id)
         self.members = [Member(**member) for member in members["members"]]
 
@@ -179,6 +219,9 @@ async def get_members(self) -> list[Member]:
         return self.members
 
     async def _update_images(self) -> None:
+        """
+        :meta private:
+        """
         images = await self.get_org(self.id)
         self.images = [Image(**image) for image in images["images"]]
 

masterblaster/member.py

@@ -8,8 +8,32 @@
 if TYPE_CHECKING:
     from _typeshed import SupportsRead
 
+__all__ = [
+    "Member",
+]
+
 
 class Member:
+    """
+    Class for organization members
+
+    :param player: The player object
+    :param email: The member email
+    :param name: The member name
+    :param playerId: The player id
+    :param role: The member role
+    :param addedAt: When the member was added
+    :param invitedAt: When the member was invited
+
+    :ivar player: The member's related player object
+    :ivar email: The member's email-address
+    :ivar name: The member's name
+    :ivar player_id: The member's player id
+    :ivar role: The member's role
+    :ivar added_at: When the member was added
+    :ivar invited_at: When the member was invited
+    """
+
     def __init__(
         self,
         player: dict,

masterblaster/player.py

@@ -2,8 +2,23 @@
 from dateutil import parser
 from .gameaccount import GameAccount
 
+__all__ = [
+    "Player",
+]
+
 
 class Player:
+    """
+    Class for Player objects, related to zero or more gameaccounts
+
+    :param id: The masterblaster id of the player
+    :param nickName: The internal nickname of the player
+    :param avatarUrl: The avatar url of the player
+    :param registered: When the player was registered
+    :param isProfileComplete: Whether or not the player has completed their profile
+    :param gameAccounts: List of gameaccounts related to the player
+    """
+
     def __init__(
         self,
         id: str,

pyproject.toml

@@ -31,3 +31,4 @@ jupyter = "^1.0.0"
 sphinx-autoapi = "^2.1.1"
 sphinx-rtd-theme = "^1.3.0"
 myst-nb = "^0.17.2"
+pydata-sphinx-theme = "^0.13.3"