📔 update documentation & fix tracklist indexing

- Fixed tracklist indexing for album posters (#30).
- Rephrased questions in prompt.py for clarity.
- Hid module names in the documentation for cleaner output.

BeatPrints/errors.py

@@ -78,19 +78,7 @@ def __init__(self, message="Use format 'x-y' where x and y are numbers."):
         super().__init__(self.message)
 
 
-class PathNotFoundError(Exception):
-    """
-    Raised when the specified path cannot be found.
-    """
-
-    def __init__(
-        self, message="The specified path for saving the image could not be found."
-    ):
-        self.message = message
-        super().__init__(self.message)
-
-
-class ThemeNotFound(Exception):
+class ThemeNotFoundError(Exception):
     """
     Raised when the specified theme is not found or is invalid.
     """

BeatPrints/poster.py

@@ -15,7 +15,7 @@
 from . import image, write
 from .utils import filename, organize_tracks
 
-from .errors import ThemeNotFound
+from .errors import ThemeNotFoundError
 from .spotify import TrackMetadata, AlbumMetadata
 
 
@@ -100,7 +100,7 @@ def track(
 
         # Check if the theme mentioned is valid or not
         if theme not in THEMES:
-            raise ThemeNotFound
+            raise ThemeNotFoundError
 
         # Get theme colors and template for the poster
         color, template = image.get_theme(theme)
@@ -172,7 +172,7 @@ def album(
 
         # Check if the theme mentioned is valid or not
         if theme not in THEMES:
-            raise ThemeNotFound
+            raise ThemeNotFoundError
 
         # Get theme colors and template for the poster
         color, template = image.get_theme(theme)
@@ -198,11 +198,10 @@ def album(
             # Album's Tracks
             tracks = metadata.tracks
 
-            if indexing:
-                tracks = [f"{i + 1}. {track}" for i, track in enumerate(tracks)]
-
             # Organize the tracklist and render it on the poster
-            tracklist, track_widths = organize_tracks(tracks)
+            tracklist, track_widths = organize_tracks(tracks, indexing)
+
+            # Starting Position
             x, y = C_TRACKS
 
             # Render the tracklist, adjusting the position for each column

BeatPrints/utils.py

@@ -11,7 +11,29 @@
 from . import write, consts
 
 
-def organize_tracks(tracks: list) -> tuple:
+def add_flat_indexes(nlist: list) -> list:
+    """
+    Adds a flat index to each track name in a nested list.
+
+    Args:
+        nlist (list): A nested list of track names.
+
+    Returns:
+        list: The modified nested list with flat indexes added to track names.
+    """
+
+    index = 1
+
+    for idx, cols in enumerate(nlist):
+        for jdx, row in enumerate(cols):
+
+            nlist[idx][jdx] = f"{index}. {row}"
+            index += 1
+
+    return nlist
+
+
+def organize_tracks(tracks: list, indexing: bool = False) -> tuple:
     """
     Organizes tracks into columns that fit within the maximum allowed width.
 
@@ -23,18 +45,39 @@ def organize_tracks(tracks: list) -> tuple:
             - List of lists where each inner list contains a column of track names.
             - List of widths for each track column.
     """
+
+    def calculate_column_width(tracks_column: list, additional_width: int = 0):
+        """
+        Helper function to calculate the width of the longest track in a column.
+        """
+
+        tracks = max(tracks_column, key=len)
+
+        return (
+            write.calculate_text_width(tracks, write.font("Light"), consts.S_TRACKS)
+            + additional_width
+        )
+
+    additional_width = 0
+
+    # Account for the space that index numbers take
+    if indexing:
+        index = len(tracks) + 1
+
+        additional_width = write.calculate_text_width(
+            f"{index}", write.font("Light"), consts.S_TRACKS
+        )
+
     while True:
         # Split tracks into columns with a maximum of MAX_ROWS per column
         columns = [
             tracks[i : i + consts.MAX_ROWS]
             for i in range(0, len(tracks), consts.MAX_ROWS)
         ]
 
-        # Determine the width of the longest track in each column
-        max_tracks = [max(col, key=len) for col in columns]
+        # Determine the width of each column
         track_widths = [
-            write.calculate_text_width(track, write.font("Light"), consts.S_TRACKS)
-            for track in max_tracks
+            calculate_column_width(col, additional_width) for col in columns
         ]
 
         # Sum the total width and check if it fits within the allowed MAX_WIDTH
@@ -44,11 +87,15 @@ def organize_tracks(tracks: list) -> tuple:
             break  # If it fits, exit the loop
 
         else:
-            # If it doesn't fit, remove the longest track from the longest column
+            # If it doesn't fit, remove the longest track from the column with the widest width
             longest_column_index = track_widths.index(max(track_widths))
             longest_column = columns[longest_column_index]
             tracks.remove(max(longest_column, key=len))
 
+    # Add flat indexes to tracks if indexing is enabled
+    if indexing:
+        columns = add_flat_indexes(columns)
+
     return columns, track_widths
 
 

README.md

@@ -20,7 +20,7 @@
 
 ![examples](https://i.ibb.co.com/y0jKqHK/banner.png)
 
-<h3 align="center">📔 Check out the new documentation <a href="https://beatprints.readthedocs.io/en/latest/">here!</a></h3>
+<h3 align="center">📔 Check out the documentation <a href="https://beatprints.readthedocs.io/en/latest/">here!</a></h3>
 
 ## 📦 Installation
 
@@ -134,9 +134,7 @@ I wanted to make it free for everyone to print themselves, as I believe my poste
 ## ❤️  Special Thanks
 
 - A big thanks to [Spotify Poster Generator](https://github.com/AnveshakR/poster-generator/) by [@AnveshakR](https://github.com/AnveshakR) for inspiring BeatPrints with amazing ideas!  
-- Shoutout to [@Magniquick](https://github.com/Magniquick), [@Krishna-Gunjan](https://github.com/Krishna-Gunjan), and [@itsnotrin](https://github.com/itsnotrin) for their awesome contributions!  
-- Thanks to [@T-Dynamos](https://github.com/T-Dynamos) and [@cherriae](https://github.com/cherriae) for their great improvements and tweaks.  
-- A special nod to [@itsnotrin](https://github.com/itsnotrin) for helping make album poster generation possible!  
+- Shoutout to [@Magniquick](https://github.com/Magniquick), [@Krishna-Gunjan](https://github.com/Krishna-Gunjan), [@itsnotrin](https://github.com/itsnotrin), [@T-Dynamos](https://github.com/T-Dynamos), and [@cherriae](https://github.com/cherriae) for their awesome contributions!
 
 
 ## 📜 License

cli/prompt.py

@@ -184,10 +184,16 @@ def poster_features():
             qmark="💫",
         ),
         accent=questionary.confirm(
-            "• Add a color accent?", default=False, style=exutils.lavish, qmark="🌈"
+            "• Add a colored accent to the bottom?",
+            default=False,
+            style=exutils.lavish,
+            qmark="🌈",
         ),
         image=questionary.confirm(
-            "• Use a custom image?", default=False, style=exutils.lavish, qmark="🥐"
+            "• Use a custom image as the poster's cover art?",
+            default=False,
+            style=exutils.lavish,
+            qmark="🥐",
         ),
     ).unsafe_ask()
 
@@ -213,7 +219,7 @@ def create_poster():
     Create a poster based on user input.
     """
     poster_type = questionary.select(
-        "• What type of poster would you like to create?",
+        "• What do you want to create?",
         choices=["Track Poster", "Album Poster"],
         style=exutils.lavish,
         qmark="🎨",
@@ -245,7 +251,8 @@ def main():
         create_poster()
 
     except KeyboardInterrupt as e:
-        print("╰─ 👋 Alright, no problem! See you next time.")
+        exutils.clear()
+        print("👋 Alright, no problem! See you next time.")
         exit(1)
 
     except Exception as e:

docs/conf.py

@@ -11,7 +11,7 @@
 project = "BeatPrints"
 copyright = "2024, elysianmyst"
 author = "elysianmyst"
-release = "v1.1.1"
+release = "v1.1.2"
 
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
@@ -23,6 +23,9 @@
     "sphinxcontrib.video",
 ]
 
+# Hides the module name in documentation
+add_module_names = False
+
 templates_path = ["_templates"]
 exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
 

docs/guidebook/cli.rst

@@ -19,11 +19,11 @@ Windows
 
    [general]
    search_limit = 7
-   output_directory = "<path-to-save-your-posters>" 
+   output_directory = "<path-to-save-your-posters>"
 
    [credentials]
-   client_id = "your-client-id"
-   client_secret = "your-client-secret"
+   client_id = "<your-client-id>"
+   client_secret = "<your-client-secret>"
 
 Replace ``<path-to-save-your-posters>`` with the path where you'd like to save the generated posters, and fill in the ``client_id`` and ``client_secret`` with your Spotify credentials.
 

docs/guidebook/generate.rst

@@ -3,6 +3,10 @@
 
 This is a quick guide on how to generate posters using **BeatPrints** through code.
 
+.. note::
+
+   It is important for you to have the ``.env`` file in the same directory.
+
 🎷 Track Posters
 ^^^^^^^^^^^^^^^^^
 
@@ -35,6 +39,11 @@ To generate a track poster, follow the steps below.
    # Generate the track poster
    ps.track(metadata, highlighted_lyrics)
 
+.. tip::
+
+  You can create a **helper function** to display lyrics with line numbers in a nice format using `rich <https://github.com/Textualize/rich/>`_. 
+  This is just a **basic way** to generate the poster. The sky's the limit!
+
 💿️ Album Posters 
 ^^^^^^^^^^^^^^^^^
 

docs/misc/FAQ.rst

@@ -13,6 +13,10 @@ Why isn't "x" language supported in BeatPrints?
 -----------------------------------------------
 The lack of support for some languages is due to the large size of font files (around 90 MB) required for the tool. Adding more languages would significantly increase the project's size. Since Pillow (the library used for this project) doesn’t support multi-language text natively, the write.py module would need to be rewritten to handle this, which is a time-consuming task. This issue is actively being worked on, but a simple solution hasn't been found yet.
 
+Why are some tracks missing from the album posters?
+---------------------------------------------------
+Some tracks are missing from the album posters because the function organizes tracks into columns that fit within a set width, removing the longest track name if needed. Additionally, since it's not always possible to fit all tracks in order, a shuffle feature was added to randomly select tracks for the poster.
+
 I've got a really interesting idea for a feature for BeatPrints.
 ----------------------------------------------------------------
 I really appreciate that you want to contribute! Feel free to create an issue on the GitHub page. Just keep in mind that I started this project for fun, so actively maintaining it can be tough for me. I’m not always able to dedicate a lot of time, but I truly appreciate all ideas and contributions, and I’ll try my best to work on it when I can. Your suggestions are always welcome!

docs/reference/errors.rst

@@ -3,3 +3,4 @@
 
 .. automodule:: BeatPrints.errors
    :members:
+   :member-order: bysource

docs/reference/index.rst

@@ -5,7 +5,7 @@ Reference
 
 .. toctree::
    :maxdepth: 1
-  
+
    spotify
    lyrics
    poster

docs/reference/lyrics.rst

@@ -3,3 +3,4 @@
 
 .. automodule:: BeatPrints.lyrics
    :members: Lyrics
+   :member-order: bysource

docs/reference/poster.rst

@@ -3,3 +3,4 @@
 
 .. automodule:: BeatPrints.poster
    :members: Poster
+   :member-order: bysource

docs/reference/spotify.rst

@@ -3,3 +3,4 @@
 
 .. automodule:: BeatPrints.spotify
    :members: Spotify
+   :member-order: bysource