Add more docstrings

app.py

@@ -1,3 +1,9 @@
+"""The app.py used with streamlit
+
+This ties together the different parts of the app.
+
+"""
+
 import streamlit as st
 
 from start import start_input_form

edit.py

@@ -1,3 +1,29 @@
+"""The editing page of the app
+
+This is the meat of the application. On the sidebar, the content of the model
+card is displayed in the form of editable fields. On the right side, the
+rendered model card is shown.
+
+In the side bar, users can:
+
+- edit the title and content of existing sections
+- delete sections
+- add new sections below the current section
+- add new figures below the current section
+
+Moreover, each action results in a "task" that is tracked in the task state. A
+task has a "do" and an "undo" method. This allows us to provide "undo" and
+"redo" features to the app, making it easier for users to experiment and deal
+with errors. The "reset" button undoes all the tasks, leading back to the
+initial model card.
+
+When the user is finished, there is a "save" button that downloads the model
+card. They can also click "delete" to start over again, leading them to the
+start page.
+
+"""
+
+
 from __future__ import annotations
 
 import reprlib

start.py

@@ -1,3 +1,15 @@
+"""Start page of the app
+
+This page is used to initialize a model card that is either:
+
+1. based on the skops template
+2. empty
+3. loads an existing model card
+
+Optionally, users can add a model file, data, requirements, and choose a task.
+
+"""
+
 import glob
 import io
 import os

tasks.py

@@ -1,3 +1,8 @@
+"""Functionality around tasks
+
+Tasks are used to implement "undo" and "redo" functionality.
+
+"""
 from __future__ import annotations
 
 from pathlib import Path
@@ -9,9 +14,7 @@ from streamlit.runtime.uploaded_file_manager import UploadedFile
 
 
 class Task:
-    def __init__(self, model_card: card.Card) -> None:
-        self.model_card = model_card
-
+    """(Abstract) base class for tasks"""
     def do(self) -> None:
         raise NotImplementedError
 
@@ -20,6 +23,7 @@ class Task:
 
 
 class TaskState:
+    """Tracking the state of tasks"""
     def __init__(self) -> None:
         self.done_list: list[Task] = []
         self.undone_list: list[Task] = []
@@ -51,6 +55,7 @@ class TaskState:
 
 
 class AddSectionTask(Task):
+    """Add a new text section"""
     def __init__(
         self,
         model_card: card.Card,
@@ -72,6 +77,7 @@ class AddSectionTask(Task):
 
 
 class AddFigureTask(Task):
+    """Add a new figure section"""
     def __init__(
         self,
         model_card: card.Card,
@@ -94,6 +100,12 @@ class AddFigureTask(Task):
 
 
 class DeleteSectionTask(Task):
+    """Delete a section
+
+    The section is not completely removed from the underlying data structure,
+    but only turned invisible.
+
+    """
     def __init__(
         self,
         model_card: card.Card,
@@ -110,6 +122,7 @@ class DeleteSectionTask(Task):
 
 
 class UpdateSectionTask(Task):
+    """Change the title or content of a text section"""
     def __init__(
         self,
         model_card: card.Card,
@@ -140,6 +153,7 @@ class UpdateSectionTask(Task):
 
 
 class UpdateFigureTask(Task):
+    """Change the title or image of a figure section"""
     def __init__(
         self,
         model_card: card.Card,

utils.py

@@ -1,3 +1,5 @@
+"""Utility functions for the app"""
+
 from __future__ import annotations
 
 import base64