# 为XiUOS 完善网站文档

# 准备阶段

首先,从XiUOS文档主库中复刻一份到自己的个人空间。 假定您在Trustie的用户名为“panda”

# 步骤1:复刻

再在浏览器中打开XiUOS的文档项目首页https://forgeplus.trustie.net/projects/xuos/xuos-web, 点击右上角的"复刻" 按钮

这样您就在自己的个人空间中有了XiUOS文档库的一个复刻代码库, 地址为

项目首页为 "https://forgeplus.trustie.net/projects/panda/xuos-web"

代码库地址为 "https://git.trustie.net/panda/xuos-web.git"

# 步骤2 : 下载到本地,并配置

  • 从个人空间下载
git clone https://git.trustie.net/panda/xuos-web.git

警告

请务必记住,将panda替换为您自己的用户名

  • 配置
# 设置 upstream
git remote add upstream https://git.trustie.net/xuos/xuos-web.git
# 禁止直接向 upstream 推送代码
git remote set-url --push upstream no_push

# 步骤3 : 安装 yarn

首先

curl -sS https://dl.yarnpkg.com/debian/pubkey.gpg | sudo apt-key add -
echo "deb https://dl.yarnpkg.com/debian/ stable main" | sudo tee /etc/apt/sources.list.d/yarn.list

然后

sudo apt update && sudo apt install yarn

具体参见这里

# 步骤4 : 安装vuepress

安装vuepress需要依赖v10.x以上的node.js,在命令行输入以下命令以查看node.js版本

nodejs -v

如果版本过低导致安装失败,输入以下命令安装新版的node.js,其中版本号14可以根据node.js官网的最新版本更改

curl -sL https://deb.nodesource.com/setup_14.x | sudo -E bash -
sudo apt-get install -y nodejs

可以为所有项目安装全局的唯一 vuepress

yarn global add vuepress

也可以在vuepress 项目根目录下安装每个项目各自的vuepress

yarn add -D vuepress

每当做了改动,可以运行

yarn dev

yarn会编译文档, 并启动内置的web server. 在浏览器中访问 http://localhost:8080, 可观察网站效果

运行

yarn build

可在 docs/.vuepress/dist 中生成编译后的html页面, 可以单独启动一个web server观察效果,如

python -m http.server

# 工作阶段

# 步骤5 : 创建工作分支

为本次工作创建一个分支,命名为 develop

git checkout -b develop

# 步骤6 : work, commit & commit

此时就可以在该分支下工作了, 不断修改代码,不断 commit

git add .

git commit -m "your commit message"

# 步骤7 : push & push

如果经过测试,您觉得在本地完成了代码工作,您就可以将代码推送到您自己的服务器端的仓库中了。

git push origin develop

push到自己的服务器端库中后,就可以考虑创建合并请求(Pull Request)了, 为 此需要将本地库和upstream同步。

# 步骤8 : 和upstream 同步

git fetch upstream

git merge upstream/master

请确保本地您位于工作分支。如果合并过程有冲突,您要负责解决冲突,并提交。

然后将消解了冲突的最新本地代码,推送到个人服务器端仓库的develop分支。

git push origin develop

# 合并阶段

# 步骤9 : 合并请求(pull request)

到自己个人服务器端仓库的首页 https://forgeplus.trustie.net/projects/panda/xuos-web, 点击 合并请求 ,

设置源分支:

选择 设定的工作分支, 本文的例子是 develop 分支

设置目标分支:

目标仓库选择 upstream 库, 即: "泛在操作系统实验室/xuos-web"

目标分支选择 master

提交即可。

如果您的"合并请求"被核心开发者拒绝, 这种情况在开源社区很常见,所以请不要灰心失望, 请按照返回的意见修改完善,再提交即可。

# 更新本地和个人服务器端仓库的主分支

git fetch upstream
git checkout master
git merge upstream/master
git push origin master

# 用法举例

# 增加菜单栏选项的内容

在'社区'菜单栏中增加'测试文档'选项:

cd xuos-web/docs/.vuepress
vim config.js

找到'社区',在其中子目录添加

{
    text:'测试文档',
    link:'/community/testdoc.html'
}

找到'/community',在其子目录添加

[
  ['testdoc','测试文档'],
],

转到目录创建testdoc.md文件:

cd xuos-web/docs/community
vim testdoc.md

在文件testdoc.md中增加目标内容,如:test

查看网站修改情况

yarn dev

登录网站:http://localhost:8080/即可,查看确认无误之后

在目录xuos-web/docs/下

git add community/testdoc.md
git commit -m "change testdoc"
git fetch upstream
git merge upstream/master
git push origin BranchName

最终合并到目标仓库中完成修改

# 增加图片

在xuos-web/docs/doc/hardware/processor/riscv.md中增加图片img.png

可用方法:

cd xuos-web/docs/doc/hardware/processor/
mkdir imagesrc

将图片img.png放入文件夹imagesrc中 在riscv.md中需要用到该图片的位置添加

![Image description](./imagesrc/img.png)

图片添加完成。

Last Updated: 5/1/2021, 12:20:27 PM