adding mkdocs

src/musicbrainzapi/wordcloud/__init__.py

@@ -20,59 +20,57 @@ if typing.TYPE_CHECKING:
     import PIL.PngImagePlugin.PngImageFile
 
 
+# pylint:disable=line-too-long
 class LyricsWordcloud:
-    """Create a word cloud from Lyrics.
+    """
+    Create a Wordcloud from Lyrics.
+
+    The docstring continues here.
+
+    It should contain:
+
+    - something
+    - something else
+
+    Args:
+        pillow_img (PIL.PngImagePlugin.PngImageFile): pillow image of the word
+            cloud base
+        all_albums_lyrics_count (dict): A dictionary containing the lyrics from
+           a whole album.
+
+    !!! Attributes
+
+        - `pillow_img` (pillow): A pillow image.
+
+    Anything else can go here.
+
+    Example:
+        Here is how you can use it
 
-    Attributes
-    ----------
-    all_albums_lyrics_count : list
-        List of all albums + track lyrics counted by each word
-    char_mask : np.array
-        numpy array containing data for the word cloud image
-    freq : collections.Counter
-        Counter object containing counts for all words across all tracks
-    lyrics_list : list
-        List of all words from all lyrics across all tracks.
-    pillow_img : PIL.PngImagePlugin.PngImageFile
-        pillow image of the word cloud base
-    wc : wordcloud.WordCloud
-        WordCloud object
     """
 
     def __init__(
         self,
-        pillow_img: 'PIL.PngImagePlugin.PngImageFile',
-        all_albums_lyrics_count: 'Lyrics.all_albums_lyrics_count',
+        pillow_img: "PIL.PngImagePlugin.PngImageFile",
+        all_albums_lyrics_count: "Lyrics.all_albums_lyrics_count",
     ):
-        """
-        Create a worcloud object.
-
-        Parameters
-        ----------
-        pillow_img : PIL.PngImagePlugin.PngImageFile
-            pillow image of the word cloud base
-        all_albums_lyrics_count : Lyrics.all_albums_lyrics_count
-            List of all albums + track lyrics counted by each word
-        """
         self.pillow_img = pillow_img
         self.all_albums_lyrics_count = all_albums_lyrics_count
+        self.test = []
 
     @classmethod
     def use_microphone(
-        cls, all_albums_lyrics_count: 'Lyrics.all_albums_lyrics_count',
+        cls, all_albums_lyrics_count: "Lyrics.all_albums_lyrics_count",
     ) -> LyricsWordcloud:
-        """
-        Class method to instantiate with a microphone base image.
+        """Create a LyricsWordcloud using a microphone as a base image.
 
-        Parameters
-        ----------
-        all_albums_lyrics_count : Lyrics.all_albums_lyrics_count
-            List of all albums + track lyrics counted by each word
+        Args:
+            all_albums_lyrics_count (dict): A dictionary containing the lyrics from a whole album.
+        Returns:
+            LyricsWordcloud: Instance of itself with a micrphone image loaded in.
 
         """
-        mic_resource = resources.path(
-            'musicbrainzapi.wordcloud.resources', 'mic.png'
-        )
+        mic_resource = resources.path("musicbrainzapi.wordcloud.resources", "mic.png")
         with mic_resource as m:
             mic_img = Image.open(m)
 
@@ -80,15 +78,20 @@ class LyricsWordcloud:
 
     @staticmethod
     def generate_grey_colours(
-        # word: str,
-        # font_size: str,
-        # random_state: typing.Union[None, bool] = None,
-        *args,
-        **kwargs,
-    ) -> str:
-        """Static method to generate a random grey colour."""
-        colour = f'hsl(0, 0%, {random.randint(60, 100)}%)'
-        return colour
+            # word: str,
+            # font_size: str,
+            # random_state: typing.Union[None, bool] = None,
+            *args,
+            **kwargs,
+        ) -> str:
+        """Static method to return a random grey color.
+
+        Returns:
+            str: A random grey colour in `hsl` form.
+
+            Can be any grey colour.
+        """
+        return f"hsl(0, 0%, {random.randint(60, 100)}%)"
 
     def _get_lyrics_list(self) -> None:
         """Gets all words from lyrics in a single list + cleans them.
@@ -101,12 +104,8 @@ class LyricsWordcloud:
                         for word in track:
                             for _ in range(1, word[1]):
                                 cleaned = word[0]
-                                cleaned = re.sub(
-                                    r'[\(\[].*?[\)\]]', ' ', cleaned
-                                )
-                                cleaned = re.sub(
-                                    r'[^a-zA-Z0-9\s]', '', cleaned
-                                )
+                                cleaned = re.sub(r"[\(\[].*?[\)\]]", " ", cleaned)
+                                cleaned = re.sub(r"[^a-zA-Z0-9\s]", "", cleaned)
                                 cleaned = cleaned.lower()
                                 if cleaned in STOPWORDS:
                                     continue
@@ -129,11 +128,7 @@ class LyricsWordcloud:
         """Generates a word cloud
         """
         self.wc = WordCloud(
-            max_words=150,
-            width=1500,
-            height=1500,
-            mask=self.char_mask,
-            random_state=1,
+            max_words=150, width=1500, height=1500, mask=self.char_mask, random_state=1,
         ).generate_from_frequencies(self.freq)
         return self
 
@@ -141,18 +136,16 @@ class LyricsWordcloud:
         """Plots the wordcloud and sets matplotlib options.
         """
         plt.imshow(
-            self.wc.recolor(
-                color_func=self.generate_grey_colours, random_state=3
-            ),
-            interpolation='bilinear',
+            self.wc.recolor(color_func=self.generate_grey_colours, random_state=3),
+            interpolation="bilinear",
         )
-        plt.axis('off')
+        plt.axis("off")
         return self
 
     # def show_word_cloud(self):
-        # """Shows the word cloud.
-        # """
-        # plt.show()
+    # """Shows the word cloud.
+    # """
+    # plt.show()
 
     def create_word_cloud(self) -> None:
         """Creates a word cloud