- 机器学习
- 深度学习
- AutoML
- 大数据
- 后端
【免费下载链接】h2o-3
H2O is an Open Source, Distributed, Fast & Scalable Machine Learning Platform: Deep Learning, Gradient Boosting (GBM) & XGBoost, Random Forest, Generalized Linear Modeling (GLM with Elastic Net), K-Means, PCA, Generalized Additive Models (GAM), RuleFit, Support Vector Machine (SVM), Stacked Ensembles, Automatic Machine Learning (AutoML), etc.
本指南以 H2O-3 仓库内 h2o-docs-theme/demo_docs/source/demo.rst 这份 560 行的 reStructuredText（reST）语法演示文档为核心骨架，逐项解析 reST 的全部基础与进阶语法构造（标题结构、行内标记、各类列表、表格、脚注引文、目标引用、指令系统、替换文本、错误处理），并结合仓库内的 Sphinx 主题配置、构建脚本与 h2o-docs 目录下真实文档（如 flow.rst）给出源码级佐证。读完本文，你将掌握 reST 的完整语法要点，并能直接读懂、编写、维护 H2O-3 仓库中 h2o-docs/src 与 h2o-docs-theme 下的任何 .rst 文档，理解它们是如何经 Sphinx 渲染为 HTML 在线文档的。
一、reStructuredText 与 H2O-3 文档体系
reStructuredText 是一种面向文档结构化的轻量级标记语言，由 Docutils 项目定义并解析。它兼顾"人类易读的纯文本"与"可精确转换为结构化文档（HTML/LaTeX/man）"两个目标。demo.rst本身源于 Docutils 官方的语法演示文档（demo.txt），其文档末尾也注明了出处：
demo.rst from: http://docutils.sourceforge.net/docs/user/rst/demo.txt
在 H2O-3 仓库中，reStructuredText 是全部用户文档的书写语言：
- h2o-docs/src/product 下存放着 285 个
.rst文档（automl、gbm、glm、flow、data-munging、cloud-integration 等专题）； - h2o-docs-theme 则是文档站点主题（基于 Sphinx Read the Docs 主题的定制版），其中
demo_docs/source/目录就是用来演示和检验该主题渲染效果的示例文档集。
两者合起来构成了 H2O-3 完整的文档生成链路：作者书写 reST 源文件 → Sphinx 解析并调用主题模板 → 输出 HTML 站点。
1.1 文档构建配置（conf.py）解析
conf.py 是 Sphinx 构建的"总开关"，其中的关键配置决定了文档如何被解析与渲染：
| 配置项 | demo 值 | 含义 |
|---|---|---|
source_suffix | '.rst' | 源文件后缀，即文档全部使用 reST 编写 |
master_doc | 'index' | 文档树的根入口文档 |
extensions | sphinx.ext.autodoc、sphinx.ext.mathjax、sphinx.ext.viewcode | 启用自动文档（autodoc）、数学公式（mathjax）、源码查看（viewcode）扩展 |
html_theme | 'sphinx_rtd_theme' | HTML 输出使用 Read the Docs 主题 |
html_theme_path | ["../.."] | 主题查找路径指向仓库内的 sphinx_rtd_theme 目录 |
pygments_style | 'sphinx' | 代码高亮风格 |
project/version | 'H<sub>2</sub>O Documentation'/'1' | 站点标题与版本号，会在页眉页脚显示 |
主题本身的样式由 theme.conf 定义：
[theme] inherit = basic stylesheet = css/theme.css [options] typekit_id = hiw1hhg analytics_id = sticky_navigation = False它声明继承 Sphinx 内置的basic主题，并挂载css/theme.css定制样式；sticky_navigation = False表示侧边导航不随滚动固定。
1.2 构建命令（Makefile）
demo_docs/Makefile 是标准的 Sphinx 构建脚本，提供了十余种输出目标：
make html # 生成独立 HTML 页面，输出到 build/html make dirhtml # 生成目录式 HTML（index.html 嵌套结构） make singlehtml # 生成单个大 HTML 文件 make latexpdf # 生成 LaTeX 源并调用 pdflatex 编译为 PDF make epub # 生成 epub 电子书 make text # 生成纯文本 make man # 生成 man 手册页 make linkcheck # 检查所有外部链接完整性 make doctest # 运行文档内嵌的 doctest 示例其中html目标的执行本质是：
sphinx-build -b html -d build/doctrees source build/html二、文档骨架：标题、元数据与目录生成
demo.rst开头展示了 reST 文档的"头部结构"，这在 h2o-docs 的每个.rst文档中都是标准范式。
2.1 注释（Comment）
reST 注释以..（两个点加空格）开头，其后内容仅存在于源文件，不进入渲染结果：
.. This is a comment. Note how any initial comments are moved by transforms to after the document title, subtitle, and docinfo.注意一个细节：文档开头的注释在 Docutils 处理时会被自动移动到标题、副标题和文档信息（docinfo）之后。注释的另一条规则是：..后不能跟脚注、超链接目标或替换定义的语法，否则会被当成其他构造解析。
2.2 文档标题与副标题
reST 的标题用"下划线装饰线"（over/under-line）标记。等号=是最高层级标题，-是副标题（subtitle）：
================================ reStructuredText Demonstration ================================ -------------------------------- Examples of Syntax Constructs --------------------------------解析后，第一行标题成为<title>，下面的装饰线则被转换为文档的 subtitle 字段，并出现在 docinfo（文档信息块）中。
2.3 书目信息字段（Bibliographic Fields）
字段列表紧跟在副标题之后构成 docinfo 块。demo.rst完整演示了 Docutils 支持的字段写法：
:Author: David Goodger :Address: 123 Example Street Example, EX Canada A1B 2C3 :Contact: docutils-develop@lists.sourceforge.net :Authors: Me; Myself; I :organization: humankind :date: $Date: 2012-01-03 19:23:53 +0000 (Tue, 03 Jan 2012) $ :status: This is a "work in progress" :revision: $Revision: 7302 $ :version: 1 :copyright: This document has been placed in the public domain. :field name: This is a generic bibliographic field. :field name 2: Generic bibliographic fields may contain multiple body elements. :abstract: This document is a demonstration of the reStructuredText markup language, containing examples of all basic reStructuredText constructs and many advanced constructs.要点：
- 字段标记是"冒号 + 字段名 + 冒号"；
- 字段体可以包含多个缩进的正文元素（如
:abstract:的多段内容）； :Authors:（复数）与:Author:（单数）语义不同；- 内建的
:Dedication:、:abstract:等字段会被渲染为独立区块。
2.4 meta 指令与目录
.. meta:: :keywords: reStructuredText, demonstration, demo, parser :description lang=en: A demonstration of the reStructuredText markup language, containing examples of all basic constructs and many advanced constructs. .. contents:: Table of Contents .. section-numbering::meta指令为 HTML 输出注入<meta name="keywords">等元信息（对 SEO 与文档检索有直接价值）；contents指令根据文档章节标题自动生成目录（Table of Contents）；section-numbering则自动为各章节编号。
2.5 多文档组织：toctree
单篇文档的目录由contents生成，而多文档站点的导航树则由toctree指令负责。demo文档的入口 index.rst 是这样组织的：
Demo Docs ================================================= :Page Status: Incomplete :Last Reviewed: 2013-10-29 Contents: .. toctree:: :maxdepth: 2 demo listtoctree列出demo与list两个文档，:maxdepth: 2控制目录最多展开两级。这正是 h2o-docs 每个专题页（如>赞
- 机器学习
- 深度学习
- AutoML
- 大数据
- 后端
【免费下载链接】h2o-3
H2O is an Open Source, Distributed, Fast & Scalable Machine Learning Platform: Deep Learning, Gradient Boosting (GBM) & XGBoost, Random Forest, Generalized Linear Modeling (GLM with Elastic Net), K-Means, PCA, Generalized Additive Models (GAM), RuleFit, Support Vector Machine (SVM), Stacked Ensembles, Automatic Machine Learning (AutoML), etc.
相关推荐
PyInstaller 文档工程指南：基于 Sphinx 与 reStructuredText 的文档改进与构建实践
PyInstaller 文档工程指南：基于 Sphinx 与 reStructuredText 的文档改进与构建实践 本篇指南以 PyInstaller 官方开
开发工具构建工具H2O-3 文档工程全指南：Sphinx 用户手册、LaTeX Booklets 与 API 文档的构建体系
H2O 3 文档工程全指南：Sphinx 用户手册、LaTeX Booklets 与 API 文档的构建体系 本篇技术指南以 h2o 3 仓库的 h2o doc
机器学习深度学习AutoML大数据后端Django 文档构建指南：基于 Sphinx 与 reStructuredText 的文档生产体系全解析
Django 文档构建指南：基于 Sphinx 与 reStructuredText 的文档生产体系全解析 本篇以 Django 仓库中 docs/README
后端Web框架
