云原生【免费下载链接】mesosApache Mesos项目地址https://gitcode.com/gh_mirrors/mesos2/mesos点击查看免费下载本指南是 Apache Mesos 项目中所有“非代码文档”的统一书写规范规定了docs/目录下 Markdown 用户指南在标题大小写、代码块、强调、表格、空行等方面应遵循的约定并解释了这些 Markdown 文件如何经 Middleman Doxygen 流水线渲染为线上文档。读完本文后你将掌握编写符合 Mesos 文档规范的 Markdown 页面的全部规则并能理解从仓库docs/目录到最终站点页面的完整生成机制使你的文档改动一次通过评审。风格指南的定位与适用范围Mesos 的文档体系分为三类见 Documentation GuideMarkdown 用户指南、Doxygen API 文档、以及普通源码注释。本文所述的风格指南专门约束第一类——即存放在docs/文件夹中的用户指南与非代码技术文档。这些 Markdown 文件会被渲染为线上文档mesos.apache.org/documentation/latest/。指南本身在 docs/home.md 的开发者资源列表中与 Doxygen Style Guide、C Style Guide 并列是贡献者必须遵循的写作规范之一。注意原文档声明该指南仍在完善中work in progress仓库中部分存量文档可能尚未完全符合本规范。编写新文档时应以本指南为准修订旧文档时也应向此规范靠拢。此外Mesos 文档在措辞上遵循 RFC 2119 的语义约定must、should、can等词汇具有严格的约束强度含义见 Documentation Guide 的 Conventions 一节撰写文档时应保持这一语义一致性。What to Document什么值得写文档指南给出的两条核心原则是任何新的实质性功能substantial feature都应在其独立的 Markdown 文件中获得文档而不是塞进既有页面。保持代码与文档的关联可见如果从源码跳转到文档的链接不明显应在相关代码中插入一条简短注释说明存在需要同步维护的非代码文档并指明它的位置。与之配套的是“文档与代码同步”要求修改代码时必须评估是否需要更新文档尤其是引入新命令行 flag 或修改现有 flag 时必须在 docs/configuration.md 中有对应反映。configuration.md是入口索引实际 flag 表格分散在 docs/configuration/master.md、docs/configuration/agent.md、docs/configuration/master-and-agent.md 等页面中这些页面正是 HTML 表格规范下文详述最集中的落地场景。Section Headings章节标题使用 Title Case章节标题section headings应使用 Title Case标题式大小写指南推荐 APA 风格变体具体规则为标题含标题、副标题、子标题的第一个单词首字母必须大写标题中所有“主要”单词名词、动词、形容词、副词、代词首字母大写连字符主要词的第二部分同样大写例如Self-Report而不是Self-report五个字母及以上的单词一律大写首字母。换言之只有四类“次要”单词可以小写连词如and、or、nor、but、冠词a、an、the、介词如as、at、by、for、from、in、of、on、per、to、with且仅限四个字母及以下它们不能作为标题的第一个单词出现。从仓库现状看现有配置文档的标题正是这一规则的体现例如 docs/configuration.md 中的Master and Agent Options、Autotools Options、CMake Options——介词and小写其余主要词与五个字母以上的词均大写。Code Examples代码块的围栏语法与 Doxygen 限制C 代码示例应使用带cpp语言标注的围栏代码块~~~{.cpp} int main(int argc, char** argv) { .... } ~~~原文档中该示例本身采用了四空格缩进这正是下一条限制的直接体现由于 Doxygen 的 Markdown 解析器存在缺陷当前所有非 C 的代码块统一改用缩进而非围栏包裹。这条限制有明确的工程背景Mesos 的 API 文档由 Doxygen 从源码与main.dox统一生成Doxyfile 的INPUT配置同时包含了../include/、../src/与../src/main.dox而 src/main.dox 将 API 文档页与整体文档站点串联在一起。因此 Markdown 内容会被两套渲染器Middleman 站点与 Doxygen先后处理风格规则实际上是为“两者都能正确解析”而设计的折中方案。从仓库现状看~~~{.cpp}围栏在较新的文档中已广泛使用例如 docs/reconciliation.md、docs/health-checks.md 中的 C 示例以及 docs/app-framework-development-guide.md 中的~~~{.proto}与~~~{.sh}块均与本指南的写法一致。Notes、Emphasis 与行内高亮指南定义了三层行内强调约定1. 醒目提示NOTE——用于突出正文中重要的部分格式为加粗的**NOTE:**前缀**NOTE:** Short note. Continued longer note.2. 单个标识符高亮——用单反引号突出句中的特定标识符类型名、类名等Use the default HierarchicalDRF allocator....3. 命令高亮——示例命令同样使用单反引号mesos-master --help4. 文件与路径——文件、路径引用使用单反引号支持file://形式与绝对路径形式Remember you can also use the file:///path/to/file or /path/to/filedocs/configuration.md 的开头就是这一约定在实战中的直接应用mesos-master --help、--option_namevalue、MESOS_OPTION_NAME、file://path/to/file全部以单反引号行内高亮。Tables表格必须写成 HTML为了避免 Markdown 表格在渲染时出现格式问题指南要求直接用 HTML 书写表格并给出标准模板table table-striped为站点 Bootstrap 样式的斑马纹表格table classtable table-striped thead tr th width30% Flag /th th Explanation /th /thead tr td --ipVALUE /td td IP address to listen on /td /tr tr td --[no-]help /td td Prints this help message (default: false) /td /tr /table这一规则在仓库中有大量落地证据docs/configuration/master.md 中每个 flag 都遵循Flag列宽 30%/Explanation两列结构且带锚点的tr idquorum等写法便于按 flag 名定位docs/configuration/master-and-agent.md、docs/isolators/cgroups-cpu.md、docs/isolators/network-port-mapping.md 等页面也统一使用table classtable table-striped。撰写 flag 文档时应严格沿用这一结构。Indentation and Whitespace缩进与空行指南对空白字符的规定很严格Markdown 文件内不使用额外缩进章节标题之后一个空行章节与章节之间两个空行。原文给出的示范结构如下... end of previous section. ## New Section Beginning of new section ....这一约定保证了 Doxygen 与 Middleman 两套解析器对段落边界识别一致也是评审时格式检查的常见依据。渲染流水线从 docs/ 到线上文档理解风格规则“为什么必须这样写”的关键在于 Mesos 的文档生成流水线。以下机制均可在仓库源码中得到确认1. 站点构建使用 Middleman。site/config.rb 中配置了 Markdown 引擎与关键选项set :markdown_engine, :rdiscount set :markdown, :layout_engine :erb, :tables true, :autolink true, :smartypants true, :fenced_code_blocks true其中fenced_code_blocks: true解释了~~~{.cpp}围栏语法在站点侧可以被正确渲染而page /documentation/*, :layout documentation则解释了为何每篇docs/文档的 YAML front matter 都携带layout: documentation——docs/markdown-style-guide.md 自身的文件头即为--- title: Apache Mesos - Markdown Style Guide layout: documentation ---2. docs/ 目录被整体同步进站点源目录。site/Rakefile 的update_docs任务约 L20-L71完成了四件关键工作将docs/**排除docs/images拷贝到site/source/documentation/latest/由于 Middleman 对xxx.json.md这类文件名的限制把**/*.json.md迁移为**/*.json/index.md用正则批量改写文档内相对链接(xxx.md#anchor)重写为/documentation/latest/目录/xxx/#anchora hrefxxx.md同样处理images/...路径重写为/assets/img/documentation/...将home.md移动为latest.html.md并把docs/images/拷贝到site/source/assets/img/documentation/。这也解释了风格指南中“表格用 HTML、图片用相对路径”的原因这些链接会在发布前被脚本机械地重写写法不规范的链接会直接失效。3. 本地开发与构建。按 site/README.md 的流程先按构建说明编译 Mesos运行support/generate-endpoint-help.py生成 HTTP 端点帮助页然后执行./site/mesos-website-dev.sh启动 Docker 容器与 Middleman 开发服务器在http://localhost:4567预览站点该流程同时生成 Doxygen 与 Javadoc 输出可分别在/api/latest/c/index.html与/api/latest/java/index.html查看。Rakefile 的doxygen任务即调用doxygen ../Doxyfile并把 HTML 输出移入site/source/api/latest/c这正与风格指南中“非 C 代码块改用缩进”的 Doxygen 限制相互印证。正式发布由 ASF Jenkins 的 Mesos-Websitebot 任务完成见 support/jenkins/websitebot.sh开发者本人无需手工发布。编写文档的实操清单结合上述规范向docs/提交新页面或修改现有页面时可按以下清单自检内容层面新功能是否有独立 Markdown 文件代码中是否留下了指向文档的同步注释flag 变更是否同步到了docs/configuration/下的表格Front matter是否包含titleApache Mesos - 页面名格式与layout: documentation标题章节标题是否遵循 APA Title Case首词大写、主要词大写、五个字母以上词大写介词/连词/冠词小写且不作首词代码块C 用~~~{.cpp}围栏非 C 块遵循当前的缩进约定以兼容 Doxygen 解析器。强调重要提示用**NOTE:**前缀标识符、命令、路径用单反引号如mesos-master --help。表格一律使用table classtable table-stripedHTML 结构flag 列固定 30% 宽度。空白不额外缩进标题后一个空行章节之间两个空行。链接与图片文档内相对链接与images/相对路径按现有文档写法书写发布流水线会自动重写为站点绝对路径。遵循以上约定你的文档既能通过代码评审的格式检查也能在 Middleman 站点与 Doxygen API 文档两条渲染路径下都呈现正确。赞分享云原生【免费下载链接】mesosApache Mesos项目地址https://gitcode.com/gh_mirrors/mesos2/mesos点击查看免费下载相关推荐Apache Mesos 文档编写规范docs/ 目录 Markdown 风格指南全解Apache Mesos 文档编写规范docs/ 目录 Markdown 风格指南全解 本篇技术指南系统讲解 Apache Mesos 仓库 docs/ 目录云原生集群管理容器编排任务调度Apache Mesos Markdown 文档风格规范全解析标题、代码块、表格与发布链路Apache Mesos Markdown 文档风格规范全解析标题、代码块、表格与发布链路 本文是 Apache Mesos 仓库中 docs/markdow集群管理任务调度后端Apache Mesos 文档编写指南三种文档形态、风格规范与提交流程详解Apache Mesos 文档编写指南三种文档形态、风格规范与提交流程详解 本文以 Apache Mesos 仓库中的 docs/documentation云原生集群管理容器编排任务调度创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考