master

Katrina-CXYfeat(doc): auto-fit table column widths to content

8c56bf48创建于 17 天前历史提交

文件	最后提交记录	最后更新时间
mkdocs	[doc server] 添加文档托管网站基础设施 Co-authored-by: xuchi<xuchicolson@163.com> # message auto-generated for no-merge-commit merge: !724 merge A00200_0330 into dev [doc server] 添加文档托管网站基础设施 Created-by: martinXuc Commit-by: xuchi Merged-by: ascend-robot Description: <!-- PR描述模板更新日期：20251225 --> # 合入背景 Fixes #377 当前项目缺少统一的文档站点构建与发布能力，文档以原始 Markdown 形式放在仓库中，阅读体验差、导航结构不清晰，在线浏览和搜索功能非常有限。 本 PR 引入 MkDocs Material 文档站点基础设施，支持通过 ReadTheDocs 在线发布中文文档，同时修复文档链接、适配 pre-commit 检查、优化代码块渲染，为后续文档持续维护和协作提供标准化框架。 # 修改内容 ## 文档站点基础设施 1. 新增 [mkdocs.yml](mkdocs.yml) 站点配置文件，基于 MkDocs Material 主题，配置导航、搜索、代码高亮、Git 修订日期、图片灯箱、HTML 压缩、MathJax 数学公式渲染等插件和 Markdown 扩展 2. 新增 [.readthedocs.yaml](.readthedocs.yaml) ReadTheDocs 构建配置，使用 Ubuntu 22.04 + Python 3.11 + uv 包管理器进行文档构建 3. 新增 [requirements/mkdocs.txt](requirements/mkdocs.txt) 文档构建依赖清单 4. 新增 [docs/zh/.nav.yml](docs/zh/.nav.yml) 中文文档导航配置，覆盖用户指南、开发者指南和 FAQ 等模块 5. 新增 [docs/zh/build_mkdocs.md](docs/zh/build_mkdocs.md) 本地构建 MkDocs 文档服务的调试指南 ## 自定义样式与 Hook 6. 新增 [docs/mkdocs/hooks/github_admonition.py](docs/mkdocs/hooks/github_admonition.py) Hook，将 GitHub 风格的 > [!NOTE] 等 Admonition 语法自动转换为 MkDocs !!! note 语法（支持 >- 列表嵌套语法） 7. 新增 [docs/mkdocs/hooks/img_width.py](docs/mkdocs/hooks/img_width.py) Hook，将 HTML <img> 标签（含 width 属性）转换为 MkDocs 兼容的 Markdown 图片语法 8. 新增 [docs/zh/stylesheets/extra.css](docs/zh/stylesheets/extra.css) 自定义样式：定义 announcement、important、code、console 四种 Admonition 类型样式，Tabbed 组件样式，代码块系统等宽字体（不换行 + tab-size: 8） 9. 新增 [docs/zh/javascripts/mathjax.js](docs/zh/javascripts/mathjax.js) MathJax 数学公式渲染配置 ## README 与首页 10. 重构 [README.md](README.md)：添加居中大标题和副标题、导航栏（昇腾社区 / 文档中心 / 代码仓库 / 社区会议），所有文档链接替换为 ReadTheDocs 在线地址，修复原有 2 个断链（install/README.md、user_manual/README.md） 11. 重构 [docs/zh/README.md](docs/zh/README.md) 首页为 Landing Page，包含项目简介、核心能力、架构概览和相关链接 ## 文档修复与整理 12. 修复 [docs/zh/user_guide/install/menu_install.md](docs/zh/user_guide/install/menu_install.md) 中 4 处链接失效：nofification 拼写错误、FAQ 路径 faq/ → faq_and_appendixes/ 13. 修复 [docs/zh/user_guide/feature/](docs/zh/user_guide/feature/) 文件名大小写不一致：multi_loRA.md → multi_lora.md、splitFuse.md → split_fuse.md，同步更新所有引用该文件的导航链接 14. 删除冗余文档 installtion_in_containerized.md（保留 installation_in_containerized.md） ## Pre-commit 适配 15. [.pre-commit-config.yaml](.pre-commit-config.yaml) 中 check-yaml 添加 exclude: mkdocs\.yml$，跳过含 !!python/name: 扩展标签的 mkdocs.yml # 资料变更 本 PR 即为资料变更。引入 MkDocs 文档站点基础设施，重构中文文档首页和项目 README，修复多处文档链接失效，新增导航配置、自定义样式、MkDocs Hook 和 ReadTheDocs 构建配置。 # 接口变更 不涉及 # 测试结果 - 本地使用 mkdocs serve 构建验证通过，站点可正常访问，页面渲染正确 - 导航链接已逐一确认，所有页面可正常跳转 - 明暗主题切换正常，Logo 和 favicon 显示正确 - GitHub Admonition Hook 转换验证通过，> [!NOTE]、> [!WARNING]、> [!TIP]、> [!CAUTION]、> [!IMPORTANT] 均可正确转换（含 >- 列表嵌套语法） - 代码块系统等宽字体渲染正常，box-drawing 字符对齐正确（Mac / Windows / ReadTheDocs 已验证） - 搜索功能正常，支持中文搜索和高亮 - ReadTheDocs 构建配置验证通过 - pre-commit 检查通过（mkdocs.yml 已排除 check-yaml） # CheckList - [x] 代码注释完备 - [x] 正确记录错误日志 - [x] 进行了返回值校验 (禁止使用void屏蔽安全函数、自研函数返回值；考虑接口的异常场景；调用底层组件接口时，需要进行返回值校验) - [x] 进行了空指针校验 - [x] 若存在资源申请，使用后资源被正确的释放了 - [x] 若涉及多线程场景，考虑了并发场景，不存在死锁问题 - [x] 按照[代码仓中提供的格式模板](https://gitcode.com/Ascend/MindIE-LLM/blob/master/.clang-format)，使用clang-format工具格式化代码 - [x] 符合Ascend社区的编码规范。[C++ 语言编程指导](https://gitcode.com/Ascend/community/blob/master/docs/contributor/Ascend-Cpp-Coding-Style-Guide.md) | [C++ 语言安全编程指导](https://gitcode.com/Ascend/community/blob/master/docs/contributor/Ascend-Cpp-Secure-Coding-Guide.md) See merge request: Ascend/MindIE-LLM!724	1 个月前
zh	feat(doc): auto-fit table column widths to content Add global CSS rule to prevent unwanted line breaks in table cells. Tables now expand to fit their content and scroll horizontally when overflowing the page width. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>	17 天前