关于本网站¶
该网站使用 Sphinx (2.4.4) 构建，这是一个用于创建官方 Python 文档和其他许多网站的开源工具。这是一个非常成熟和稳定的工具，它被选中是因为它支持定义 API 项目并从代码中链接到它们，以及其他原因。
该网站使用自定义主题，该主题基于 Read the docs 主题.
搜索网站¶
搜索返回包含 **所有** 指定关键字的主题。
提示
始终从搜索单个词开始，例如“交互”或“编译”。通常这足以找到相关的文档。如果没有，您可以通过添加其他词来细化搜索。
注意
包含“-”和“+”等字符的搜索将不起作用。不支持逻辑运算符。
报告错误¶
为本网站做贡献¶
贡献 到这个网站（以及实际上 Emscripten 的任何部分）都是受欢迎的！
构建网站¶
网站源代码存储在 GitHub 上。编辑和添加应该以与对工具的任何其他更改相同的方式提交到此分支。
该网站发布到 emscripten-core/emscripten-site gh-pages 分支（GitHub Pages）。
注意
请记住为 公开 构建更新 构建版本。
安装 Sphinx¶
此网站需要安装特定版本的 Sphinx。运行以下命令以确保您安装了正确的版本
pip install -r requirements-dev.txt
网站构建¶
可以在 Ubuntu 和 Windows 上从源代码构建网站，方法是导航到 /emscripten/site 目录并使用以下命令
make clean
make html
SDK 构建¶
SDK 构建与 网站构建 几乎相同。主要区别在于 SDK 构建中 主页 有一个明确的通知，表明它是 SDK 构建。
SDK 构建通过启用 sdkbuild 标签来启用。这是通过 SPHINXOPTS 环境变量完成的
# Set the sdkbuild tag.
set SPHINXOPTS=-t sdkbuild
make html
# Unset SPHINXOPTS
set SPHINXOPTS=
构建版本¶
文档版本应与当前构建的 Emscripten 版本匹配。对于一般网站构建，这将是最新标记的版本，如 Emscripten 版本 中所定义。对于 SDK 构建，这将是 SDK 的 Emscripten 版本。
版本和发布信息在文档中的几个地方使用，例如 作者。
版本信息定义在 conf.py 中 - 请参见变量 version 和 release。这些变量可以通过在 SPHINXOPTS 环境变量中设置新值来覆盖。例如，要在 Windows 上通过命令行更新 release 变量
# Set SPHINXOPTS
set SPHINXOPTS=-D release=6.40
make html
# Unset SPHINXOPTS
set SPHINXOPTS=
编写和更新文章¶
网站内容使用 reStructured text 编写。我们建议您阅读以下文章以了解语法
风格指南¶
本节提供了一些非常简短的建议，以帮助作者使用通用的风格。
提示
在贡献方面，我们更看重您的代码和内容写作，而不是完美的文风！尽力而为，然后 请求编辑审核。
**拼写：** 尽可能使用美式英语拼写。
**避免习语：** 这些习语对非母语人士来说尤其令人困惑（例如，“说错话”实际上意味着“说了一些令人尴尬的话”）。
强调
**粗体**：用于文件名和 UI/菜单说明（例如：“按 **确定** 执行某项操作”）。
斜体：用于工具名称 - 例如 Clang、emcc、Closure Compiler。
monotype：用于内联代码（无法链接到 API 引用时）以及演示工具命令行选项。注意
除了上述规则外，应谨慎使用强调。
**列表：** 在适当的情况下，在列表的开头使用冒号。将第一个字母大写，并为每个项目使用句点。
如何链接到文档或标题¶
要链接到页面，首先在页面标题之前定义一个全局唯一引用（例如 _my-page-reference），然后使用 ref 角色链接到它，如下所示
.. _my-page-reference:
My Page Title
=============
This is the text of the section.
To link to page use either of the options below:
ref:`my-reference-label` - the link text is the heading name after the reference
ref:`some text <my-reference-label>` - the link text is "some text"
这比使用 :doc: 角色链接到文档更好的方法，因为即使文章被移动，链接也不会断开。
这种方法也推荐用于链接到网站中的任意标题。
注意
还有许多其他角色可用于链接 - 包括用于链接到代码项目的 Sphinx 域，以及用于链接到术语表条目的 **term**。
推荐的章节/标题标记¶
reStructured text 定义 章节标题，在标题文本之后（以及可选地在之前）使用单独一行标点符号。标点符号行必须至少与标题一样长。例如
A heading
=========
不同的标点符号用于指定嵌套的章节。虽然系统没有规定每个嵌套级别使用哪种标点符号，但保持一致非常重要。推荐的标题级别如下
=======================================
Page title (top and bottom bars of "=")
=======================================
Level 1 heading (single bar of "=" below)
=========================================
Level 2 heading (single bar of "-" below)
-----------------------------------------
Level 3 heading (single bar of "+" below)
+++++++++++++++++++++++++++++++++++++++++
Level 4 heading (single bar of "~" below)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
在 Markdown 中工作¶
新文章可以在 wiki 上使用 Markdown 语法进行创作和讨论，然后将其包含在文档集中。将它们转换为 reStructured text 的最简单方法是使用 Pandoc 等工具。
注意
get_wiki.py 工具（/site/source/get_wiki.py）可用于自动获取 wiki 的快照。它克隆 wiki 并对每个文件调用 pandoc。输出被复制到 wiki_static 文件夹。该工具还添加了一个标题，一个说明文件是“wiki 快照”的注释，并修复了标记为“内联代码”的链接，使其与 API 引用中的匹配链接相匹配。
Read the docs 主题¶
该网站使用 Read the docs 主题 的修改版本（可以在 /emscripten/site/source/_themes/emscripten_sphinx_rtd_theme 中的源代码中找到）。
对原始主题的主要更改如下所示。
Footer.html
版权已更改为链接到 Emscripten 作者（一些代码被翻译标记破坏）
添加了页脚菜单栏
Layout.html
添加了带有项目的页眉菜单栏
Breadcrumb.html
将第一个链接的文本从“docs”更改为“Home”
将“View Page Source” 代码移到了底部页脚
theme.css
更改为支持侧边栏 toc 中的 4 个深度级别。
将主题居中。使用绝对定位使侧边栏到达页面底部。