Add more docs

dorianim · dorianim · commit 2ece10c69570 · 2021-07-20T11:51:33.000+02:00
diff --git a/.vscode/extensions.json b/.vscode/extensions.json
@@ -0,0 +1,6 @@
+{
+    "recommendations": [
+        "njpwerner.autodocstring",
+        "ms-python.python"
+    ]
+}
diff --git a/.vscode/settings.json b/.vscode/settings.json
@@ -0,0 +1,3 @@
+{
+    "autoDocstring.docstringFormat": "sphinx"
+}
diff --git a/docs/index.rst b/docs/index.rst
@@ -33,3 +33,8 @@ Particularly, some `appliances (Proxmox, XCP-ng and KVM) are prepared <https://d
    python/shares.rst
    python/computer.rst
    python/config.rst
+   python/environment.rst
+   python/fileHelper.rst
+   python/gpo.rst
+   python/hooks.rst
+   python/imageHelper.rst
diff --git a/docs/python/config.rst b/docs/python/config.rst
@@ -3,7 +3,7 @@ Module: config
 
 This module is used to deal with all config files:
 
-* `/etc/linuxmusterLinuxclient7/network.conf`
+* `/etc/linuxmuster-linuxclient7/network.conf`
 
 Members
 =======
diff --git a/docs/python/environment.rst b/docs/python/environment.rst
@@ -0,0 +1,9 @@
+Module: environment
+*******************
+
+This module is used to export and unset environment variables during the onLogin/logon hook.
+
+Members
+=======
+.. automodule:: linuxmusterLinuxclient7.environment
+   :members:
diff --git a/docs/python/fileHelper.rst b/docs/python/fileHelper.rst
@@ -0,0 +1,9 @@
+Module: fileHelper
+******************
+
+This module is used to deal files.
+
+Members
+=======
+.. automodule:: linuxmusterLinuxclient7.fileHelper
+   :members:
diff --git a/docs/python/gpo.rst b/docs/python/gpo.rst
@@ -0,0 +1,9 @@
+Module: gpo
+***********
+
+This module is used to deal with Microsoft GPOs.
+
+Members
+=======
+.. automodule:: linuxmusterLinuxclient7.gpo
+   :members:
diff --git a/docs/python/hooks.rst b/docs/python/hooks.rst
@@ -0,0 +1,9 @@
+Module: hooks
+*************
+
+This module is used to deal with local hookdirs in `/etc/linuxmuster-linuxclient7` and the sysvol.
+
+Members
+=======
+.. automodule:: linuxmusterLinuxclient7.hooks
+   :members:
diff --git a/docs/python/imageHelper.rst b/docs/python/imageHelper.rst
@@ -0,0 +1,9 @@
+Module: imageHelper
+*******************
+
+This module is used to prepare a client for imaging.
+
+Members
+=======
+.. automodule:: linuxmusterLinuxclient7.imageHelper
+   :members:
diff --git a/usr/lib/python3/dist-packages/linuxmusterLinuxclient7/config.py b/usr/lib/python3/dist-packages/linuxmusterLinuxclient7/config.py
@@ -3,7 +3,7 @@
 
 def network():
     """
-    Get the network configuration in `/etc/linuxmusterLinuxclient7/network.conf`
+    Get the network configuration in `/etc/linuxmuster-linuxclient7/network.conf`
 
     :return: Tuple (success, dict of keys)
     :rtype: tuple
@@ -30,7 +30,7 @@ def network():
 
 def writeNetworkConfig(newNetworkConfig):
     """
-    Write the network configuration in `/etc/linuxmusterLinuxclient7/network.conf`
+    Write the network configuration in `/etc/linuxmuster-linuxclient7/network.conf`
 
     :param newNetworkConfig: The new config
     :type newNetworkConfig: dict
@@ -64,7 +64,7 @@ def writeNetworkConfig(newNetworkConfig):
 
 def upgrade():
     """
-    Upgrade the format of the network configuration in `/etc/linuxmusterLinuxclient7/network.conf`
+    Upgrade the format of the network configuration in `/etc/linuxmuster-linuxclient7/network.conf`
     This is done automatically on package upgrades.
 
     :return: True or False
diff --git a/usr/lib/python3/dist-packages/linuxmusterLinuxclient7/environment.py b/usr/lib/python3/dist-packages/linuxmusterLinuxclient7/environment.py
@@ -2,6 +2,14 @@
 from linuxmusterLinuxclient7 import constants, user, logging
 
 def export(keyValuePair):
+    """
+    Export an environment variable
+
+    :param keyValuePair: Key value pair in format `key=value`
+    :type keyValuePait: str
+    :return: True or False
+    :rtype: bool
+    """
     logging.debug("Saving export '{}' to tmp file".format(keyValuePair))
     
     envList = keyValuePair.split("=")
@@ -10,9 +18,17 @@ def export(keyValuePair):
     
     return _appendToTmpEnvFile("export", keyValuePair)
 
-def unset(keyValuePair):
-    logging.debug("Saving unset '{}' to tmp file".format(keyValuePair))
-    return _appendToTmpEnvFile("unset", keyValuePair)
+def unset(key):
+    """
+    Unset a previously exported environment variable
+
+    :param key: The key to unset
+    :type key: str
+    :return: True or False
+    :rtype: bool
+    """
+    logging.debug("Saving unset '{}' to tmp file".format(key))
+    return _appendToTmpEnvFile("unset", key)
 
 # --------------------
 # - Helper functions -
diff --git a/usr/lib/python3/dist-packages/linuxmusterLinuxclient7/fileHelper.py b/usr/lib/python3/dist-packages/linuxmusterLinuxclient7/fileHelper.py
@@ -2,6 +2,16 @@
 from linuxmusterLinuxclient7 import logging
 
 def removeLinesInFileContainingString(filePath, forbiddenStrings):
+    """
+    Remove all lines containing a given string form a file.
+
+    :param filePath: The path to the file
+    :type filePath: str
+    :param forbiddenStrings: The string to search for
+    :type forbiddenStrings: str
+    :return: True on success, False otherwise
+    :rtype: bool
+    """
     if not isinstance(forbiddenStrings, list):
         forbiddenStrings = [forbiddenStrings]
     
@@ -33,6 +43,14 @@ def removeLinesInFileContainingString(filePath, forbiddenStrings):
     return True
 
 def deleteFile(filePath):
+    """
+    Delete a file
+
+    :param filePath: The path of the file
+    :type filePath: str
+    :return: True on success, False otherwise
+    :rtype: bool
+    """
     try:
         if os.path.exists(filePath):
             os.unlink(filePath)
@@ -43,6 +61,16 @@ def deleteFile(filePath):
         return False
 
 def deleteFilesWithExtension(directory, extension):
+    """
+    Delete all files with a given extension in a given directory.
+
+    :param directory: The path of the directory
+    :type directory: str
+    :param extension: The file extension
+    :type extension: str
+    :return: True on success, False otherwise
+    :rtype: bool
+    """
     if directory.endswith("/"):
         directory = directory[:-1]
         
@@ -61,13 +89,30 @@ def deleteFilesWithExtension(directory, extension):
     return True
 
 def deleteDirectory(directory):
+    """
+    Recoursively delete a directory.
+
+    :param directory: The path of the directory
+    :type directory: bool
+    :return: True on success, False otherwise
+    :rtype: bool
+    """
     try:
         shutil.rmtree(directory)
     except:
         return False
     return True
 
 def deleteAllInDirectory(directory):
+    """
+    Delete all files in a given directory
+
+    :param directory: The path of the directory
+    :type directory: str
+    :return: True on success, False otherwise
+    :rtype: bool
+    """    
+
     if directory.endswith("/"):
         directory = directory[:-1]
         
diff --git a/usr/lib/python3/dist-packages/linuxmusterLinuxclient7/gpo.py b/usr/lib/python3/dist-packages/linuxmusterLinuxclient7/gpo.py
@@ -8,6 +8,12 @@
 from linuxmusterLinuxclient7 import logging, constants, config, user, ldapHelper, shares, computer, printers
 
 def processAllPolicies():
+    """
+    Process all applicable policies (equivalent to gpupdate on windows)
+
+    :return: True on success, False otherwise
+    :rtype: bool
+    """    
     rc, policyDnList = _findApplicablePolicies()
     if not rc:
         logging.error("Error when loading applicable GPOs")
diff --git a/usr/lib/python3/dist-packages/linuxmusterLinuxclient7/hooks.py b/usr/lib/python3/dist-packages/linuxmusterLinuxclient7/hooks.py
@@ -7,11 +7,25 @@
 from linuxmusterLinuxclient7 import logging, constants, user, config, computer, environment, setup, shares
 
 class Type(Enum):
+    """
+    Enum containing all hook types
+    """
+
     Boot = 0
+    """The onBoot hook
+    """
     Shutdown = 1
+    """The on Shutdown hook
+    """
     LoginAsRoot = 2
+    """The onLoginAsRoot hook
+    """
     Login = 3
+    """The onLogin hook
+    """
     SessionStarted = 4
+    """The onSession started hook
+    """
     LogoutAsRoot = 5
     LoginLogoutAsRoot = 6
 
@@ -30,6 +44,12 @@ class Type(Enum):
 }
 
 def runLocalHook(hookType):
+    """
+    Run all scripts in a local hookdir
+
+    :param hookType: The type of hook to run
+    :type hookType: hooks.Type
+    """    
     logging.info("=== Running local hook on{0} ===".format(hookType.name))
     hookDir = _getLocalHookDir(hookType)
     if os.path.exists(hookDir):
@@ -41,6 +61,12 @@ def runLocalHook(hookType):
 
 
 def runRemoteHook(hookType):
+    """
+    Run hookscript from sysvol
+
+    :param hookType: The type of hook to run
+    :type hookType: hooks.Type
+    """    
     logging.info("=== Running remote hook on{0} ===".format(hookType.name))
     rc, hookScripts = _getRemoteHookScripts(hookType)
 
@@ -52,16 +78,33 @@ def runRemoteHook(hookType):
     logging.info("===> Finished running remote hook on{0} ===".format(hookType.name))
 
 def runHook(hookType):
+    """
+    Executes hooks.runLocalHook() and hooks.runRemoteHook()
+
+    :param hookType: The type of hook to run
+    :type hookType: hooks.Type
+    """    
     runLocalHook(hookType)
     runRemoteHook(hookType)
 
 def getLocalHookScript(hookType):
-    return "{0}/on{1}".format(constants.scriptDir,hookType.name)
+    """Get the path of a local hookscript
 
-def createSessionAutostartFile():
-    pass
+    :param hookType: The type of hook script to get the path for
+    :type hookType: hooks.Type
+    :return: The path
+    :rtype: str
+    """
+    return "{0}/on{1}".format(constants.scriptDir,hookType.name)
 
 def shouldHooksBeExecuted(overrideUsername=None):
+    """Check if hooks should be executed
+
+    :param overrideUsername: Override the username to check, defaults to None
+    :type overrideUsername: str, optional
+    :return: True if hooks should be executed, fale otherwise
+    :rtype: bool
+    """
     # check if linuxmuster-linuxclient7 is setup
     if not setup.isSetup():
         logging.info("==== Linuxmuster-linuxclient7 is not setup, exiting ====")
diff --git a/usr/lib/python3/dist-packages/linuxmusterLinuxclient7/imageHelper.py b/usr/lib/python3/dist-packages/linuxmusterLinuxclient7/imageHelper.py
@@ -2,6 +2,13 @@
 from linuxmusterLinuxclient7 import logging, setup, realm, user, constants, printers, fileHelper
 
 def prepareForImage(unattended=False):
+    """Prepare the computer for creating an image
+
+    :param unattended: If set to True, all questions will be answered with yes, defaults to False
+    :type unattended: bool, optional
+    :return: True on success, False otherwise
+    :rtype: bool
+    """
     logging.info("#### Image preparation ####")
 
     try:

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+{`
	`2`	`+ "autoDocstring.docstringFormat": "sphinx"`
	`3`	`+}`