文章目录

任务描述
环境搭建
- DTK环境
- - dtkcommon
  - dtkcore
  - dtkgui
  - dtkwidget
  - shell脚本
任务流程
- fork仓库
- 推荐编辑器
- 同步上游代码
- - 方法一
  - 方法二
- 发起issue
- 编写文档
- - 检查
- 提交commit
- 拉取上游代码
- 变基
- 推送代码
- 提交pr
- 重新提交
- 关闭issue

任务描述

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;domkdir -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命令，可以上网学习，这里不做介绍

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的一些学习记录

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 docsTask: 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

如何进行dtk文档的编写相关推荐

WINUSB设备的inf文档的编写
<WINUSB设备的inf文档的编写> 目录简介... 1 1. 获取inf文件和cat文件模板... 1 1.1 创建WinUSB应用程序... 1 1.2 ...
Deepin、DTK 文档参考集合
简述: 整理收集 DTK 相关资料. 文章目录 DTK 文档集合文档交流源码内网交流: 本文初发于 "偕臧的小站",同步转载于此. DTK 文档集合文档 DTK 介绍. ...
项目方案-标书-文档等等编写规范
文章目录背景文档要求背景作为一个社会人,经常需要面对文档,无论是程序员.项目经理.售前.售后等等,都需要面对文档,但是我目前位置,对于文档还是一知半解.所以收集了一些对编写文档有用的干货并持续 ...
java文档注释编写格式
java 文档注释在sun主页上有java文档注释的编写格式 How to Write Doc Comments for the Javadoc Tool http://java.sun.com/j ...
需求分析及需求文档的编写
通常,软件开发工程师和软件测试工程师的工作都开始于软件需求说明书成型的基础上.那么软件需求说明书到底是怎么来的,软件的需求分析到底怎么做?今天我就针对这个话题结合我自己的一些理解和经历来梳理一下. 需 ...
接口文档如何编写，接口文档快速生成工具
正规的团队合作或者是项目对接,接口文档是非常重要的,一般接口文档都是通过开发人员写的.一个工整的文档显得是非重要.下面我总结下自己看到的优秀接口文档. 一.背景介绍接口:API API(Applic ...
项目规划和方案设计文档的编写
引言在工作中,很多时候,我们都需要就一个问题提出一个解决方案,这时候,我们很可能需要产出一个文档来供大家讨论,并指导下一步工作计划.这个文档便是所谓的设计文档. 问题可大可小,形式上是否叫它为一个项 ...
软件设计文档如何编写，设计文档内容都包括什么
我们经常听到这样的话: "设计文档没有用,是用来糊弄客户和管理层的文档": "用来写设计文档的时间,项目开发早就做完了": "项目紧张,没有时间做设计 ...
SAP 电商云 Spartacus 5_0.md 迁移文档的编写格式
ng-container which wrapped div.row.cx-checkout-btns has been removed. 上述选择器,首先确认描述的是一个 div 元素.这个元素同时 ...

如何进行dtk文档的编写