Merge pull request #136 from Peefy/refactor-python-api-and-docs

refactor: python api code examples

Author: Peefy

python/kcl_lib/api/service.py

@@ -50,14 +50,15 @@
 class API:
     """KCL APIs
 
-    Examples
-    --------
+    ## Examples
+
+    Python Code
+
     ```python
     import kcl_lib.api as api
-    # Call the `exec_program` method with appropriate arguments
     args = api.ExecProgram_Args(k_filename_list=["a.k"])
-    # Usage
     api = api.API()
+
     result = api.exec_program(args)
     print(result.yaml_result)
     ```
@@ -78,10 +79,9 @@ def parse_program(self, args: ParseProgram_Args) -> ParseProgram_Result:
 
         ```python
         schema AppConfig:
-            replicas: int
-
+           replicas: int
         app: AppConfig {
-            replicas: 2
+           replicas: 2
         }
         ```
 
@@ -109,7 +109,6 @@ def exec_program(self, args: ExecProgram_Args) -> ExecProgram_Result:
         ```python
         schema AppConfig:
             replicas: int
-
         app: AppConfig {
             replicas: 2
         }
@@ -129,7 +128,6 @@ def exec_program(self, args: ExecProgram_Args) -> ExecProgram_Result:
 
         ```python
         import kcl_lib.api as api
-
         try:
             args = api.ExecProgram_Args(k_filename_list=["file_not_found"])
             api = api.API()
@@ -141,12 +139,6 @@ def exec_program(self, args: ExecProgram_Args) -> ExecProgram_Result:
         """
         return self.call("KclvmService.ExecProgram", args)
 
-    def build_program(self, args: BuildProgram_Args) -> BuildProgram_Result:
-        return self.call("KclvmService.BuildProgram", args)
-
-    def exec_artifact(self, args: ExecArtifact_Args) -> ExecProgram_Result:
-        return self.call("KclvmService.ExecArtifact", args)
-
     def parse_file(self, args: ParseFile_Args) -> ParseFile_Result:
         """Parse KCL single file to Module AST JSON string with import dependencies and parse errors.
 
@@ -157,7 +149,6 @@ def parse_file(self, args: ParseFile_Args) -> ParseFile_Result:
         ```python
         schema AppConfig:
             replicas: int
-
         app: AppConfig {
             replicas: 2
         }
@@ -187,7 +178,6 @@ def parse_program(self, args: ParseProgram_Args) -> ParseProgram_Result:
         ```python
         schema AppConfig:
             replicas: int
-
         app: AppConfig {
             replicas: 2
         }
@@ -217,7 +207,6 @@ def load_package(self, args: LoadPackage_Args) -> LoadPackage_Result:
         ```python
         schema AppConfig:
             replicas: int
-
         app: AppConfig {
             replicas: 2
         }
@@ -227,7 +216,6 @@ def load_package(self, args: LoadPackage_Args) -> LoadPackage_Result:
 
         ```python
         import kcl_lib.api as api
-
         args = api.LoadPackage_Args(
             parse_args=api.ParseProgram_Args(paths=["schema.k"]), resolve_ast=True
         )
@@ -279,7 +267,6 @@ def list_variables(self, args: ListVariables_Args) -> ListVariables_Result:
         ```python
         schema AppConfig:
             replicas: int
-
         app: AppConfig {
             replicas: 2
         }
@@ -300,35 +287,18 @@ def list_variables(self, args: ListVariables_Args) -> ListVariables_Result:
     def format_code(self, args: FormatCode_Args) -> FormatCode_Result:
         """Format the code source.
 
-        <details><summary>Example</summary>
-        <p>
+        ## Example
 
         Python Code
 
         ```python
         import kcl_lib.api as api
-
-        source_code = \"\"\"schema Person:
-            name:   str
-            age:    int
-
-            check:
-                0 <   age <   120
-        \"\"\"
+        source_code = "a   =   1"
         args = api.FormatCode_Args(source=source_code)
         api_instance = api.API()
-        result = api_instance.format_code(args)
-        assert (
-            result.formatted.decode()
-            == \"\"\"schema Person:
-            name: str
-            age: int
-
-            check:
-                0 < age < 120
 
-        \"\"\"
-        )
+        result = api_instance.format_code(args)
+        assert result.formatted.decode(), "a = 1"
         ```
         """
         return self.call("KclvmService.FormatCode", args)
@@ -344,7 +314,6 @@ def format_path(self, args: FormatPath_Args) -> FormatPath_Result:
         schema Person:
             name:   str
             age:    int
-
             check:
                 0 <   age <   120
         ```
@@ -372,7 +341,6 @@ def lint_path(self, args: LintPath_Args) -> LintPath_Result:
         ```python
         import math
 
-        a = 1
         ```
 
         Python Code
@@ -396,7 +364,6 @@ def override_file(self, args: OverrideFile_Args) -> OverrideFile_Result:
 
         ```python
         a = 1
-
         b = {
             "a": 1
             "b": 2
@@ -441,7 +408,6 @@ def get_schema_type_mapping(
         ```python
         schema AppConfig:
             replicas: int
-
         app: AppConfig {
             replicas: 2
         }
@@ -474,7 +440,6 @@ def validate_code(self, args: ValidateCode_Args) -> ValidateCode_Result:
         schema Person:
             name: str
             age: int
-
             check:
                 0 < age < 120
         \"\"\"
@@ -510,7 +475,6 @@ def load_settings_files(
 
         ```python
         import kcl_lib.api as api
-
         args = api.LoadSettingsFiles_Args(
             work_dir=".", files=["kcl.yaml"]
         )
@@ -530,9 +494,10 @@ def rename(self, args: Rename_Args) -> Rename_Result:
 
         ## Example
 
-        The content of `main.k` is
+        The content of main.k is
 
         ```python
+
         a = 1
         b = a
         ```
@@ -541,7 +506,6 @@ def rename(self, args: Rename_Args) -> Rename_Result:
 
         ```python
         import kcl_lib.api as api
-
         args = api.Rename_Args(
             package_root=".",
             symbol_path="a",
@@ -563,7 +527,6 @@ def rename_code(self, args: RenameCode_Args) -> RenameCode_Result:
 
         ```python
         import kcl_lib.api as api
-
         args = api.RenameCode_Args(
             package_root="/mock/path",
             symbol_path="a",
@@ -619,7 +582,6 @@ def update_dependencies(
 
         ```python
         import kcl_lib.api as api
-
         args = api.UpdateDependencies_Args(
             manifest_path="module"
         )
@@ -651,15 +613,13 @@ def update_dependencies(
         ```python
         import helloworld
         import flask
-
         a = helloworld.The_first_kcl_program
         ```
 
         Python Code
 
         ```python
         import kcl_lib.api as api
-
         args = api.UpdateDependencies_Args(
             manifest_path="module"
         )