diff --git a/doc/source/codestyle.rst b/doc/source/codestyle.rst new file mode 100644 index 0000000000000000000000000000000000000000..9abae83336d627c7badc3060d7a8c206ea34eb32 --- /dev/null +++ b/doc/source/codestyle.rst @@ -0,0 +1,39 @@ +Numpydoc +======== + +More specifically, + +- PEP 7 – Style Guide for C Code: https://peps.python.org/pep-0007/ +- PEP 8 – Style Guide for Python Code: https://peps.python.org/pep-0008/ + + + +Numpydoc style, conf https://numpydoc.readthedocs.io/en/latest/format.html + + +标记语言 +======= + +标记语言(Markup language) 可以分为三类 + + - 展示标记(Presentational markup) + what you see is what you get + - 步骤标记(Procedural markup) + e.g., Markdown, TeX + - 描述标记(Descriptive markup) + e.g., LaTex, HTML, XML, ... + +我们着重介绍两种在Python编程中被广泛运用的标记语言——Markdown和reStructured Text。 + + 1. Markdown + Markdown可能是最轻量级的可用于层次化展示的标记语言, + 用户只需要学习为数不多的规则即可开始使用, + 并且在github等各种环境中均有插件支持。 + 通常可以使用Markdown格式编写程序说明(`README.md`) + 2. + + + +- reStructured Text + https://www.writethedocs.org/guide/writing/reStructuredText/ +- \ No newline at end of file diff --git a/doc/source/git.rst b/doc/source/git.rst new file mode 100644 index 0000000000000000000000000000000000000000..f81803556832e87908220d21ef020a0dcdcac3ed --- /dev/null +++ b/doc/source/git.rst @@ -0,0 +1,46 @@ +为什么需要版本控制 +=============== + +版本控制有两个最重要的好处,即 + + 1. 版本管理 + 在开发中,这是刚需,必须允许并且可以很容易地对软件版本进行任意回滚, + 版本控制工具实现这个功能的原理简单来讲,就是你每修改一次代码,它就帮你做一次快照(snapshot)。 + + 2. 写作开发 + 一个复杂点的软件,往往不是一个开发人员可以搞定的,为加快产品开发速度,需要有一群跟你一样的开发人员(developer)开发这个软件。 + 拿微信来举例,现在假设 3个人一起开发微信,A开发联系人功能,B开发发文字、图片、语音通讯功能,C开发视频通话功能, + B和C的功能都是要基于通讯录的,你说简单,直接把A开发的代码copy过来,在它的基础上开发就好了,可以。 + 但是你在他的代码基础上开发了2周后,这期 间A没闲着,对通讯录代码作了更新,此时怎么办? + 你和他的代码不一致了,此时我们知道,你肯定要再把A的新代码拿过来替换掉你手上的旧通讯录功能代码。 + 现在人少,3个人之间沟通很简单,但想想,如果团队变成30个人呢? + 来回这样copy代码,很快就乱了, 所以此时亟需一个工具,能确保一直存储最新的代码库,所有人的代码应该和最新的代码库保持一致。 + +版本控制的其他功能,例如,代码的approve-merge机制等,也在大型项目的开发中有重要意义。 + + +`git` +===== +`git` 是当前使用最广泛的版本控制协议,例如大家熟知的 `github.com` 就可以使用 `git`。 + + - 官方网站:https://git-scm.com/ + - 参考书《Pro Git (2nd Edition)》:https://git-scm.com/book/en/v2 + + +`git` 的基本使用 +=============== + +如何建库 +------- +在gitlab或者github页面中点击 `New Project` 即可在自己的账户下或者拥有权限的组织中新建代码库(repository)。 + + +克隆远程代码库到本地 +----------------- + + +CSST gitlab +=========== +CSST 项目利用国家天文台的服务器提供了GitLab服务,网址为 https://csst-tb.bao.ac.cn/code/。 + +其中,一级流水线的开发均在 `csst-l1` group中进行,链接为 https://csst-tb.bao.ac.cn/code/csst-l1 。 diff --git a/doc/source/index.rst b/doc/source/index.rst index 582ba6e633566cc2cecc969e4d00ae35b50b8e9c..ef0a1db141f8136f1d4826e3879e2a987daf88a5 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -3,8 +3,8 @@ You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. -csst_proto -========== +CSST一级流水线原型 +================ .. meta:: :description lang=cn: Automate building, versioning, and hosting of your technical documentation continuously on Read the Docs. @@ -20,22 +20,54 @@ csst_proto :maxdepth: 1 :caption: csst_proto -Hello! Welcome to `csst_proto`. -`csst_proto` is the CSST L1 pipeline prototype. +Hello! Welcome to `csst_proto` -- the CSST L1 pipeline prototype. -欢迎大家来到`csst_proto`的文档,这里是CSST一级流水线原型的文档。 +欢迎大家来到 `csst_proto` 的文档,这里是CSST一级流水线原型的文档。 -GitLab: -https://csst-tb.bao.ac.cn/code/csst-l1/csst_proto +`csst_proto` 是一个基于 `Python` 的程序包,目的是为一级流水线功能模块开发提供打包/封装的参考格式。 +程序源码以及文档的源码都可以在CSST Gitlab中找到: https://csst-tb.bao.ac.cn/code/csst-l1/csst_proto 。 +引用一句英语谚语:"Dress for the job you want, not the one you have." +一个优秀的程序库(repository)应该有许多理想的特征,包含但不限于: + - Use version control (使用版本控制,比如 `git`) + - Use tests (测试/单元测试) + - Have good documentation (有好的文档/注释) + - Use good structure (有好的结构) +尽管要在一个大的project中保持好的结构可能非常难,但这一定是优秀开发者的最求的目标。 + + +这里的主要内容包括 + + - 版本控制 (version control) + - how to use `git` + - 代码风格 (Code style) + - PEP8 for Python + - PEP7 for C + - Numpydoc + - 单元测试 (unit test) + - `unittest` + - `doctest` + - gitlab CI/CD pipeline + - 文件结构 (file structures) + - CSST一级流水线功能模块命名 + - + - 开发时间线 (timeline for CSST developers) + - C6 + - C7 + + + +最后放一个值得 CSST 团队学习的网站 + - LSST团队的内部开发指引:https://developer.lsst.io/ +希望这个网站对大家的开发有帮助! .. toctree:: :hidden: :maxdepth: 2 - :caption: unittest + :caption: version control - unittest.rst + git.rst .. toctree:: @@ -43,10 +75,18 @@ https://csst-tb.bao.ac.cn/code/csst-l1/csst_proto :maxdepth: 2 :caption: code style - numpydoc.rst + codestyle.rst sphinxdoc.rst +.. toctree:: + :hidden: + :maxdepth: 2 + :caption: unittest + + unittest.rst + + .. toctree:: :hidden: :maxdepth: 2 diff --git a/doc/source/unittest.rst b/doc/source/unittest.rst index 1cab618c0a0fa99b56169b201afc6e5b6f0aa483..9dbffba0a70c5afd52a606c0f63e54e8010907a0 100644 --- a/doc/source/unittest.rst +++ b/doc/source/unittest.rst @@ -1,7 +1,16 @@ -Unit test -========= +单元测试相关的pacakge +=================== use - `unittest` (https://docs.python.org/3.8/library/unittest.html) +- `doctest` - `pytest` (https://docs.pytest.org/en/stable/) +- `coverage` + + +gitlab CI/CD pipeline +===================== + +自动化流水线。 +