昂信嵌入式 工程师指南¶

书写 Blog¶

我们鼓励工程师将日常工作的笔记以Blog的形式发表。 公开发表工作笔记，首先，便于客户了解我们的工作内容，增加与客户的交流。 第二，有利于工程师自己整理思路。 Blog不需要写的非常详细，不必写成文档的形式； 只需要将最核心的思想描述清晰就很好了。

因为我们的Blog系统是给程序员使用的， 所以将过去的wordpress迁移到jekyll系统。 Jekyll没有很好的图形界面，但是完全可以用git管理， 这是我们更喜欢的方式。

git clone https://github.com/EMSYM/octopress.git emsym
cd emsym
gem install bundler
bundle install
rake install
rake preview

write-doc-in-github¶

Sphinx是由python写成的文档编辑工具,语法简洁，方便使用。

readthedocs.org是一个网站，可以导入Sphinx文档，并且可以与git等代码库关联自动生成文档。

[使用方向] : 研发人员所开发的成果，要以文档的形式体现出。

• 网页文档是基于sphinx工具来做的，所以需要先安装sphinx文档工具，用命令行安装。

• 登陆github的EMSYM页面，网址：https://github.com/emsym

• 找到要写的文档仓库，复制版本库网址。

• 如果文件版本库不在自己的github库中，则需要先fork到自己的github库。
• 在Linux中打开终端，执行git clone下载此版本库到本地。

• 本地目录下就有了此版本库的文件夹。

• 打开文件夹，里面 .rst 就是可以打开编辑的文件。

• sphinx语法特列

• 新建文档:
• 在 index.rst 文件中的主标题之后，有一个内容清单，其中包括 toctree 声明。toctree 是将所有文档汇集到文档中的中心元素。如果有其他文件存在，但没有将它们列在此指令下，那么在构建的时候，这些文件不会随文档一起生成。
• 我们想将一个新文件添加到文档中，并打算将其命名为 blog.rst。还需要将它列在 toctree 中，但要谨慎操作。文件名后面需要有一个间隔，这样文件名清单才会有效，该文件不需要文件扩展名（在本例中为 .rst）。在文件名距离左边距有三个空格的距离，maxdepth 选项后面有一个空白行。

• 在blog.rst文件中添加内容，现在我们准备生成输出。
• 运行 make 命运，并将 HTML 指定为输出格式。可直接将该输出用作网站，因为它包含了生成的所有内容，包括 JavaScript 和 CSS 文件。

写好后提交代码，github会自动生成网页文档。

readthedocs使用文档¶

Sphinx是由python写成的文档编辑工具,语法简洁，方便使用。

readthedocs.org是一个网站，可以导入Sphinx文档，并且可以与git等代码库关联自动生成文档。

[使用方向] : 研发人员所开发的成果，要以文档的形式体现出。

建议地址 sphinx that

Git 使用文档¶

Git是一个分布式的版本控制系统。安装与学习这个软件，建议到官网学习。

我们所做的项目不可能是由一个人来完成，而是要一个团队。就会出现多人同时开发代码。

Git是提交代码的工具，使用中应当与我们在QA系统中提交的工作报告相一致。Git能够很好的对开发人员的代码进行版本控制。

Release workflow¶

github使用文档¶

GitHub 是开源的源代码管理网站，具体的学习请到官网查看。

Phabricator使用向导¶

Phabricator代替redmine，成为昂信嵌入式的最新的QA系统。 Phabricator是facebook.com的团队开发的，对于软件团队协作的意义巨大。 之所以从redmine迁移过来，是因为Phabricator支持代码提交的 前审核流程 。

前审核的概念：工程师修改的代码不会直接进入git版本库，而是先提交至QA； 再由另外（至少）一名工程师进行审核。直至审核通过后，方能够提交至git。 相当于一个人做作业，一个人检查错误，将显著提高准确率。 因此，这一套工作流程，保证我们的代码库的所有代码都是经过较有经验的工程师检验过， 提高代码的质量。