Added docstrings

app/generate_podcast.py

@@ -14,6 +14,33 @@
 
 
 def generate_podcast(name, desc, topics, adverts):
+    """
+    Generate a podcast with the provided details.
+
+    Args:
+        name (str): Name of the podcast.
+        desc (str): Description of the podcast.
+        topics (list): List of topics to be covered in the podcast.
+        adverts (list): List of advertisements to be included in the podcast.
+
+    Returns:
+        Tuple[str, str]: A tuple containing the filenames of the generated audio file (MP3)
+        and script file (TXT).
+
+    The function generates podcast scripts based on provided topics and advertisements, creates an
+    introductory and outroductory script, and combines them into an MP3 audio file. The generated
+    script and audio files are saved with unique filenames including the current date and a
+    randomly generated UUID.
+
+    Note:
+        - The generated files are stored in the 'app/downloads/' directory.
+        - External libraries such as llmOS_stuff, string_stuff, date_stuff, and edge_tts_stuff
+          are assumed to be defined elsewhere.
+
+    Example:
+        audio_file, script_file = generate_podcast("My Podcast", "Description", ["Topic 1", "Topic 2"],
+                                                   ["Advert 1", "Advert 2"])
+    """
     current_date = date_stuff.get_tomorrows_date_for_file_names()
     unique_id = uuid.uuid4()
 

app/keepyourmouthshut.py

@@ -8,11 +8,32 @@
 
 @app.route("/")
 def index():
+    """
+    Route handler for the root URL ("/").
+
+    Returns:
+        flask.Response: The response object containing the rendered "index.html" template.
+    """
     return render_template("index.html")
 
 
 @app.route("/generate", methods=["POST"])
 def generate():
+    """
+    Route handler for generating a podcast based on user-submitted form data.
+
+    This route expects a POST request with the following form parameters:
+    - 'name': Name of the podcast.
+    - 'desc': Description of the podcast.
+    - 'topic1', 'topic2', 'topic3': Topics to be covered in the podcast.
+    - 'advert1', 'advert2': Advertisements to be included in the podcast.
+
+    The generated podcast includes the provided information and is packaged into a ZIP file
+    containing both an MP3 audio file and a corresponding text transcript file.
+
+    Returns:
+        flask.Response: A response object containing the ZIP file for download.
+    """
     name = request.form["name"]
     desc = request.form["desc"]
     topic1 = request.form["topic1"]

app/utils/date_stuff.py

@@ -2,4 +2,18 @@
 
 
 def get_tomorrows_date_for_file_names() -> str:
+    """
+    Get the formatted string representation of tomorrow's date.
+
+    Returns:
+        str: A string representing tomorrow's date in the format "YYYY-MM-DD".
+
+    This function utilizes the `datetime` module to obtain tomorrow's date and returns
+    a string in the specified format. It is intended for use in generating file names
+    with dates, ensuring uniqueness.
+
+    Example:
+        tomorrow_date_str = get_tomorrows_date_for_file_names()
+        # Output: "2022-01-08" (assuming today is "2022-01-07")
+    """
     return datetime.now().strftime("%Y-%m-%d")

app/utils/edge_tts_stuff.py

@@ -5,11 +5,45 @@
 
 
 async def converter(text, filename):
+    """
+    Asynchronously convert text to an audio segment and save it as an MP3 file.
+
+    Args:
+        text (str): The text to be converted to audio.
+        filename (str): The desired filename for the resulting MP3 file.
+
+    This function utilizes an asynchronous approach to convert the given text into an audio
+    segment using the `edge_tts.Communicate` method with a specified voice. The resulting
+    audio segment is then saved as an MP3 file in the 'app/cache/' directory.
+
+    Note:
+        - This function should be awaited when called.
+
+    Example:
+        await converter("Hello, world!", "output.mp3")
+    """
     audio_segment = edge_tts.Communicate(text, VOICE)
     await audio_segment.save("app/cache/" + filename)
 
 
 def convert_text_to_mp3(text, filename):
+    """
+    Convert text to an audio segment and save it as an MP3 file.
+
+    Args:
+        text (str): The text to be converted to audio.
+        filename (str): The desired filename for the resulting MP3 file.
+
+    This function is a synchronous wrapper for the asynchronous `converter` function. It
+    sets up an event loop, runs the asynchronous function, and then closes the loop.
+
+    Note:
+        - This function is suitable for use in synchronous code.
+        - For asynchronous contexts, it is recommended to use the `converter` function directly.
+
+    Example:
+        convert_text_to_mp3("Hello, world!", "output.mp3")
+    """
     loop = asyncio.new_event_loop()
     asyncio.set_event_loop(loop)
 

app/utils/llmOS_stuff.py

@@ -10,6 +10,28 @@
 
 
 def generate_response(system_prompt, user_prompt):
+    """
+    Generate a response using the Mistral-7B instructive language model.
+
+    Args:
+        system_prompt (str): System prompt for instructing the language model.
+        user_prompt (str): User prompt to guide the language model's response.
+
+    Returns:
+        str: The generated response from the language model.
+
+    This function sends a request to the Mistral-7B instructive language model API with the
+    provided system and user prompts. The generated response is extracted from the API
+    response and returned.
+
+    Note:
+        - The Mistral-7B API key (llmos_api_key) and API endpoint (url) should be defined
+          before calling this function.
+
+    Example:
+        response = generate_response("Provide information about", "What is the process of")
+        print(response)
+    """
     payload = {
         "model": "mistral-7b-instruct",
         "messages": [

app/utils/string_stuff.py

@@ -1,2 +1,19 @@
 def script_header(string):
+    """
+    Generate a formatted script header.
+
+    Args:
+        string (str): The content to be included in the script header.
+
+    Returns:
+        str: A formatted string representing the script header.
+
+    This function takes a string as input and formats it into a script header by
+    capitalizing the input string, adding a colon, and placing it on a new line.
+
+    Example:
+        header = script_header("intro")
+        print(header)
+        # Output: "\nINTRO:"
+    """
     return f"\n{string.upper()}:\n"