From 651d9b6c0754df0ae2a454836e704d97817edfce Mon Sep 17 00:00:00 2001 From: jsonwan Date: Mon, 22 Jul 2024 16:04:02 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E4=BD=9C=E4=B8=9A=E5=B9=B3=E5=8F=B0?= =?UTF-8?q?=E6=96=87=E6=A1=A3=E5=BB=BA=E8=AE=BE=20#3119?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 1. 支持生成英文版API文档简介； 2. 添加trouble_shooting英文版文档； 3. 修正部分接口文档中不合理的地方。 --- docs/apidoc/README_en.md | 65 +++++++++++++++++++ .../apidocs/en/create_credential.md | 2 +- .../apidocs/en/create_file_source.md | 2 +- ...cript_basic .md => update_script_basic.md} | 0 docs/overview/trouble_shooting_en.md | 6 ++ support-files/tools/docs/README_en.tpl | 6 ++ .../tools/docs/generateApiDocsReadme.py | 42 ++++++++++-- 7 files changed, 114 insertions(+), 9 deletions(-) create mode 100644 docs/apidoc/README_en.md rename docs/apidoc/esb/jobv3-confapis/apidocs/en/{update_script_basic .md => update_script_basic.md} (100%) create mode 100644 docs/overview/trouble_shooting_en.md create mode 100644 support-files/tools/docs/README_en.tpl diff --git a/docs/apidoc/README_en.md b/docs/apidoc/README_en.md new file mode 100644 index 0000000000..43bce80e2c --- /dev/null +++ b/docs/apidoc/README_en.md @@ -0,0 +1,65 @@ +## Job V3 API Introduction + +**The Job Platform (Job) is a fundamental operations management system. In addition to supporting a series of basic operations scenarios such as script execution, file distribution, and scheduled tasks, it also supports the ability to assemble fragmented individual tasks into an automated job process through workflow scheduling capabilities. Each job can serve as an atomic node, available for use by upper-layer or surrounding systems/platforms to achieve scheduling automation. The Job Platform provides atomic capabilities to other systems via APIs. The currently supported API resources are summarized as follows:** + + +| Resource Name | Resource Description | +| -------- |-------------------------------------------------------------------------------------------------------| +| [batch_get_job_instance_ip_log](https://github.com/TencentBlueKing/bk-job/blob/3.9.x/docs/apidoc/esb/jobv3-confapis/apidocs/en/batch_get_job_instance_ip_log.md) | Bulk query of job execution logs by host list | +| [callback_protocol](https://github.com/TencentBlueKing/bk-job/blob/3.9.x/docs/apidoc/esb/jobv3-confapis/apidocs/en/callback_protocol.md) | This component is only used to present the callback protocol when job finished | +| [check_script](https://github.com/TencentBlueKing/bk-job/blob/3.9.x/docs/apidoc/esb/jobv3-confapis/apidocs/en/check_script.md) | High risk script detection | +| [create_credential](https://github.com/TencentBlueKing/bk-job/blob/3.9.x/docs/apidoc/esb/jobv3-confapis/apidocs/en/create_credential.md) | Create credential | +| [create_dangerous_rule](https://github.com/TencentBlueKing/bk-job/blob/3.9.x/docs/apidoc/esb/jobv3-confapis/apidocs/en/create_dangerous_rule.md) | Create dangerous rule | +| [create_file_source](https://github.com/TencentBlueKing/bk-job/blob/3.9.x/docs/apidoc/esb/jobv3-confapis/apidocs/en/create_file_source.md) | Create a new file source | +| [create_public_script](https://github.com/TencentBlueKing/bk-job/blob/3.9.x/docs/apidoc/esb/jobv3-confapis/apidocs/en/create_public_script.md) | Create public script | +| [create_public_script_version](https://github.com/TencentBlueKing/bk-job/blob/3.9.x/docs/apidoc/esb/jobv3-confapis/apidocs/en/create_public_script_version.md) | Create Public Script Version | +| [create_script](https://github.com/TencentBlueKing/bk-job/blob/3.9.x/docs/apidoc/esb/jobv3-confapis/apidocs/en/create_script.md) | Create Script | +| [create_script_version](https://github.com/TencentBlueKing/bk-job/blob/3.9.x/docs/apidoc/esb/jobv3-confapis/apidocs/en/create_script_version.md) | Create Script Version | +| [delete_cron](https://github.com/TencentBlueKing/bk-job/blob/3.9.x/docs/apidoc/esb/jobv3-confapis/apidocs/en/delete_cron.md) | Delete cron job | +| [delete_dangerous_rule](https://github.com/TencentBlueKing/bk-job/blob/3.9.x/docs/apidoc/esb/jobv3-confapis/apidocs/en/delete_dangerous_rule.md) | Delete dangerous rule | +| [delete_public_script](https://github.com/TencentBlueKing/bk-job/blob/3.9.x/docs/apidoc/esb/jobv3-confapis/apidocs/en/delete_public_script.md) | Delete public script | +| [delete_public_script_version](https://github.com/TencentBlueKing/bk-job/blob/3.9.x/docs/apidoc/esb/jobv3-confapis/apidocs/en/delete_public_script_version.md) | Delete script version | +| [delete_script](https://github.com/TencentBlueKing/bk-job/blob/3.9.x/docs/apidoc/esb/jobv3-confapis/apidocs/en/delete_script.md) | Delete script | +| [delete_script_version](https://github.com/TencentBlueKing/bk-job/blob/3.9.x/docs/apidoc/esb/jobv3-confapis/apidocs/en/delete_script_version.md) | Delete script version | +| [disable_dangerous_rule](https://github.com/TencentBlueKing/bk-job/blob/3.9.x/docs/apidoc/esb/jobv3-confapis/apidocs/en/disable_dangerous_rule.md) | Disable dangerous rule | +| [disable_public_script_version](https://github.com/TencentBlueKing/bk-job/blob/3.9.x/docs/apidoc/esb/jobv3-confapis/apidocs/en/disable_public_script_version.md) | Disable the public script version | +| [disable_script_version](https://github.com/TencentBlueKing/bk-job/blob/3.9.x/docs/apidoc/esb/jobv3-confapis/apidocs/en/disable_script_version.md) | Disable script version | +| [enable_dangerous_rule](https://github.com/TencentBlueKing/bk-job/blob/3.9.x/docs/apidoc/esb/jobv3-confapis/apidocs/en/enable_dangerous_rule.md) | Enable dangerous rule | +| [execute_job_plan](https://github.com/TencentBlueKing/bk-job/blob/3.9.x/docs/apidoc/esb/jobv3-confapis/apidocs/en/execute_job_plan.md) | Start Job Plan | +| [fast_execute_script](https://github.com/TencentBlueKing/bk-job/blob/3.9.x/docs/apidoc/esb/jobv3-confapis/apidocs/en/fast_execute_script.md) | Start Job Plan | +| [fast_execute_sql](https://github.com/TencentBlueKing/bk-job/blob/3.9.x/docs/apidoc/esb/jobv3-confapis/apidocs/en/fast_execute_sql.md) | Quick execution of SQL scripts | +| [fast_transfer_file](https://github.com/TencentBlueKing/bk-job/blob/3.9.x/docs/apidoc/esb/jobv3-confapis/apidocs/en/fast_transfer_file.md) | Quick File transfer | +| [generate_local_file_upload_url](https://github.com/TencentBlueKing/bk-job/blob/3.9.x/docs/apidoc/esb/jobv3-confapis/apidocs/en/generate_local_file_upload_url.md) | Generate the local file upload URL | +| [get_account_list](https://github.com/TencentBlueKing/bk-job/blob/3.9.x/docs/apidoc/esb/jobv3-confapis/apidocs/en/get_account_list.md) | Query the list of executive accounts to which users have access under the business | +| [get_cron_detail](https://github.com/TencentBlueKing/bk-job/blob/3.9.x/docs/apidoc/esb/jobv3-confapis/apidocs/en/get_cron_detail.md) | Query Cron job details | +| [get_cron_list](https://github.com/TencentBlueKing/bk-job/blob/3.9.x/docs/apidoc/esb/jobv3-confapis/apidocs/en/get_cron_list.md) | Query information of cron jobs under business | +| [get_dangerous_rule_list](https://github.com/TencentBlueKing/bk-job/blob/3.9.x/docs/apidoc/esb/jobv3-confapis/apidocs/en/get_dangerous_rule_list.md) | Get dangerous rule list | +| [get_job_instance_global_var_value](https://github.com/TencentBlueKing/bk-job/blob/3.9.x/docs/apidoc/esb/jobv3-confapis/apidocs/en/get_job_instance_global_var_value.md) | Gets the value of the job instance global variable | +| [get_job_instance_ip_log](https://github.com/TencentBlueKing/bk-job/blob/3.9.x/docs/apidoc/esb/jobv3-confapis/apidocs/en/get_job_instance_ip_log.md) | Query job execution log by host | +| [get_job_instance_list](https://github.com/TencentBlueKing/bk-job/blob/3.9.x/docs/apidoc/esb/jobv3-confapis/apidocs/en/get_job_instance_list.md) | Query job instance list (execution history) | +| [get_job_instance_status](https://github.com/TencentBlueKing/bk-job/blob/3.9.x/docs/apidoc/esb/jobv3-confapis/apidocs/en/get_job_instance_status.md) | Query job execution status based on job instance ID | +| [get_job_plan_detail](https://github.com/TencentBlueKing/bk-job/blob/3.9.x/docs/apidoc/esb/jobv3-confapis/apidocs/en/get_job_plan_detail.md) | Check Job Plan details by Job Plan ID | +| [get_job_plan_list](https://github.com/TencentBlueKing/bk-job/blob/3.9.x/docs/apidoc/esb/jobv3-confapis/apidocs/en/get_job_plan_list.md) | Search Job Plan list | +| [get_job_template_list](https://github.com/TencentBlueKing/bk-job/blob/3.9.x/docs/apidoc/esb/jobv3-confapis/apidocs/en/get_job_template_list.md) | Query job template list | +| [get_latest_service_version](https://github.com/TencentBlueKing/bk-job/blob/3.9.x/docs/apidoc/esb/jobv3-confapis/apidocs/en/get_latest_service_version.md) | Query the latest service version | +| [get_public_script_list](https://github.com/TencentBlueKing/bk-job/blob/3.9.x/docs/apidoc/esb/jobv3-confapis/apidocs/en/get_public_script_list.md) | Query public script list | +| [get_public_script_version_detail](https://github.com/TencentBlueKing/bk-job/blob/3.9.x/docs/apidoc/esb/jobv3-confapis/apidocs/en/get_public_script_version_detail.md) | Query public script version details | +| [get_public_script_version_list](https://github.com/TencentBlueKing/bk-job/blob/3.9.x/docs/apidoc/esb/jobv3-confapis/apidocs/en/get_public_script_version_list.md) | Query public script version list | +| [get_script_list](https://github.com/TencentBlueKing/bk-job/blob/3.9.x/docs/apidoc/esb/jobv3-confapis/apidocs/en/get_script_list.md) | Query business script list | +| [get_script_version_detail](https://github.com/TencentBlueKing/bk-job/blob/3.9.x/docs/apidoc/esb/jobv3-confapis/apidocs/en/get_script_version_detail.md) | Query business script version details | +| [get_script_version_list](https://github.com/TencentBlueKing/bk-job/blob/3.9.x/docs/apidoc/esb/jobv3-confapis/apidocs/en/get_script_version_list.md) | Query business script version list | +| [operate_job_instance](https://github.com/TencentBlueKing/bk-job/blob/3.9.x/docs/apidoc/esb/jobv3-confapis/apidocs/en/operate_job_instance.md) | Use to perform actions on an executed job instance, such as terminating a job | +| [operate_step_instance](https://github.com/TencentBlueKing/bk-job/blob/3.9.x/docs/apidoc/esb/jobv3-confapis/apidocs/en/operate_step_instance.md) | Used to perform actions on the steps of an executed instance, such as retry, ignore errors, and so on | +| [publish_public_script_version](https://github.com/TencentBlueKing/bk-job/blob/3.9.x/docs/apidoc/esb/jobv3-confapis/apidocs/en/publish_public_script_version.md) | Set public script version status to online | +| [publish_script_version](https://github.com/TencentBlueKing/bk-job/blob/3.9.x/docs/apidoc/esb/jobv3-confapis/apidocs/en/publish_script_version.md) | Set script version status to online | +| [push_config_file](https://github.com/TencentBlueKing/bk-job/blob/3.9.x/docs/apidoc/esb/jobv3-confapis/apidocs/en/push_config_file.md) | Distribute configuration files | +| [save_cron](https://github.com/TencentBlueKing/bk-job/blob/3.9.x/docs/apidoc/esb/jobv3-confapis/apidocs/en/save_cron.md) | Create or update Cron Job | +| [update_credential](https://github.com/TencentBlueKing/bk-job/blob/3.9.x/docs/apidoc/esb/jobv3-confapis/apidocs/en/update_credential.md) | Update credentials | +| [update_cron_status](https://github.com/TencentBlueKing/bk-job/blob/3.9.x/docs/apidoc/esb/jobv3-confapis/apidocs/en/update_cron_status.md) | Update Cron job status | +| [update_dangerous_rule](https://github.com/TencentBlueKing/bk-job/blob/3.9.x/docs/apidoc/esb/jobv3-confapis/apidocs/en/update_dangerous_rule.md) | update dangerous rule | +| [update_file_source](https://github.com/TencentBlueKing/bk-job/blob/3.9.x/docs/apidoc/esb/jobv3-confapis/apidocs/en/update_file_source.md) | Update the file source | +| [update_public_script_basic](https://github.com/TencentBlueKing/bk-job/blob/3.9.x/docs/apidoc/esb/jobv3-confapis/apidocs/en/update_public_script_basic.md) | Update basic information of public scripts | +| [update_public_script_version](https://github.com/TencentBlueKing/bk-job/blob/3.9.x/docs/apidoc/esb/jobv3-confapis/apidocs/en/update_public_script_version.md) | Update public script version | +| [update_script_basic](https://github.com/TencentBlueKing/bk-job/blob/3.9.x/docs/apidoc/esb/jobv3-confapis/apidocs/en/update_script_basic.md) | Update script basic information | +| [update_script_version](https://github.com/TencentBlueKing/bk-job/blob/3.9.x/docs/apidoc/esb/jobv3-confapis/apidocs/en/update_script_version.md) | Update Script Version Information | + diff --git a/docs/apidoc/esb/jobv3-confapis/apidocs/en/create_credential.md b/docs/apidoc/esb/jobv3-confapis/apidocs/en/create_credential.md index d3f53f2c87..806711396a 100644 --- a/docs/apidoc/esb/jobv3-confapis/apidocs/en/create_credential.md +++ b/docs/apidoc/esb/jobv3-confapis/apidocs/en/create_credential.md @@ -1,4 +1,4 @@ -### **Description** Function Description +### Function Description Create credential. diff --git a/docs/apidoc/esb/jobv3-confapis/apidocs/en/create_file_source.md b/docs/apidoc/esb/jobv3-confapis/apidocs/en/create_file_source.md index e7d5d58014..84b110d2d0 100644 --- a/docs/apidoc/esb/jobv3-confapis/apidocs/en/create_file_source.md +++ b/docs/apidoc/esb/jobv3-confapis/apidocs/en/create_file_source.md @@ -1,4 +1,4 @@ -### Description Function Description +### Function Description Create a new file source, currently only BlueKing Repository file sources that are associated with automatically selected public access points are supported. The created file source has the following default features: diff --git a/docs/apidoc/esb/jobv3-confapis/apidocs/en/update_script_basic .md b/docs/apidoc/esb/jobv3-confapis/apidocs/en/update_script_basic.md similarity index 100% rename from docs/apidoc/esb/jobv3-confapis/apidocs/en/update_script_basic .md rename to docs/apidoc/esb/jobv3-confapis/apidocs/en/update_script_basic.md diff --git a/docs/overview/trouble_shooting_en.md b/docs/overview/trouble_shooting_en.md new file mode 100644 index 0000000000..52c1dc634b --- /dev/null +++ b/docs/overview/trouble_shooting_en.md @@ -0,0 +1,6 @@ +# BlueKing Job Platform Troubleshooting Documentation + +### I. Operations and Maintenance +#### 1. How to Batch Trigger an Action (e.g., Force Terminate a Batch of Abnormal Jobs, or Batch Close/Open Scheduled Tasks)? +Answer: You can use the diagnostic and maintenance toolset under the `op-tools` directory in the [BlueKing Job Platform Code Repository](https://github.com/TencentBlueKing/bk-job/tree/master/op-tools) to perform these operations. For specific usage instructions, please refer to the corresponding README documentation. + diff --git a/support-files/tools/docs/README_en.tpl b/support-files/tools/docs/README_en.tpl new file mode 100644 index 0000000000..9e2480ed7c --- /dev/null +++ b/support-files/tools/docs/README_en.tpl @@ -0,0 +1,6 @@ +## Job V3 API Introduction + +**The Job Platform (Job) is a fundamental operations management system. In addition to supporting a series of basic operations scenarios such as script execution, file distribution, and scheduled tasks, it also supports the ability to assemble fragmented individual tasks into an automated job process through workflow scheduling capabilities. Each job can serve as an atomic node, available for use by upper-layer or surrounding systems/platforms to achieve scheduling automation. The Job Platform provides atomic capabilities to other systems via APIs. The currently supported API resources are summarized as follows:** + + +{{api_summary}} diff --git a/support-files/tools/docs/generateApiDocsReadme.py b/support-files/tools/docs/generateApiDocsReadme.py index 659a4ac380..0d917adbf8 100644 --- a/support-files/tools/docs/generateApiDocsReadme.py +++ b/support-files/tools/docs/generateApiDocsReadme.py @@ -33,18 +33,44 @@ # 获取当前脚本的目录 script_dir = os.path.dirname(os.path.abspath(__file__)) +language_info = { + "en": { + "docs_dir_path": "esb/jobv3-confapis/apidocs/en", + "template_file_name": "README_en.tpl", + "output_file_name": "README_en.md", + "function_desc_title": "### Function Description", + "resource_name_title": "Resource Name", + "resource_description_title": "Resource Description" + }, + "zh_hans": { + "docs_dir_path": "esb/jobv3-confapis/apidocs/zh_hans", + "template_file_name": "README.tpl", + "output_file_name": "README.md", + "function_desc_title": "### 功能描述", + "resource_name_title": "资源名称", + "resource_description_title": "资源描述" + } +} + # 获取使用的分支 branch = "master" if len(sys.argv) >= 2: branch = sys.argv[1].strip() +# 获取使用的语言 +language = "zh_hans" +if len(sys.argv) >= 3: + language = sys.argv[2].strip() + print("文档引用的代码分支为: %s" % branch) # 常量定义 apidoc_dir = os.path.join(script_dir, "../../../docs/apidoc") -docs_dir = os.path.join(apidoc_dir, "esb/jobv3-confapis/apidocs/zh_hans") -docs_link_prefix = "https://github.com/TencentBlueKing/bk-job/blob/" + branch + "/docs/apidoc/esb/jobv3-confapis/apidocs/zh_hans/" -template_file = os.path.join(script_dir, "README.tpl") -output_file = os.path.join(apidoc_dir, "README.md") +docs_dir_path = language_info[language]["docs_dir_path"] +docs_dir = os.path.join(apidoc_dir, docs_dir_path) +docs_link_prefix = "https://github.com/TencentBlueKing/bk-job/blob/" + branch + "/docs/apidoc/" + docs_dir_path + "/" +template_file = os.path.join(script_dir, language_info[language]["template_file_name"]) +output_file_name = language_info[language]["output_file_name"] +output_file = os.path.join(apidoc_dir, output_file_name) # 初始化结果列表 results = [] @@ -60,7 +86,7 @@ # 提取功能描述 func_desc = None for i, line in enumerate(lines): - if line.strip() == "### 功能描述": + if line.strip() == language_info[language]["function_desc_title"]: # 查找功能描述内容，忽略空白行 for j in range(i + 1, len(lines)): if lines[j].strip(): @@ -80,8 +106,10 @@ else: print(f"功能描述缺失: {file_path}") +resource_name_title = language_info[language]["resource_name_title"] +resource_description_title = language_info[language]["resource_description_title"] # 生成接口文档简介内容 -api_summary = "| 资源名称 | 资源描述 |\n" +api_summary = "| " + resource_name_title + " | " + resource_description_title + " |\n" api_summary += "| -------- | -------- |\n" for result in results: api_summary += result + "\n" @@ -96,4 +124,4 @@ with open(output_file, 'w', encoding='utf-8') as f: f.write(output_content) -print(f"接口文档简介README.md已生成: {output_file}") +print(f"接口文档简介已生成: {output_file}")