快速生成ACRN文档so easy

Larry 发布于 2018/05/25-00:20 标签：ACRN文档，本地系统

这些说明将指导您生成ACRN项目的文档，并且将其发布到https://projectacrn.github.io网站上。您也可以使用这些说明在本地系统生成ACRN文档。

文档概览

ACRN项目内容使用带有Sphinx扩展名的reStructuredText标记语言编写（.rst 文件扩展名），并且使用Sphinx进行处理且创建一个格式化的独立网站。开发者可以用诸如.rst标记文件的格式来式查看这些内容，也可以生成HTML内容并在工作站点通过浏览器直接查看。

您可以从reStructureText和Sphinx的网站阅读关于它们的详细内容。ACRN项目的文档包含以下条目：

• 用来产生文档的ReStructuredText 资源文件可以在http://projectacrn.github.io站点找到。所有reStructured 源文件可以在acrn-document repo中找到。

• 用于创建所有特定API文档的Doxygen生成资料可以在http://projectacrn.github.io/api/站点找到。克隆acrn-hypervisor也用于访问API的头文件。

reStructuredText文件使用Sphinx文档系统来处理，并且利用breathe扩展来包含doxygen生成的API材料。

设置建立文件夹来开始文档的产生
你需要安装git来设置工作文件夹：
• 在Ubuntu开发系统上，请使用: sudo apt-get install git
• 在 Fedora 开发系统上，请使用：sudo dnf install git

因为我们需要最新的头文件生成API文档，所以文档生成假定在某一个目录里克隆acrn-hypervisor repo。以下是针对文档贡献和生成所推荐的文件夹设置：

最好在这些文件夹里使用ssh模式克隆upstream ACRN项目repo的私人分支。（drank可以通过https模式克隆也可以工作）：

1 使用浏览器访问：https://github.com/projectacrn。并访问, acrn-hypervisor, repo，并且点击fork按钮在您的个人Gitbub账户里创建个人分支。

2 在命令提示处，创建工作文件夹，并将三个存储库复制到您的本地电脑：

mkdir –p ~/projectacrn

cd ~/projectacrn

git clone git@github.com:<github-username>/acrn-hypervisor.git

3 对于每个克隆到本地的repo，使用git remote模式添加upstream
repo：

cd
~/projectacrn/acrn-hypervisor

git remote add
upstream https://github.com/projectacrn/acrn-hypervisor.git

4 如果您还没有这样做，一定要使用在您提交信息的签名信息行中显示的名字和邮箱地址来配置git：例如

安装文档工具

我们的文档处理在如下的版本软件下已经进行过测试：
• Python 3.6.3
• Doxygen 1.8.13版本
• Sphinx 1.6.7版本
• Breathe 4.7.3版本
• docutils 0.14版本
• sphinx_rtd_theme 0.2.4版本

根据您的Linux版本，安装需要的工具：
• 在Ubuntu上，请使用:
• 在Fedora上，请使用:对于任何Linux环境，都需要安装其余的基于python的工具：

cd ~/projectacrn/acrn-hypervisor/doc

pip3 install
–user –r scripts/requirements.txt

有了这些，您已经准备好生成文档。

文档演示主题
Sphinx支持通过主题轻松定制生成文档外观。替换主题文件并执行make htmldocs命令，从而更改输出布局和样式。read-the-docs主题作为上面的requirements.txt列表的一部分进行安装。

运行文档处理器

acrn-documentation目录包含所有.rst源文件、额外工具和用来生成ACRN技术文档本地副本的Makefile。

cd ~/projectacrn/acrn-hypervisor/doc

make html

根据您的开发系统，大约需要花费15秒收集和生成HTML内容。完成以后，您可以使用浏览器打开~/projectacrn/acrn-documentation/_build/html/index.html文件查看HTML输出。

发布内容

如果您拥有ACRN project的projectacrn.github.io的repo推送权限，您可以更新https://projectacrn.github.io中的公共项目文档。

你将需要使用ssh模式克隆做一次upstream repo：
git clone git@github.com:projectacrn/projectacrn.github.io.git

然后，当你验证了使用make html生成HTML看起来不错后，你可以使用make publish命令直接推送到站点：

make publish

这将删除发布repo中的所有内容（例如新版本已删除文件），并将新生成的HTML内容的副本直接推送到GitHub页面的发布repo。公共站点https://projectacrn.github.io将立即更新。因此最好在发布之前验证下本地生成的html文件。

过滤预期的警告
doxygen/Sphinx/Breathe处理存在一些已知问题，这些问题会导致对某些构造产生相应的警告，尤其是在嵌套联合和机构中未命名的构造。虽然正在考虑修复这些Sphinx/Breathe问题，但是我们在文档构建处理的输出增加了一个后处理过滤器，从而以便于检查生成过程中的“预期”信息。

来自Sphinx构建的输出已经使用 scripts/filter-known-issues.py 脚本和.known-issues/doc目录下的一系列过滤配置文件进行处理。（这个过滤是作为Makefile的一部分完成的。）

如果您的贡献组件包含在ACRN API文档中，并且碰到了这些警告，你可以模仿找到的其它conf例子来添加一个conf文件到.known-issues/doc文件夹，从而可以将其作为“预期”警告信息过滤包含进来。

喜欢（0）