updated doc

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

为什么需要版本控制

===============

版本控制有两个最重要的好处，即

    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 。

   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.

   :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一级流水线原型的文档。

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

   :maxdepth: 2

   :caption: code style

   numpydoc.rst

   codestyle.rst

   sphinxdoc.rst

.. toctree::

   :hidden:

   :maxdepth: 2

   :caption: unittest

   unittest.rst

.. toctree::

   :hidden:

   :maxdepth: 2

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

=====================

自动化流水线。