Merge branch 'fp-ns-type' of https://github.com/fabric-testbed/fabric…

…testbed-extensions into fp-ns-type

CHANGELOG.md

@@ -48,6 +48,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   [#242](https://github.com/fabric-testbed/fabrictestbed-extensions/issues/242),
   [#243](https://github.com/fabric-testbed/fabrictestbed-extensions/issues/243),
   PR [#251](https://github.com/fabric-testbed/fabrictestbed-extensions/pull/251))
+- Module docstrings (PR
+  [#256](https://github.com/fabric-testbed/fabrictestbed-extensions/pull/256))
 
 ### Changed
 

docs/source/component.rst

@@ -1,9 +1,9 @@
-Component
+component
 =========
 
 .. automodule:: fabrictestbed_extensions.fablib.component
    :members:
 
 .. autoclass:: fabrictestbed_extensions.fablib.component.Component
    :members:
-   :special-members: __init__, __str__
+   :special-members: __str__

docs/source/conf.py

@@ -42,6 +42,9 @@
 # This pattern also affects html_static_path and html_extra_path.
 exclude_patterns = []
 
+# Use __init__ method’s docstrings in class docs.  Other options are
+# "class" and "both".
+autoclass_content = "init"
 
 # -- Options for HTML output -------------------------------------------------
 

docs/source/fablib.rst

@@ -1,9 +1,9 @@
-FablibManager
-=============
+fablib
+======
 
 .. automodule:: fabrictestbed_extensions.fablib.fablib
    :members:
 
 .. autoclass:: fabrictestbed_extensions.fablib.fablib.FablibManager
    :members:
-   :special-members: __init__, __str__
+   :special-members: __str__

docs/source/facility_port.rst

@@ -1,9 +1,9 @@
-FacilityPort
-============
+facility_port
+=============
 
 .. automodule:: fabrictestbed_extensions.fablib.facility_port
    :members:
 
 .. autoclass:: fabrictestbed_extensions.fablib.facility_port.FacilityPort
    :members:
-   :special-members: __init__, __str__
+   :special-members: __str__

docs/source/interface.rst

@@ -1,9 +1,9 @@
-Interface
+interface
 =========
 
 .. automodule:: fabrictestbed_extensions.fablib.interface
    :members:
 
 .. autoclass:: fabrictestbed_extensions.fablib.interface.Interface
    :members:
-   :special-members: __init__, __str__
+   :special-members: __str__

docs/source/network_service.rst

@@ -1,9 +1,9 @@
-NetworkService
-==============
+network_service
+===============
 
 .. automodule:: fabrictestbed_extensions.fablib.network_service
    :members:
 
 .. autoclass:: fabrictestbed_extensions.fablib.network_service.NetworkService
    :members:
-   :special-members: __init__, __str__
+   :special-members: __str__

docs/source/node.rst

@@ -1,9 +1,9 @@
-Node
+node
 ====
 
 .. automodule:: fabrictestbed_extensions.fablib.node
    :members:
 
 .. autoclass:: fabrictestbed_extensions.fablib.node.Node
    :members:
-   :special-members: __init__, __str__
+   :special-members: __str__

docs/source/resources.rst

@@ -1,9 +1,9 @@
-Resources
+resources
 =========
 
 .. automodule:: fabrictestbed_extensions.fablib.resources
    :members:
 
 .. autoclass:: fabrictestbed_extensions.fablib.resources.Resources
    :members:
-   :special-members: __init__, __str__
+   :special-members: __str__

docs/source/slice.rst

@@ -1,9 +1,9 @@
-Slice
+slice
 =====
 
 .. automodule:: fabrictestbed_extensions.fablib.slice
    :members:
 
 .. autoclass:: fabrictestbed_extensions.fablib.slice.Slice
    :members:
-   :special-members: __init__, __str__
+   :special-members: __str__

fabrictestbed_extensions/fablib/component.py

@@ -22,6 +22,21 @@
 # SOFTWARE.
 #
 # Author: Paul Ruth ([email protected])
+
+"""
+Methods to work with FABRIC components_.
+
+.. _components: https://learn.fabric-testbed.net/knowledge-base/glossary/#component
+
+You normally would not create :class:`Component` objects directly with
+a constructor call; they are created when you invoke
+:py:func:`fabrictestbed_extensions.fablib.node.Node.add_component()`,
+like so::
+
+    node.add_component(model='NVME_P4510', name="nvme1")
+    node.add_component(model='NIC_Basic', name="nic1")
+"""
+
 from __future__ import annotations
 
 import json
@@ -310,12 +325,15 @@ def new_component(
 
     def __init__(self, node: Node = None, fim_component: FimComponent = None):
         """
-        Not intended for API use
+        Typically invoked when you add a component to a ``Node``.
 
-        Constructor. Sets the FIM component and fablib node to the inputted values.
+        .. note ::
+
+            ``Component`` constructer is not meant to be directly used.
 
         :param node: the fablib node to build the component on
         :type node: Node
+
         :param fim_component: the FIM component this object represents
         :type fim_component: FIMComponent
         """

fabrictestbed_extensions/fablib/fablib.py

@@ -22,6 +22,45 @@
 # SOFTWARE.
 #
 # Author: Paul Ruth ([email protected])
+
+"""
+This module exports a :class:`FablibManager` class and a
+:class:`fablib` class available, which allows you to, among other
+things:
+
+    - Query FABRIC testbed resources.
+
+    - Create, modify, and delete slices.
+
+    - Manage the SSH keys you use with FABRIC.
+
+    - etc.
+
+In most cases you would need to create a :class:`FablibManager`
+instance to interact with FABRIC testbed::
+
+    from fabrictestbed_extensions.fablib.fablib import FablibManager
+
+    fablib = FablibManager()
+
+    slice = fablib.new_slice(name="MySlice")
+    node = slice.add_node(name="node1")
+    slice.submit();
+
+See FABRIC project's `Jupyter notebook examples <examples>`_ for more
+complete code samples.
+
+.. note::
+
+    Some configuration in the form of a configuration file, environment
+    variables, or :class:`FablibManager` constructor parameters is
+    required for the library to work.  Please see the FABRIC project's
+    `documentation on getting started <learn>`_.
+
+.. _learn: https://learn.fabric-testbed.net/article-categories/getting-started/
+.. _examples: https://github.com/fabric-testbed/jupyter-examples/
+"""
+
 from __future__ import annotations
 
 import datetime
@@ -55,6 +94,10 @@
 
 
 class fablib:
+    """
+    Convenience static methods to work with FABRIC testbed.
+    """
+
     default_fablib_manager = None
 
     @staticmethod
@@ -526,13 +569,52 @@ def __init__(
         **kwargs,
     ):
         """
-        Constructor. Builds FablibManager.  Tries to get configuration from:
-
-         - constructor parameters (high priority)
-         - fabric_rc file (middle priority)
-         - environment variables (low priority)
-         - defaults (if needed and possible)
-
+        ``FablibManager`` is the main interface to FABRIC services.
+
+        A ``FablibManager`` object is used to query FABRIC testbed for
+        available resources, create and configure slices, manage SSH
+        keys in nodes in slices and FABRIC's bastion host, etc.  This
+        requires some configuration, which is gathered from:
+
+            - constructor parameters (high priority)
+
+            - a configuration file (medium priority)
+
+            - environment variables (low priority)
+
+            - defaults (if needed, and when possible)
+
+        Typically you would use the configuration file located at
+        ``"${HOME}/work/fabric_config/fabric_rc"``, and/or environment
+        variables.
+
+        :param fabric_rc: Path to fablib configuration file.  Defaults
+            to ``"${HOME}/work/fabric_config/fabric_rc"``.
+        :param credmgr_host: Name of credential manager host.
+        :param orchestrator_host: Name of FABRIC orchestrator host.
+        :param fabric_token: Path to the file that contains your
+            FABRIC auth token.
+        :param project_id: Your FABRIC project ID, obtained from
+            https://cm.fabric-testbed.net/, usually via FABRIC portal.
+        :param bastion_username: Your username on FABRIC bastion host,
+            obtained from FABRIC portal.
+        :param bastion_key_filename: Path to your bastion SSH key.
+        :param log_file: Path where fablib logs are written; defaults
+            to ``"/tmp/fablib/fablib.log"``.
+        :param log_level: Level of detail in the logs written.
+            Defaults to ``"DEBUG"``; other possible log levels are
+            ``"INFO"``, ``"WARNING"``, ``"ERROR"``, and
+            ``"CRITICAL"``, in reducing order of verbosity.
+        :param data_dir: directory for fablib to store temporary data.
+        :param output: Format of fablib output; can be either
+            ``"pandas"`` or ``"text"``.  Defaults to ``"pandas"`` in a
+            Jupyter notebook environment; ``"text"`` otherwise.
+        :param execute_thread_pool_size: Number of worker threads in
+            the thread pool fablib uses to execute commands in nodes.
+            Defaults to 64.
+        :param offline: Avoid using FABRIC services when initializing.
+            This is ``False`` by default, and set to ``True`` only in
+            some unit tests.
         """
         super().__init__(
             fabric_rc=fabric_rc,

fabrictestbed_extensions/fablib/facility_port.py

@@ -22,6 +22,13 @@
 # SOFTWARE.
 #
 # Author: Paul Ruth ([email protected])
+
+"""
+This module contains methods to work with FABRIC `facility ports`_.
+
+.. _`facility ports`: https://learn.fabric-testbed.net/knowledge-base/glossary/#facility_port
+"""
+
 from __future__ import annotations
 
 import json
@@ -45,13 +52,11 @@ class FacilityPort:
 
     def __init__(self, slice: Slice, fim_interface: FimInterface):
         """
-        Sets the fablib slice and FIM node based on arguments.
-
         :param slice: the fablib slice to have this node on
         :type slice: Slice
 
-        :param node: the FIM node that this Node represents
-        :type node: Node
+        :param fim_interface:
+        :type fim_interface: FimInterface
         """
         super().__init__()
         self.fim_interface = fim_interface

fabrictestbed_extensions/fablib/interface.py

@@ -22,6 +22,11 @@
 # SOFTWARE.
 #
 # Author: Paul Ruth ([email protected])
+
+"""
+Methods to work with FABRIC network interfaces.
+"""
+
 from __future__ import annotations
 
 import ipaddress
@@ -54,11 +59,15 @@ class Interface:
 
     def __init__(self, component: Component = None, fim_interface: FimInterface = None):
         """
-        Constructor. Sets keyword arguments as instance fields.
+        .. note::
+
+            Objects of this class are not created directly.
 
         :param component: the component to set on this interface
         :type component: Component
-        :param fim_interface: the FABRIC information model interface to set on this fablib interface
+
+        :param fim_interface: the FABRIC information model interface
+            to set on this fablib interface
         :type fim_interface: FimInterface
         """
         super().__init__()

fabrictestbed_extensions/fablib/network_service.py

@@ -22,6 +22,13 @@
 # SOFTWARE.
 #
 # Author: Paul Ruth ([email protected])
+
+"""
+Methods to work with FABRIC `network services`_.
+
+.. _`network services`: https://learn.fabric-testbed.net/knowledge-base/glossary/#network_service
+"""
+
 from __future__ import annotations
 
 import logging
@@ -572,14 +579,16 @@ def __init__(
         self, slice: Slice = None, fim_network_service: FimNetworkService = None
     ):
         """
-        Not inteded for API use.
+        .. note::
 
-        Constructor. Sets the fablib slice and the FABRIC network service.
+            Not inteded for API use.
 
         :param slice: the fablib slice to set as instance state
         :type slice: Slice
-        :param fim_network_service: the FIM network service to set as instance state
-        :type fim_network_service: FIMNetworkService
+
+        :param fim_network_service: the FIM network service to set as
+            instance state
+        :type fim_network_service: FimNetworkService
         """
         super().__init__()
         self.fim_network_service = fim_network_service