From 88fd2fe421bdeae024326c59dd74ac6674209855 Mon Sep 17 00:00:00 2001
From: yuhan <yuhan24@h-partners.com>
Date: Mon, 4 Aug 2025 15:30:07 +0800
Subject: [PATCH] modify config

---
 docs/mindspore/_ext/customdocumenter.txt      |  1 +
 docs/mindspore/_ext/generate_ops_mint_rst.py  |  5 ++++
 docs/mindspore/_ext/generate_rst_by_en.py     | 29 ++++++++++---------
 docs/mindspore/_ext/overwrite_autodoc.txt     |  2 ++
 .../_ext/overwriteobjectiondirective.txt      |  2 ++
 tools/generate_html/base_version.json         | 10 +++----
 6 files changed, 31 insertions(+), 18 deletions(-)

diff --git a/docs/mindspore/_ext/customdocumenter.txt b/docs/mindspore/_ext/customdocumenter.txt
index 2d37ae41f6..a8985f0b84 100644
--- a/docs/mindspore/_ext/customdocumenter.txt
+++ b/docs/mindspore/_ext/customdocumenter.txt
@@ -22,6 +22,7 @@ class CustomDocumenter(Documenter):
         members_check_module, members = self.get_object_members(want_all)
 
         # **** 排除已写中文接口名 ****
+        # 获取需要排除的接口名，定义和include两种
         file_path = os.path.join(self.env.app.srcdir, self.env.docname+'.rst')
         exclude_re = re.compile(r'(.. py:class::|.. py:function::)\s+(.*?)(\(|\n)')
         includerst_re = re.compile(r'.. include::\s+(.*?)\n')
diff --git a/docs/mindspore/_ext/generate_ops_mint_rst.py b/docs/mindspore/_ext/generate_ops_mint_rst.py
index 3160473dff..1df70dc418 100644
--- a/docs/mindspore/_ext/generate_ops_mint_rst.py
+++ b/docs/mindspore/_ext/generate_ops_mint_rst.py
@@ -23,6 +23,7 @@ def generate_ops_mint_rst(repo_path, ops_path, mint_path, pr_need='all'):
     for root, dirs, files in os.walk(os.path.join(repo_path, 'mindspore/python/mindspore/mint')):
         for file in files:
             if file in ('__init__.py', 'functional.py'):
+                # 获取两个模块并按照模块名分类
                 with open(os.path.join(root, file), 'r+', encoding='utf-8') as f:
                     content = f.read()
                 modulename = '.'.join(root.split('mindspore/python/')[-1].split('/'))
@@ -39,6 +40,7 @@ def generate_ops_mint_rst(repo_path, ops_path, mint_path, pr_need='all'):
                     continue
                 one_p = re.findall(r'from mindspore\.(ops|nn).*?(?<!extend) import (.*?)(\n|# )', content)
                 two_p = [i[1] for i in one_p]
+                # 从导入处获取接口名，分为直接导入接口名，as别名，import导入多个
                 for i in two_p:
                     if ' as ' in i:
                         name1 = re.findall('(.*?) as (.*)', i)[0][0]
@@ -59,6 +61,7 @@ def generate_ops_mint_rst(repo_path, ops_path, mint_path, pr_need='all'):
     if pr_need != 'all':
         os.makedirs(mint_path, exist_ok=True)
     for k, v in mint_ops_dict.items():
+        # 去除mint.nn.xxx接口
         if not re.findall(r'\.nn\.(?!function).*', k):
             for name in v:
                 if isinstance(name, list):
@@ -67,10 +70,12 @@ def generate_ops_mint_rst(repo_path, ops_path, mint_path, pr_need='all'):
                 else:
                     name1 = name
                     name2 = name
+                # 非对外接口不操作
                 if f'{k}.{name2}' not in sum_list:
                     continue
                 elif pr_need != 'all' and f'{k}.{name2}' not in pr_need:
                     continue
+                # 已存在不覆盖
                 if os.path.exists(os.path.join(mint_path, f'{k}.{name2}.rst')):
                     exist_mint_file.append(f'{k}.{name2}')
                     continue
diff --git a/docs/mindspore/_ext/generate_rst_by_en.py b/docs/mindspore/_ext/generate_rst_by_en.py
index 24d0a6bc75..d3e601fd08 100644
--- a/docs/mindspore/_ext/generate_rst_by_en.py
+++ b/docs/mindspore/_ext/generate_rst_by_en.py
@@ -3,23 +3,22 @@ import importlib
 import inspect
 import re
 import os
+from functools import reduce
 
 def get_api(fullname):
-    """Get the api module."""
-    try:
-        module_name, api_name = ".".join(fullname.split('.')[:-1]), fullname.split('.')[-1]
-        # pylint: disable=unused-variable
-        module_import = importlib.import_module(module_name)
-    except ModuleNotFoundError:
-        module_name, api_name = ".".join(fullname.split('.')[:-2]), ".".join(fullname.split('.')[-2:])
-        module_import = importlib.import_module(module_name)
-    # pylint: disable=eval-used
+    """
+    获取接口对象。
+
+    :param fullname: 接口名全称
+    :return: 属性对象或None(如果不存在)
+    """
+    main_module = fullname.split('.')[0]
+    main_import = importlib.import_module(main_module)
+
     try:
-        api = getattr(module_import, api_name, '')
+        return reduce(getattr, fullname.split('.')[1:], main_import)
     except AttributeError:
-        print(f'failed to {module_import}.{api_name}')
-        return ''
-    return api
+        return None
 
 def generate_rst_by_en(sum_list, target_path, language='cn'):
     """Generate the rst file by the ops list."""
@@ -27,6 +26,7 @@ def generate_rst_by_en(sum_list, target_path, language='cn'):
     exist_rst = []
     primi_auto = []
     for i in sum_list:
+        # 处理大写接口
         if i.lower() == i:
             continue
         try:
@@ -50,6 +50,7 @@ def generate_rst_by_en(sum_list, target_path, language='cn'):
             except TypeError:
                 py_docs = ''
 
+        # 获取入参
         try:
             source_code = inspect.getsource(module_api.__init__)
             if module_api.__doc__:
@@ -61,8 +62,10 @@ def generate_rst_by_en(sum_list, target_path, language='cn'):
             all_params = ''
 
         if 'Refer to' in py_docs.split('\n')[-1] and 'for more details.' in py_docs.split('\n')[-1]:
+            # 记录哪些是自动生成的
             if py_docs:
                 primi_auto.append(i)
+            # 生成中文rst文件
             if py_docs and language == 'cn':
                 sig_doc_str = all_params.strip()
                 cn_base_rst = i + '\n' + '=' * len(i) + '\n\n' + '.. py:class:: ' + i + '(' + sig_doc_str + ')\n\n'
diff --git a/docs/mindspore/_ext/overwrite_autodoc.txt b/docs/mindspore/_ext/overwrite_autodoc.txt
index f79d257f4c..d4f1513ab5 100644
--- a/docs/mindspore/_ext/overwrite_autodoc.txt
+++ b/docs/mindspore/_ext/overwrite_autodoc.txt
@@ -564,6 +564,7 @@ class Documenter:
                           RemovedInSphinx50Warning, stacklevel=2)
         docstring = getdoc(self.object, self.get_attr, self.config.autodoc_inherit_docstrings,
                            self.parent, self.object_name)
+        # 修改mint方法的英文注释内容
         spec_tp = [('ops.dense', 'ops.linear'), ('ops.inverse_ext', ['mint.linalg.inv', 'mint.inverse']),
                    ('ops.auto_generate.linalg_qr', 'mindspore.mint.linalg.qr')]
         if docstring and '.mint.' in self.fullname:
@@ -1783,6 +1784,7 @@ class ClassDocumenter(DocstringSignatureMixin, ModuleLevelDocumenter):  # type:
                     docstrings = [initdocstring]
                 else:
                     docstrings.append(initdocstring)
+        # 修改mint类的英文注释内容
         spec_tp = [('nn.HShrink', 'mint.nn.Hardshrink'), ('nn.SoftShrink', 'mint.nn.Softshrink'),
                    ('nn.HSigmoid', 'mint.nn.Hardsigmoid'), ('nn.HSwish', 'mint.nn.Hardswish')]
         if docstrings and '.mint.' in self.fullname:
diff --git a/docs/mindspore/_ext/overwriteobjectiondirective.txt b/docs/mindspore/_ext/overwriteobjectiondirective.txt
index 679bee7a5e..0d3a5989c1 100644
--- a/docs/mindspore/_ext/overwriteobjectiondirective.txt
+++ b/docs/mindspore/_ext/overwriteobjectiondirective.txt
@@ -75,6 +75,7 @@ def get_example(name: str):
             logger.warning(f"not api obj: {name}")
             return []
         api_doc = inspect.getdoc(api_obj)
+        # mint接口特殊处理样例内容
         if '.mint.' in name:
             spec_tp = [('ops.dense', 'ops.linear'), ('ops.inverse_ext', ['mint.linalg.inv', 'mint.inverse']),
                        ('nn.HShrink', 'mint.nn.Hardshrink'), ('nn.SoftShrink', 'mint.nn.Softshrink'),
@@ -96,6 +97,7 @@ def get_example(name: str):
             else:
                 api_doc = re.sub('(>>> from mindspore import .*?)(ops|nn)', r'\1mint', api_doc)
                 api_doc = api_doc.replace('>>> import mindspore.ops as ops', '>>> from mindspore import mint')
+        # tensor接口特殊处理样例内容
         elif 'mindspore.is_tensor' in name:
             api_doc = api_doc.replace('>>> from mindspore import Tensor, ops', '>>> from mindspore import Tensor, is_tensor')
             api_doc = api_doc.replace('>>> ops.is_tensor', '>>> is_tensor')
diff --git a/tools/generate_html/base_version.json b/tools/generate_html/base_version.json
index fb750b2d8a..75e33126d1 100644
--- a/tools/generate_html/base_version.json
+++ b/tools/generate_html/base_version.json
@@ -9,12 +9,12 @@
         "submenu": {
             "zh": [
                 {
-                    "label": "特性介绍",
+                    "label": "Developer Notes",
                     "url": "/docs/zh-CN/master/features/index.html",
                     "id": "master-features"
                 },
                 {
-                    "label": "API文档",
+                    "label": "API",
                     "url": "/docs/zh-CN/master/api_python/index.html",
                     "id": "master-api_python"
                 },
@@ -24,13 +24,13 @@
                     "id": "master-faq"
                 },
                 {
-                    "label": "RELEASE NOTES",
+                    "label": "Release Notes",
                     "url": "/docs/zh-CN/master/RELEASE.html"
                 }
             ],
             "en": [
                 {
-                    "label": "Feature Description",
+                    "label": "Developer Notes",
                     "url": "/docs/en/master/features/index.html",
                     "id": "master-features"
                 },
@@ -45,7 +45,7 @@
                     "id": "master-faq"
                 },
                 {
-                    "label": "RELEASE NOTES",
+                    "label": "Release Notes",
                     "url": "/docs/en/master/RELEASE.html"
                 }
             ]
-- 
Gitee