Merge pull request #347 from fabric-testbed/312.facility-port-docstrings

Add missing docstrings in `facility_port` module

CHANGELOG.md

@@ -17,6 +17,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Remove duplicate Node.delete() method (Issue [#321](https://github.com/fabric-testbed/fabrictestbed-extensions/issues/321))
 
 ## Added
+- Missing docstrings in facility_port module (Issue [#312](https://github.com/fabric-testbed/fabrictestbed-extensions/issues/312))
 - Missing docstrings in node module (Issue [#318](https://github.com/fabric-testbed/fabrictestbed-extensions/issues/318))
 
 ## [1.6.4] - 2024-03-05

docs/source/facility_port.rst

@@ -6,4 +6,5 @@ facility_port
 
 .. autoclass:: fabrictestbed_extensions.fablib.facility_port.FacilityPort
    :members:
+   :no-index:
    :special-members: __str__

docs/source/index.rst

@@ -118,10 +118,10 @@ above.  Currently, contents of the configuration file will override
 values set using environment variables.
 
 
-FABLib classes
+FABLib modules
 --------------
 
-Most of FABLib's functionality comes wrapped in these classes:
+FABLib functionality is made available in these modules:
 
 .. toctree::
    :maxdepth: 1

fabrictestbed_extensions/fablib/__init__.py

@@ -1 +0,0 @@
-

fabrictestbed_extensions/fablib/facility_port.py

@@ -47,6 +47,10 @@
 
 
 class FacilityPort:
+    """
+    A class for working with FABRIC facility ports.
+    """
+
     fim_interface = None
     slice = None
 
@@ -75,14 +79,23 @@ def __str__(self):
         return tabulate(table)
 
     def toJson(self):
+        """
+        Return a JSON representation of the facility port.
+        """
         return json.dumps(self.toDict(), indent=4)
 
     def get_pretty_name_dict(self):
+        """
+        Return a mapping used when rendering table headers.
+        """
         return {
             "name": "Name",
         }
 
     def toDict(self, skip=[]):
+        """
+        Return a Python `dict` representation of the facility port.
+        """
         return {"name": str(self.get_name())}
 
     def get_template_context(self):
@@ -98,6 +111,9 @@ def render_template(self, input_string):
     def show(
         self, fields=None, output=None, quiet=False, colors=False, pretty_names=True
     ):
+        """
+        Get a human-readable representation of the facility port.
+        """
         data = self.toDict(pretty_names=True)
 
         # fields = ["Name",
@@ -120,20 +136,34 @@ def show(
         return table
 
     def get_fim_interface(self) -> FimNode:
+        """
+        .. warning::
+            Not recommended for most users.
+
+        Gets the node's FABRIC Information Model (fim) object.  This
+        method is used to access data at a lower level than FABlib.
+        """
         return self.fim_interface
 
     def get_model(self) -> str:
+        """
+        Get fablib model name for the facility port.
+        """
         return "Facility_Port"
 
     def get_name(self) -> str:
         """
         Gets the name of the FABRIC node.
+
         :return: the name of the node
         :rtype: String
         """
         return self.get_fim_interface().name
 
     def get_site(self) -> str:
+        """
+        Gets the site associated with the facility port.
+        """
         return self.fim_interface.site
 
     @staticmethod
@@ -144,6 +174,18 @@ def new_facility_port(
         vlan: Union[str, list] = None,
         bandwidth: int = 10,
     ):
+        """
+        Create a new facility port.
+
+        You might want to :py:meth:`Slice.add_facility_port()`, in
+        most cases.
+
+        :param Slice: Slice associated with the facility port.
+        :param name: name of the facility port.
+        :param site: site associated with the facility port.
+        :param vlan: VLAN.
+        :param bandwidth: bandwidth to be used, in Gbps.
+        """
         if isinstance(vlan, list):
             interfaces = []
             index = 1