Improve FileStation and update docs parser and docstrings

docs_parser.py

@@ -2,6 +2,7 @@
 import re
 import sys
 import warnings
+from docstring_parser import Docstring
 import yaml
 from os import listdir
 from os.path import isfile, join
@@ -285,12 +286,32 @@ def parse_method_api(method_name: str, file_content: str) -> str:
         section = header('h4', 'Internal API')
         section += div(text(api_name, ['code']), 'padding', 'left', 'md')
     else:
-        warnings.warn(
-            f'Method {method_name} seems to not be directly calling any internal API, this is expected for utility methods that use other calls in the class.', UserWarning)
+        print(f'Method {method_name} seems to not be directly calling any internal API, this is expected for utility methods that use other calls in the class. You can ignore this message if this is the case.')
     return section + NEWLINE
 
 
-def gen_header(class_name: str, docstring: str, classes: list[str]) -> str:
+def parse_parameters(docstring: Docstring, method: dict | None) -> str:
+    parameters = ''
+    if docstring.params:
+        parameters = header('h4' if method else 'h3', 'Parameters')
+        parameters_body = ''
+        for param in docstring.params:
+            # no need to validate str if we are parsing class params
+            if method:
+                validate_str(method['name'] + ' - params',
+                             [param.arg_name, param.type_name, param.description])
+            parameters_body += text(param.arg_name or '', ['bold', 'italic'])
+            parameters_body += text(param.type_name or '',
+                                    ['code'], newline=True)
+            parameters_body += text(dedup_newlines(
+                param.description or ''), newline=True)
+            parameters_body += NEWLINE
+        parameters += div(content=parameters_body,
+                          spacing='padding', side='left', size='md')
+    return parameters
+
+
+def gen_header(class_name: str, docstring: Docstring, classes: list[str]) -> str:
     content = ''
     docs_status = ''
 
@@ -304,13 +325,24 @@ def gen_header(class_name: str, docstring: str, classes: list[str]) -> str:
     content += status_disclaimer(docs_status)
     content += header('h2', 'Overview')
 
-    docstring = docstring.replace(
+    docstring_content = text(docstring.short_description or '', newline=True)
+    docstring_content += NEWLINE
+    docstring_content += text(docstring.long_description or '', newline=True)
+
+    docstring_content = docstring_content.replace(
         'Supported methods:', header('h3', 'Supported methods'))
-    docstring = docstring.replace('Getters', text('Getters', ['bold']))
-    docstring = docstring.replace('Setters', text('Setters', ['bold']))
-    docstring = docstring.replace('Actions', text('Actions', ['bold']))
+    docstring_content = docstring_content.replace(
+        'Getters', text('Getters', ['bold']))
+    docstring_content = docstring_content.replace(
+        'Setters', text('Setters', ['bold']))
+    docstring_content = docstring_content.replace(
+        'Actions', text('Actions', ['bold']))
+
+    if docstring.params:
+        docstring_content += NEWLINE + \
+            parse_parameters(docstring=docstring, method=None)
 
-    content += docstring + '\n'
+    content += docstring_content + NEWLINE
     content += header('h2', 'Methods')
 
     return content
@@ -338,21 +370,7 @@ def gen_method(method: dict, file_content: str) -> str:
     # TODO: refactor, synology_api.core_package.Package.easy_install don't have internal API, but it has a docstring.
     internal_api = parse_method_api(method['name'], file_content)
 
-    parameters = ''
-    if docstring.params:
-        parameters = header('h4', 'Parameters')
-        parameters_body = ''
-        for param in docstring.params:
-            validate_str(method['name'] + ' - params',
-                         [param.arg_name, param.type_name, param.description])
-            parameters_body += text(param.arg_name or '', ['bold', 'italic'])
-            parameters_body += text(param.type_name or '',
-                                    ['code'], newline=True)
-            parameters_body += text(dedup_newlines(
-                param.description or ''), newline=True)
-            parameters_body += NEWLINE
-        parameters += div(content=parameters_body,
-                          spacing='padding', side='left', size='md')
+    parameters = parse_parameters(docstring, method)
 
     returns = ''
     if docstring.returns:
@@ -442,7 +460,7 @@ def main():
                     class_item['name'], file_content, file_name)
                 doc_content += gen_header(
                     class_item['name'],
-                    class_item['docstring_text'],
+                    class_item['docstring'],
                     classes=classes_names
                 )
 

docs_status.yaml

@@ -7,61 +7,61 @@
 - ActiveBackupMicrosoft:
     status: finished
 - AdminConsole:
-    status: not_started
+    status: partial
 - AudioStation:
-    status: not_started
+    status: partial
 - BaseApi:
     status: finished
 - Backup:
     status: partial
 - Certificate:
-    status: not_started
+    status: partial
 - CloudSync:
     status: finished
 - DhcpServer:
-    status: not_started
+    status: partial
 - DirectoryServer:
     status: finished
 - Docker:
     status: finished
 - DownloadStation:
-    status: not_started
+    status: partial
 - EventScheduler:
     status: finished
 - FileStation:
-    status: not_started
+    status: partial
 - Group:
     status: finished
 - KeyManagerStore:
     status: not_started
 - KeyManagerAutoKey:
     status: not_started
 - LogCenter:
-    status: not_started
+    status: partial
 - NoteStation:
-    status: not_started
+    status: partial
 - OAuth:
-    status: not_started
+    status: partial
 - Package:
     status: partial
 - Photos:
     status: partial
 - SecurityAdvisor:
-    status: not_started
+    status: partial
 - Share:
     status: partial
 - SharePermission:
     status: partial
 - Snapshot:
     status: finished
 - SurveillanceStation:
-    status: not_started
+    status: partial
 - SysInfo:
-    status: not_started
+    status: partial
 - TaskScheduler:
     status: finished
 - UniversalSearch:
-    status: not_started
+    status: partial
 - USBCopy:
     status: finished
 - User:

documentation/docs/apis/classes/abm.md

@@ -9,27 +9,28 @@ title: ✅ ActiveBackupMicrosoft
 
 # ActiveBackupMicrosoft
 ## Overview
-Active Backup for Microsoft 365 Implementation.
-
-    ### Supported methods
-
-    - **Getters** :
-        - Get all tasks info
-        - Get task settings
-        - Get task logs
-        - Get package logs
-        - Get worker settings
-
-    - **Setters** :
-        - Set worker settings
-        - Set task schedule policy
-        - Set task retention policy
-
-    - **Actions** :
-        - Run backup
-        - Cancel backup
-        - Delete task
-        - Relink task
+Active Backup for Microsoft 365 Implementation.  
+
+### Supported methods
+
+- **Getters** :
+    - Get all tasks info
+    - Get task settings
+    - Get task logs
+    - Get package logs
+    - Get worker settings
+
+- **Setters** :
+    - Set worker settings
+    - Set task schedule policy
+    - Set task retention policy
+
+- **Actions** :
+    - Run backup
+    - Cancel backup
+    - Delete task
+    - Relink task  
+
 ## Methods
 ### `get_tasks`
 Retrieve all tasks.  

documentation/docs/apis/classes/audiostation.md

@@ -10,11 +10,14 @@ title: 🚧 AudioStation
 # AudioStation
 :::warning
 
-This API is not documented yet.
+This API is partially documented or under construction.
 
 :::
 ## Overview
-A class to interact with Synology AudioStation API.
+A class to interact with Synology AudioStation API.  
+
+
+
 ## Methods
 ### `get_info`
 Retrieve general information about the AudioStation service.  

documentation/docs/apis/classes/cloud_sync.md

@@ -9,46 +9,47 @@ title: ✅ CloudSync
 
 # CloudSync
 ## Overview
-Cloud Sync API implementation.
-
-   This API provides the functionality to get information related to the package settings and current connections and tasks.
-   It also provides functionalities to set most of the settings for tasks and package configuration, as well as manage the current syncing processes.
-
-   Due to the vast amount of public clouds available in the project, the API was not tested for every cloud scenario, so some params request may be missing in specific not tested clouds.
-
-   The tested clouds so far are:
-   - Google Drive
-   - OneDrive
-   - DropBox
-   - Amazon S3 (task creation)
-
-   ### Supported methods
-
-        - **Getters** :
-           - Get package settings
-           - Get connections
-           - Get connections settings
-           - Get connection information
-           - Get connection auth information
-           - Get connection logs
-           - Get connection tasks
-           - Get task filters
-           - Get task synced remote directories
-           - Get recently modified & currently syncing files
-        - **Setters** :
-           - Set package settings
-           - Set relink behavior
-           - Set connection settings
-           - Set connection schedule settings
-           - Set task settings
-           - Set task filters
-        - **Actions** :
-           - Pause connection
-           - Resume connection
-           - Delete connection
-           - Delete task
-           - Validate task settings
-           - Create S3 task
+Cloud Sync API implementation.  
+
+This API provides the functionality to get information related to the package settings and current connections and tasks.
+It also provides functionalities to set most of the settings for tasks and package configuration, as well as manage the current syncing processes.
+
+Due to the vast amount of public clouds available in the project, the API was not tested for every cloud scenario, so some params request may be missing in specific not tested clouds.
+
+The tested clouds so far are:
+- Google Drive
+- OneDrive
+- DropBox
+- Amazon S3 (task creation)
+
+### Supported methods
+
+     - **Getters** :
+        - Get package settings
+        - Get connections
+        - Get connections settings
+        - Get connection information
+        - Get connection auth information
+        - Get connection logs
+        - Get connection tasks
+        - Get task filters
+        - Get task synced remote directories
+        - Get recently modified & currently syncing files
+     - **Setters** :
+        - Set package settings
+        - Set relink behavior
+        - Set connection settings
+        - Set connection schedule settings
+        - Set task settings
+        - Set task filters
+     - **Actions** :
+        - Pause connection
+        - Resume connection
+        - Delete connection
+        - Delete task
+        - Validate task settings
+        - Create S3 task  
+
 ## Methods
 ### `get_pkg_config`
 Retrieve package settings.  

documentation/docs/apis/classes/core_active_backup.md

@@ -9,33 +9,34 @@ title: ✅ ActiveBackupBusiness
 
 # ActiveBackupBusiness
 ## Overview
-Active Backup for Business API Implementation.
-
-    This class provides methods to interact with the Active Backup for Business package.
-
-    ### Supported methods
-
-        - **Getters** :
-            - Get package settings
-            - Get tasks information
-            - Get tasks versions information
-            - Get devices information
-            - Get devices transfer size
-            - Get hypervisors information
-            - Get package / devices / tasks logs
-            - Get task history
-            - Get task result details
-            - Get storage information
-        - **Setters** :
-            - Set maximum concurrent devices
-            - Set retention policy execution time
-            - Set bandwidth control
-            - Set use package certificate
-        - **Actions** :
-            - Run backup
-            - Cancel backup
-            - Remove task
-            - Remove version
+Active Backup for Business API Implementation.  
+
+This class provides methods to interact with the Active Backup for Business package.
+
+### Supported methods
+
+    - **Getters** :
+        - Get package settings
+        - Get tasks information
+        - Get tasks versions information
+        - Get devices information
+        - Get devices transfer size
+        - Get hypervisors information
+        - Get package / devices / tasks logs
+        - Get task history
+        - Get task result details
+        - Get storage information
+    - **Setters** :
+        - Set maximum concurrent devices
+        - Set retention policy execution time
+        - Set bandwidth control
+        - Set use package certificate
+    - **Actions** :
+        - Run backup
+        - Cancel backup
+        - Remove task
+        - Remove version  
+
 ## Methods
 ### `get_settings`
 Get the package settings including certificate information.