Lots of new documentation

trussme/report.py

@@ -6,6 +6,14 @@
 
 
 def generate_summary(the_truss) -> str:
+    """
+    Generate a summary of the analysis.
+
+    :param the_truss: The truss to be summarized
+    :type the_truss: Truss
+    :return: A string containing the summary
+    :rtype: str
+    """
     summary = "# SUMMARY OF ANALYSIS\n"
     summary += (
         "- The truss has a mass of "
@@ -140,6 +148,14 @@ def generate_summary(the_truss) -> str:
 
 
 def generate_instantiation_information(the_truss) -> str:
+    """
+    Generate a summary of the instantiation information.
+
+    :param the_truss: The truss to be reported on
+    :type the_truss: Truss
+    :return: A report of the instantiation information
+    :rtype: str
+    """
     instantiation = "# INSTANTIATION INFORMATION\n"
 
     instantiation += trussme.visualize.plot_truss(the_truss) + "\n"

trussme/truss.py

@@ -23,6 +23,21 @@
 
 @dataclasses.dataclass
 class Goals:
+    """
+    A simple class to represents goals for truss design.
+
+    :param min_fos_total: Minimum total FOS for the truss, defaults to 1.0
+    :type min_fos_total: float
+    :param min_fos_buckling: Minimum buckling FOS for the truss, defaults to 1.0
+    :type min_fos_buckling: float
+    :param min_fos_yielding: Minimum yielding FOS for the truss, defaults to 1.0
+    :type min_fos_yielding: float
+    :param max_mass: Maximum mass for the truss, defaults to inf
+    :type max_mass: float
+    :param max_deflection: Maximum deflection for the truss, defaults to inf
+    :type max_deflection: float
+    """
+
     min_fos_total: float = 1.0
     min_fos_buckling: float = 1.0
     min_fos_yielding: float = 1.0
@@ -31,6 +46,10 @@ class Goals:
 
 
 class Truss(object):
+    """
+    The truss class
+    """
+
     def __init__(self):
         # Make a list to store members in
         self.members: list[Member] = []
@@ -43,39 +62,87 @@ def __init__(self):
 
     @property
     def number_of_members(self) -> int:
+        """
+        Number of members in the truss, updated automatically
+
+        :return: The number of members in the truss
+        :rtype: int
+        """
         return len(self.members)
 
     @property
     def number_of_joints(self) -> int:
+        """
+        Number of joints in the truss, updated automatically
+
+        :return: The number of joints in the truss
+        :rtype: int
+        """
         return len(self.joints)
 
     @property
     def mass(self) -> float:
+        """
+        Total mass of the truss, updated automatically
+
+        :return: Mass of the truss
+        :rtype: float
+        """
         mass = 0
         for m in self.members:
             mass += m.mass
         return mass
 
     @property
     def fos_yielding(self) -> float:
+        """
+        Smallest yielding FOS in the truss
+
+        :return: Minimum FOS for yielding
+        :rtype: float
+        """
         return min([m.fos_yielding for m in self.members])
 
     @property
     def fos_buckling(self) -> float:
+        """
+        Smallest buckling FOS in the truss
+
+        :return: Minimum FOS for buckling
+        :rtype: float
+        """
         return min(
             [m.fos_buckling if m.fos_buckling > 0 else 10000 for m in self.members]
         )
 
     @property
     def fos_total(self) -> float:
+        """
+        Smallest FOS in the truss
+
+        :return: Minimum FOS
+        :rtype: float
+        """
         return min(self.fos_buckling, self.fos_yielding)
 
     @property
     def deflection(self) -> float:
+        """
+        Largest single joint deflection in the truss
+
+        :return: Largest deflection in the truss
+        :rtype: float
+        """
         return max([numpy.linalg.norm(joint.deflections) for joint in self.joints])
 
     @property
     def materials(self) -> list[Material]:
+        """
+        List of unique materials used in the truss
+
+        :return: List of materials
+        :rtype: list[Material]
+        """
         material_library: list[Material] = [member.material for member in self.members]
         return list({v["name"]: v for v in material_library}.values())
 
@@ -219,7 +286,11 @@ def calc_fos(self):
             )
 
     @property
-    def report(self):
+    def report(self) -> str:
+        """
+        :return: A string containing a full report on the truss
+        :rtype: str
+        """
         self.calc_fos()
 
         report_string = report.generate_summary(self) + "\n"
@@ -228,11 +299,24 @@ def report(self):
 
         return report_string
 
-    def report_to_md(self, file_name: str):
+    def report_to_md(self, file_name: str) -> None:
+        """
+        Writes a report in Markdown format
+        :param file_name: A string with the name of the file
+        :type file_name: str
+        :return: None
+        """
         with open(file_name, "w") as f:
             f.write(self.report)
 
-    def to_json(self, file_name: str):
+    def to_json(self, file_name: str) -> None:
+        """
+        Saves the truss to a JSON file
+        :param file_name: The filename to use for the truss file
+        :type file_name: str
+        :return: None
+        """
+
         class JointEncoder(json.JSONEncoder):
             def default(self, obj):
                 if isinstance(obj, Joint):
@@ -275,7 +359,13 @@ def default(self, obj):
         with open(file_name, "w") as f:
             json.dump(combined, f, indent=4)
 
-    def to_trs(self, file_name: str):
+    def to_trs(self, file_name: str) -> None:
+        """
+        Saves the truss to a .trs file
+        :param file_name: The filename to use for the truss file
+        :type file_name: str
+        :return: None
+        """
         with open(file_name, "w") as f:
             # Do materials
             for material in self.materials:
@@ -348,6 +438,13 @@ def to_trs(self, file_name: str):
 
 
 def read_trs(file_name: str) -> Truss:
+    """
+    Read a .trs file and return a Truss object
+    :param file_name: The name of the .trs file to be read
+    :type file_name: str
+    :return: The object loaded from the .trs file
+    :rtype: Truss
+    """
     truss = Truss()
     material_library: list[Material] = []
 
@@ -403,6 +500,13 @@ def read_trs(file_name: str) -> Truss:
 
 
 def read_json(file_name: str) -> Truss:
+    """
+    Read a JSON file and return a Truss object
+    :param file_name: The name of the JSON file to be read
+    :type file_name: str
+    :return: The object loaded from the JSON file
+    :rtype: Truss
+    """
     json_truss = json.load(open(file_name))
 
     truss = Truss()

trussme/visualize.py

@@ -5,13 +5,12 @@
 
 def plot_truss(truss, deflected_shape: bool = False) -> str:
     """Plot the truss.
-
-    Args:
-        truss (Truss): The truss to plot.
-        deflected_shape (bool, optional): Plot the deflected shape. Defaults to False.
-
-    Returns:
-        matplotlib.pyplot.Figure: The figure containing the plot.
+    :param truss: The truss to plot.
+    :type truss: Truss
+    :param deflected_shape: Plot the deflected shape. Defaults to False.
+    :type deflected_shape: bool, optional
+    :return: An svg string of the truss
+    :rtype: str
     """
     fig = matplotlib.pyplot.figure()
     ax = fig.add_subplot(