文档教程云原生【免费下载链接】docsUser documentation for Knative components.项目地址https://gitcode.com/gh_mirrors/docs1/docs点击查看免费下载本文基于 Knative 官方文档仓库中的风格指南 documenting-code.md系统讲解 Knative 文档中代码片段、CLI 命令、YAML 资源与变量占位符的书写标准。读完后你将能够按照 Knative 文档社区的既有规范撰写或评审技术文档中的代码内容并结合mkdocs.yml与自定义样式表理解这些规范背后的渲染机制使产出与现有文档如 Eventing 配置指南、Functions 片段库保持一致。风格指南在 Knative 文档体系中的位置Knative 文档仓库将全部写作规范集中在contribute-to-docs/style-guide/目录下包括本文档 documenting-code.md 以及 标题与格式规范、语气与语言、词汇与短语列表、内容复用。风格指南目录说明 中有一句值得注意的定调You dont need to read the whole style guide before contributing to Knative documentation. Unpolished contributions delivered early are better than perfect contributions delivered late.也就是说规范的目标是降低协作摩擦、保证文档风格统一而不是设立贡献门槛。本文聚焦其中代码如何写这一篇它与其余各篇是互补关系标题用祈使句见 style-and-formatting.md正文用现在时和主动语态见 voice-and-language.md而本文档负责其中的代码部分。哪些文本必须使用行内代码格式指南第一条明确了行内代码格式inline code的适用边界只对以下五类文本使用文件名Filenames路径名Path namesYAML 文件中的字段和取值Fields and values from a YAML file任何需要输入到 CLI 的文本CLI 工具名称CLI names这一条与 style-and-formatting.md 中标题中不要使用代码格式的规则配套标题写Configure the class annotation而不是Configure the class annotation加反引号。两者合起来定义了代码格式只出现在正文的具体技术对象上这一原则避免读者把普通英文单词误认为是需要逐字输入的内容。为代码块指定编程语言每个代码围栏fence都必须声明语言标识符用于语法高亮对不属于任何编程语言的内容——典型如 CLI 命令——统一使用bash正确示例Go 源码标注gopackage main import fmt func main() { fmt.Println(hello world) }错误示例同一段 Go 源码误标为bashpackage main import fmt func main() { fmt.Println(hello world) }这条规则看似简单但直接影响阅读体验与语法高亮效果。Knative 文档使用 MkDocs Material 主题见 mkdocs.yml围栏上的语言标识会被映射为对应的 highlight 类语言标错时高亮规则与内容不匹配代码可读性直接受损。命令说明的标准句式... by running the command:指南对引出命令的导语给出了标准格式X the Y by running the command:该句式需要同时满足四条标准明确提到运行命令running the command这一点并不总是显而易见的用词是 run而不是 type、execute 等——一致性优先先描述命令的作用再给出命令本身尽可能简短。若必须偏离该标准句仍须满足上述四条标准。正确示例Create the service by running the command:kn create service service-nameWhereservice-nameis the name of your Knative Service.错误示例共三种典型偏差只写 Create the service:——没有提到运行命令也没有先说清动作的完整语义只写 Run:——没有描述命令的作用写 Run the following command to create a service:——语义颠倒把运行命令放在了动作描述之前且不如标准句简洁。这一句式并非只写在指南里。从仓库中现网文档的用法看它被严格一致地执行例如 event-display.md 片段1. Apply the YAML file by running the command: kubectl apply -f filename.yaml Where filename is the name of the file you created in the previous step.以及 broker-configuration.md 中的 Start acurlpod by running the following command:。对贡献者而言这意味着标准句 Where 变量说明是 Knative 文档中命令段的固定范式新增文档照此书写即可通过风格一致性检查。YAML 文档化两步走以及 apply 与 edit 的选用指南规定 YAML 相关内容一律采用两步法第一步创建 YAML 文件第二步应用该文件。并给出选择kubectl apply还是kubectl edit的判据用户自行创建的文件/对象用kubectl apply它同时覆盖创建和更新两种场景且用户的本地文件是唯一事实来源source of truth随 Knative 软件分发的对象用kubectl edit例如 Knative Serving 和 Knative Eventing 的 ConfigMap。此外当 YAML 是作为 CLI 命令的一部分被输入时代码块开头要写yaml语言标识。正确写法示例创建或更新资源时Create a YAML file using the following template:# YAML FILE CONTENTSApply the YAML file by running the command:kubectl apply -f filename.yamlWherefilenameis the name of the file you created in the previous step.编辑 ConfigMap 时kubectl -n namespace edit configmap resource-name而以下两种heredoc 一步到位的写法被明确判定为错误cat EOF | kubectl create -f - # code EOFkubectl apply -f - EOF # code EOF从文档工程角度看指南未逐条列出原因以下为基于两步法要求的推断heredoc 把定义资源与下发资源揉进同一条命令既无法让读者把 YAML 内容保存为可复用的本地文件与本地文件是 source of truth的原则相悖也无法在变量说明和排错时把两步拆开定位问题。代码块中变量占位符的书写规范变量统一使用尖括号小写连字符格式service-name。具体规则有四条全部小写单词之间用连字符hyphen分隔每个变量必须在代码块下方给出解释解释的固定句式是 Where...service-nameis…。单个变量正确kn create service service-nameWhereservice-nameis the name of your Knative Service.错误使用大写下划线风格并改变说明句式kn create service {SERVICE_NAME}{SERVICE_NAME} The name of your service多个变量正确所有变量汇总到一个 Where: 列表中kn create service service-name --revision-name revision-nameWhere:service-nameis the name of your Knative Service.revision-nameis the desired name of your revision.错误为每个变量各起一行 Where...kn create service service-name --revision-name revision-nameWhereservice-nameis the name of your Knative Service. Whererevision-nameis the desired name of your revision.这一约定同样体现在现网文档中例如 broker-configuration.md 里先写kubectl get broker broker-name再统一说明 Wherebroker-nameis the name of your Broker.用省略号标注代码摘录当展示的是 YAML 文件的一个摘录而非完整可运行的示例时必须在缺失上下文的行用...显式标出以表明这只是所需文件的一部分。正确apiVersion: serving.knative.dev/v1 kind: Service metadata: ... spec: ... traffic: - percent: 54 revisionName: config-00008 ...错误看起来像完整文件、实际缺了metadata等内容读者可能直接复制导致 apply 失败apiVersion: serving.knative.dev/v1 kind: Service metadata: spec: traffic: - percent: 54 revisionName: config-00008这条规则的价值在于把可复制即运行与仅为示意两类代码块在视觉上区分开防止读者把教学摘录当成完整清单。CLI 输出块{ .bash .no-copy }的规则与实现原理指南规定展示命令输出而非命令本身时代码块的语言标识应写为自定义 CSS 类{ .bash .no-copy }而不是bash其作用是移除代码块右侧的复制到剪贴板按钮——输出没有复制价值按钮属于噪音。正确some-code错误some-code这一语法为何能生效可以在仓库构建配置中找到完整证据链mkdocs.yml 中 Material 主题启用了content.code.copy特性它会给所有代码块注入Copy按钮同一配置启用了attr_listMarkdown 扩展它允许在代码围栏后以{ ... }语法附加 CSS 类即{ .bash .no-copy }这种写法的来源仓库自定义样式表 extra.css 中定义了.highlight.no-copy .md-clipboard { display: none; }即当代码块携带no-copy类时.md-clipboard复制按钮容器被隐藏。三者结合{ .bash .no-copy }在保留 bash 高亮的同时精准关闭了复制按钮。现网文档中这一模式已大量落地例如 event-display.md 中展示kubectl apply输出service.serving.knative.dev/event-display created与 Pod 列表时均使用no-copy块broker-configuration.md 展示 Broker 的kubectl get输出时同样如此社区代码示例如 helloworld-go 的 README 也在kubectl输出处使用了该写法。命令行标志统一使用短格式指南最后一条规则文档中出现的命令标志一律使用短格式例如用-n而不是--namespace。正确kubectl apply -f filename.yaml -n namespace错误kubectl apply --filename filename.yaml --namespace namespace这与标准句保持尽可能短的整体精神一致短标志让命令在文档排版中更紧凑也更贴近开发者日常肌肉记忆。本地验证与快速自检清单文档仓库提供了本地预览链路hack/mkdocs.sh 以mkdocs serve --livereload方式启动站点默认端口 8000完整流程参见 本地预览指南。提交 PR 前在本地过一遍渲染效果是验证代码块语言标识、no-copy按钮是否消失、省略号排版是否符合预期的最直接手段。把本文档的核心规则压缩成一份可操作的自检清单检查项要求行内代码只用于文件名、路径、YAML 字段/取值、CLI 输入文本、CLI 名称代码块语言必须声明非编程语言内容用bash命令内嵌 YAML 用yaml命令导语... by running the command:先说作用、用词 run、尽量短YAML 步骤两步走建文件 →kubectl apply随 Knative 分发的对象用kubectl edit禁用 heredoc变量lower-hyphen-case代码块下方统一以 Where ... is ... 说明摘录不完整示例必须用...标注缺失上下文命令输出使用{ .bash .no-copy }关闭复制按钮标志短格式优先-n而非--namespace相关资源原始风格指南条目documenting-code.md风格指南总目录Knative style guide标题、链接与排版规范style-and-formatting.md语气与用词规范voice-and-language.md构建配置主题特性与 Markdown 扩展mkdocs.yml复制按钮隐藏样式docs/stylesheets/extra.css遵循上述范式的现网示例broker-configuration.md、event-display.md本地预览文档previewing-docs-locally.md赞分享文档教程云原生【免费下载链接】docsUser documentation for Knative components.项目地址https://gitcode.com/gh_mirrors/docs1/docs点击查看免费下载相关推荐Knative 文档风格指南代码文档化、排版规范与写作语言标准详解Knative 文档风格指南代码文档化、排版规范与写作语言标准详解 本文基于 Knative 官方文档仓库的 Knative style guide http文档教程云原生Next.js 文档写作规范详解Frontmatter 模式、代码块格式与 MDX 组件标准Next.js 文档写作规范详解Frontmatter 模式、代码块格式与 MDX 组件标准 Next.js 官方文档 docs/ 目录共 500 篇前端后端Web框架SSR前端构建CommonDevKnowledge开发规范README文档与代码编写标准详解CommonDevKnowledge开发规范README文档与代码编写标准详解 想要让你的开源项目脱颖而出掌握专业的README文档规范和代码编写标准是关键文档知识库移动开发创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考