Converted comments in dir Cura/cura/API to rst style

Converted doxygen style comments to reStructuredText style in the files found in Cura/cura/API directory recursively  using the script dox_2_rst.py (provided in the Uranium repo). Comments were manually checked and changed if needed.

Comments from the hidden attributes in the class CuraAPI (_acount, _backups, _interface) were moved to the public property getters, so they docstrings are exposed to the user.

cura/API/Account.py

@@ -16,18 +16,23 @@ if TYPE_CHECKING:
 i18n_catalog = i18nCatalog("cura")
 
 
-##  The account API provides a version-proof bridge to use Ultimaker Accounts
-#
-#   Usage:
-#       ``from cura.API import CuraAPI
-#       api = CuraAPI()
-#       api.account.login()
-#       api.account.logout()
-#       api.account.userProfile # Who is logged in``
-#
 class Account(QObject):
-    # Signal emitted when user logged in or out.
+    """The account API provides a version-proof bridge to use Ultimaker Accounts
+    
+    Usage:
+
+    .. code-block:: python
+
+      from cura.API import CuraAPI
+      api = CuraAPI()
+      api.account.login()
+      api.account.logout()
+      api.account.userProfile    Who is logged in``
+    """
+
     loginStateChanged = pyqtSignal(bool)
+    """Signal emitted when user logged in or out"""
+
     accessTokenChanged = pyqtSignal()
 
     def __init__(self, application: "CuraApplication", parent = None) -> None:
@@ -65,9 +70,10 @@ class Account(QObject):
     def _onAccessTokenChanged(self):
         self.accessTokenChanged.emit()
 
-    ## Returns a boolean indicating whether the given authentication is applied against staging or not.
     @property
     def is_staging(self) -> bool:
+        """Indication whether the given authentication is applied against staging or not."""
+
         return "staging" in self._oauth_root
 
     @pyqtProperty(bool, notify=loginStateChanged)
@@ -113,10 +119,10 @@ class Account(QObject):
     def accessToken(self) -> Optional[str]:
         return self._authorization_service.getAccessToken()
 
-    #   Get the profile of the logged in user
-    #   @returns None if no user is logged in, a dict containing user_id, username and profile_image_url
     @pyqtProperty("QVariantMap", notify = loginStateChanged)
     def userProfile(self) -> Optional[Dict[str, Optional[str]]]:
+        """None if no user is logged in otherwise the logged in  user as a dict containing containing user_id, username and profile_image_url """
+
         user_profile = self._authorization_service.getUserProfile()
         if not user_profile:
             return None

cura/API/Backups.py

@@ -8,28 +8,37 @@ if TYPE_CHECKING:
     from cura.CuraApplication import CuraApplication
 
 
-##  The back-ups API provides a version-proof bridge between Cura's
-#   BackupManager and plug-ins that hook into it.
-#
-#   Usage:
-#       ``from cura.API import CuraAPI
-#       api = CuraAPI()
-#       api.backups.createBackup()
-#       api.backups.restoreBackup(my_zip_file, {"cura_release": "3.1"})``
 class Backups:
+    """The back-ups API provides a version-proof bridge between Cura's
+    
+    BackupManager and plug-ins that hook into it.
+    
+    Usage:
+
+    .. code-block:: python
+
+       from cura.API import CuraAPI
+       api = CuraAPI()
+       api.backups.createBackup()
+       api.backups.restoreBackup(my_zip_file, {"cura_release": "3.1"})``
+    """
 
     def __init__(self, application: "CuraApplication") -> None:
         self.manager = BackupsManager(application)
 
-    ##  Create a new back-up using the BackupsManager.
-    #   \return Tuple containing a ZIP file with the back-up data and a dict
-    #   with metadata about the back-up.
     def createBackup(self) -> Tuple[Optional[bytes], Optional[Dict[str, Any]]]:
+        """Create a new back-up using the BackupsManager.
+        
+        :return: Tuple containing a ZIP file with the back-up data and a dict with metadata about the back-up.
+        """
+
         return self.manager.createBackup()
 
-    ##  Restore a back-up using the BackupsManager.
-    #   \param zip_file A ZIP file containing the actual back-up data.
-    #   \param meta_data Some metadata needed for restoring a back-up, like the
-    #   Cura version number.
     def restoreBackup(self, zip_file: bytes, meta_data: Dict[str, Any]) -> None:
+        """Restore a back-up using the BackupsManager.
+        
+        :param zip_file: A ZIP file containing the actual back-up data.
+        :param meta_data: Some metadata needed for restoring a back-up, like the Cura version number.
+        """
+
         return self.manager.restoreBackup(zip_file, meta_data)

cura/API/Interface/Settings.py

@@ -7,32 +7,43 @@ if TYPE_CHECKING:
     from cura.CuraApplication import CuraApplication
 
 
-##  The Interface.Settings API provides a version-proof bridge between Cura's
-#   (currently) sidebar UI and plug-ins that hook into it.
-#
-#   Usage:
-#       ``from cura.API import CuraAPI
-#       api = CuraAPI()
-#       api.interface.settings.getContextMenuItems()
-#       data = {
-#           "name": "My Plugin Action",
-#           "iconName": "my-plugin-icon",
-#           "actions": my_menu_actions,
-#           "menu_item": MyPluginAction(self)
-#       }
-#       api.interface.settings.addContextMenuItem(data)``
-
 class Settings:
+    """The Interface.Settings API provides a version-proof bridge
+     between Cura's
+    
+    (currently) sidebar UI and plug-ins that hook into it.
+    
+    Usage:
+
+    .. code-block:: python
+
+       from cura.API import CuraAPI
+       api = CuraAPI()
+       api.interface.settings.getContextMenuItems()
+       data = {
+       "name": "My Plugin Action",
+       "iconName": "my-plugin-icon",
+       "actions": my_menu_actions,
+       "menu_item": MyPluginAction(self)
+       }
+       api.interface.settings.addContextMenuItem(data)``
+    """
 
     def __init__(self, application: "CuraApplication") -> None:
         self.application = application
 
-    ##  Add items to the sidebar context menu.
-    #   \param menu_item dict containing the menu item to add.
     def addContextMenuItem(self, menu_item: dict) -> None:
+        """Add items to the sidebar context menu.
+        
+        :param menu_item: dict containing the menu item to add.
+        """
+
         self.application.addSidebarCustomMenuItem(menu_item)
 
-    ##  Get all custom items currently added to the sidebar context menu.
-    #   \return List containing all custom context menu items.
     def getContextMenuItems(self) -> list:
+        """Get all custom items currently added to the sidebar context menu.
+        
+        :return: List containing all custom context menu items.
+        """
+
         return self.application.getSidebarCustomMenuItems()

cura/API/Interface/__init__.py

@@ -9,18 +9,22 @@ if TYPE_CHECKING:
     from cura.CuraApplication import CuraApplication
 
 
-##  The Interface class serves as a common root for the specific API
-#   methods for each interface element.
-#
-#   Usage:
-#       ``from cura.API import CuraAPI
-#       api = CuraAPI()
-#       api.interface.settings.addContextMenuItem()
-#       api.interface.viewport.addOverlay() # Not implemented, just a hypothetical
-#       api.interface.toolbar.getToolButtonCount() # Not implemented, just a hypothetical
-#       # etc.``
-
 class Interface:
+    """The Interface class serves as a common root for the specific API
+    
+    methods for each interface element.
+    
+    Usage:
+
+    .. code-block:: python
+
+       from cura.API import CuraAPI
+       api = CuraAPI()
+       api.interface.settings.addContextMenuItem()
+       api.interface.viewport.addOverlay()    # Not implemented, just a hypothetical
+       api.interface.toolbar.getToolButtonCount()   #  Not implemented, just a hypothetical
+       # etc
+    """
 
     def __init__(self, application: "CuraApplication") -> None:
         # API methods specific to the settings portion of the UI

cura/API/__init__.py

@@ -12,13 +12,14 @@ if TYPE_CHECKING:
     from cura.CuraApplication import CuraApplication
 
 
-##  The official Cura API that plug-ins can use to interact with Cura.
-#
-#   Python does not technically prevent talking to other classes as well, but
-#   this API provides a version-safe interface with proper deprecation warnings
-#   etc. Usage of any other methods than the ones provided in this API can cause
-#   plug-ins to be unstable.
 class CuraAPI(QObject):
+    """The official Cura API that plug-ins can use to interact with Cura.
+    
+    Python does not technically prevent talking to other classes as well, but this API provides a version-safe
+    interface with proper deprecation warnings etc. Usage of any other methods than the ones provided in this API can
+    cause plug-ins to be unstable.
+    """
+
 
     # For now we use the same API version to be consistent.
     __instance = None  # type: "CuraAPI"
@@ -39,13 +40,10 @@ class CuraAPI(QObject):
     def __init__(self, application: Optional["CuraApplication"] = None) -> None:
         super().__init__(parent = CuraAPI._application)
 
-        # Accounts API
         self._account = Account(self._application)
 
-        # Backups API
         self._backups = Backups(self._application)
 
-        # Interface API
         self._interface = Interface(self._application)
 
     def initialize(self) -> None:
@@ -53,12 +51,18 @@ class CuraAPI(QObject):
 
     @pyqtProperty(QObject, constant = True)
     def account(self) -> "Account":
+        """Accounts API"""
+
         return self._account
 
     @property
     def backups(self) -> "Backups":
+        """Backups API"""
+
         return self._backups
 
     @property
     def interface(self) -> "Interface":
+        """Interface API"""
+
         return self._interface