文章目录
任务描述
dtkcore等dtk模块一直因为文档而诟病，其实这么好的模块它是拥有文档的，但是文档并不符合我们认为的可维护标准，所以我们需要做一件事：在代码内部有且仅有英文注释存在，在代码外部的doc文件夹中书写符合doxygen标准的文档。所以你需要将代码中的中文注释移动到doc文件夹下，最好能够添加英文注释。
环境搭建
DTK环境
从源里安装包的版本不是最新的，推荐使用源码打包安装。
源码编译、安装dtk组件，请按照dtkcommon > dtkcore > dtkgui > dtkwidget的顺序编译，且保证dtkcommon、dktcore、dtkgui、dtkwidget的版本一致。这里直接拉取tags为5.6.4的源码
最后附有打包安装脚本
sudo apt update -y
# 安装开发环境
sudo apt install -y git qtcreator qt5-default qtdeclarative5-dev build-essential g++ cmake qttools5-dev devscripts doxygen graphviz fakeroot
# 安装dtk项目模板
sudo apt install -y qtcreator-template-dtk
dtkcommon
dtkcommon是构建DTK库的公共项目
mkdir dtkcommon-src && cd dtkcommon-src
git clone https://github.com/linuxdeepin/dtkcommon.git -b 5.6.4
cd dtkcommon
sudo apt build-dep .
dpkg-buildpackage -us -uc -b
sudo dpkg -i ../*.deb
dtkcore
dtkcore是DTK的核心组件，等同于Qt5中的core组件。Deepin系统默认安装该组件
mkdir dtkcore-src && cd dtkcore-src
git clone https://github.com/linuxdeepin/dtkcore.git -b 5.6.4
cd dtkcore
sudo apt build-dep .
dpkg-buildpackage -us -uc -b
sudo dpkg -i ../*.deb
dtkgui
dtkgui是DTK的图形核心组件，等同于Qt5中的gui组件。Deepin系统默认安装该组件，如需要重新安装请打开终端输入以下命令：
mkdir dtkgui-src && cd dtkgui-src
git clone https://github.com/linuxdeepin/dtkgui.git -b 5.6.4
cd dtkgui
sudo apt build-dep .
dpkg-buildpackage -us -uc -b
sudo dpkg -i ../*.deb
dtkwidget
mkdir dtkwidget-src && cd dtkwidget-src
git clone https://github.com/linuxdeepin/dtkwidget.git -b 5.6.4
cd dtkwidget
sudo apt build-dep .
dpkg-buildpackage -us -uc -b
sudo dpkg -i ../*.deb
shell脚本
新建脚本
xdg-open ~/Desktop/build.sh
#!/bin/bash
# 定义变量dtk相关的四个组件
DTK_LIST="dtkcommon dtkcore dtkgui dtkwidget"
VERSION="5.6.4"
sudo apt update
# 安装 git、Qt、编译工具集、源码编译DTK组件，则需要首先安装基础环境
sudo apt -y install git qt5-default qtdeclarative5-dev g++ cmake qttools5-dev build-essential devscripts doxygen graphviz fakeroot
# 安装 DTK 编译环境
sudo apt -y build-dep $DTK_LIST
# 在桌面创建目录存放源码
WORK_SPACE=~/Desktop/DTK_SRC && mkdir -p $WORK_SPACE && cd $WORK_SPACE
for project in $DTK_LIST;
do
mkdir -p $project-src && cd $project-src;
git clone https://github.com/linuxdeepin/$project.git -b $VERSION && cd $project;
sudo apt build-dep .;
dpkg-buildpackage -us -uc -b && sudo dpkg -i ../*.deb;
cd $WORK_SPACE;
done;
rm -rf $WORK_SPACE
授权
chmod +x ~/Desktop/build.sh
执行脚本
sh ~/Desktop/build.sh
任务流程
编写的文档主要是dtkcore、dktgui、dtkwidget
dtkcore仓库
dtkgui仓库
dtkwidget仓库
这里以dtkwidget为例，提交一个pr
fork仓库
将dtkwidget的代码fork一份到自己的仓库中。
将自己仓库的dtkwidget代码clone到本地
git clone https://github.com/linuxdeepin/dtkwidget.git
可以选择直接在主分支编写文档，或者选择新开分支编写，保证主分支干净
git checkout -b docs
这里新开docs分支
如果不会使用git命令，可以上网学习，这里不做介绍
推荐编辑器
推荐使用vscode 自带可视化的git，需要先用命令行安装git，前面已经安装过了
同步上游代码
方法一
通过github页面点击Sync fork按钮同步上游代码，我这里是在docs分支编写文档。
然后到本地拉取仓库代码
git pull github docs
ps: 默认是origin远程仓库直接使用git pull就默认拉取了，我这里是另外添加了远程仓库，远程仓库名为github
方法二
git remote add upstream https://github.com/linuxdeepin/dtkwidget
添加上游仓库
git remote -v
查看远程仓库
upstream远程仓库添加成功
git pull upstream master
拉取并合并上游的master分支的代码
如果本地没有任何提交，直接pull上游代码就可以了。
如果本地已经有提交的东西，而本地还没有同步上游（比如你在完成任务的时候，已经有人先提交了代码，而此时你还在开发，你已经落后上游分支了，看后面提交commit）
发起issue
先查看dtkwidget的代码，src下是需要编写文档的源代码，docs是对应的文档。
建议每次任务开始前先同步一下上游代码
git pull upstream master
这里的danchors.cpp源码，在docs下没有对应的danchors.zh_CN.dox文档。
发起一个issue
选择Docs update
填写相关信息
Document Type 填写Standardized documents，如果是添加dtk的使用例子选择Example documents。
file name为刚刚要添加文档的源文件名.h
Target files 填写源文件.zh_CN.dox
点击提交，与任务负责人联系，确认任务领取。
编写文档
需要将源码中的中文注释转移到dox文档中，并将源码的中文注释删去，只保留英文注释。
Doxygen 指令同时支持以 @ 或 \ 作为指令的标识字符。统一使用 @ 作为文档指令的前缀，例如使用 @fn 而不是 \fn。
ps: 不知道哪些需要修改，可以先参照前面已经提交过的pr对照源码查看哪些部分被修改了。docs类型的pr。
例如：
docs: update the document of DFloatingButton #305
可以查看接口文档一些常用的指令
C++ 项目接口文档手册
源码中的类及其函数不一定所有都被导出，所以需要先看一下哪些类及函数被导出了。
在已经安装好dtk环境的前提下，执行一下命令。
需要一些cmake的知识，下面是本人对cmake相关学习的一些记录，可能有些杂乱，建议有需要的可以自行整理。
cmake -Bbuild -DBUILD_DOCS=1 -DBUILD_THEME=1
这里的BUILD_THEME宏是默认关闭的，可以选择不添加，开启后编译的文档主题可能会更加美观，根据需要自行选择。
会在docs目录下，新建一个doxygen-theme目录下载相关主题，请保证git能够成功访问github，否则会因为网络问题导致下载失败，如果doxygen-theme目录下没有任何东西，请将该目录删除并重新执行上面的命令。（CMakeLists.txt中只对目录是否存在做判断，并没有判断下面是否有内容，所以直接删除重新执行才会下载内容）
cmake --build build --target doxygen
编译文档
xdg-open build/docs/html/index.html
打开文档
页面展示
点击类列表，查看一下danchors.h里相关的类哪些被导出了，下面两个类没有其他函数被导出，不用关注，主要编写上面三个类。
在danchors.cpp中是有中文注释的，我们需要将它转移到danchors.zh_CN.dox中，并将源代码的中文注释翻译成英文注释，注意修改标识字符，以及添加@~english标识，其他修改的细节内容可以对照已经提交的文档学习。
修改后。
检查
cmake --build build --target doxygen 2>&1 | grep "Dtk::Widget::DAnchorsBase::"
2>&1 将错误输出等同于标准输出，借助grep过滤出Dtk::Widget::DAnchorsBase::相关的结果，根据提示找到错误的信息进行修改
根据提示的文件以及行数找到并修改错误，重新执行指令dox文档没有其他错误即可。
xdg-open build/docs/html/index.html
打开页面检查一下
确认没有错误的显示和遗漏。
提交commit
下面是commit提交的信息规范，具体内容可以查看
Commit 提交信息规范
这里我们使用vscode提交commit信息
doc: update docs for danchors
更新danchors的文档
Log: update docs
Task: deepin-community/coding-quarter#26
此处Task后面的链接是在提交任务issue时对应的链接
点击添加并按commit
git log
终端使用git log查看已经提交的commit
提交成功。
此时上游可能已经更新了代码，那意味这我们的代码分支是落后上游的。
拉取上游代码
git fetch upstream master
那我们拉取上游的master分支，
fetch与pull的区别，fetch只拉取不合并，pull会拉取并进行合并。
有内容更新，继续进行后续操作，如果没有更新则不需要进行后续操作，直接push到自己的代码仓库。
变基
rebase的功能之一，合并分支，当我们的分支落后上游的时候可以使用该命令合并代码。如果有不懂的地方可以查看下面链接。
git base的介绍
git rebase upstream/master
此时我们再次查看我们已经同步了上游的代码。
接下来再进行push操作
推送代码
git push github docs:docs
我这里使用了docs分支，第一次提交远程还没有改分支。冒号左侧表示本地的分支，右侧是指远程分支，将本地的docs分支提交到远程的docs分支，当然如果不想创建远程分支，可以修改成docs:master，将本地的docs分支，直接推送到master分支上。
当远程分支存在与本地同名的分支时可以简写
ps: 我这里的github指的是我添加的远程仓库名，默认的远程仓库名为origin
git push github docs
提交成功
提交pr
我们打开dtkwidget仓库，找到Pull requests
https://github.com/linuxdeepin/dtkwidget/pulls
点击创建pr
会根据我们提交的commit信息自动识别内容，如果发现没识别成功，可以是填写的格式错误，或者本次的代码存在两次commit，最好一个commit只做一件事，此处#306是对应的issue，可以添加上，然后点击提交。
等待编译通过，如果是第一次提交pr，会提示签署协议，根据提示回复即可。
然后联系对应的reviewer，检查内容是否通过，如果出现错误，下面会讲如何重新提交，不需要重新提交一个pr，只需要将代码回退，修改后，重新推送到仓库即可。
重新提交
如果有问题需要修改
回退到上一次提交
git reset HEAD~1
然后进行修改，修改完毕后重新提交commit，和前面的流程一样。
拉取下上游看一下是否有更新
git fetch upstream master
没有更新那么不需要进行rebase
进行推送
git push github docs
但是我们进行了修改远程仓库已经和本地发生变化了，此时需要添加一个参数，-f （force 表示强制推送）
git push github docs -f
重新推送
回到前面提交pr的界面，可以看到刚刚更新的提交。等待编译通过，reviewer审核通过后合并即可。
审核通过。
发送指令合并。
关闭issue
回到前面将发起的issue关闭。
此时我们一次完整的文档编写任务就完成了。
最后进行同步上游合并。
git fetch upstream master
git rebase upstream/master
164
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
