.. _code_standard:

=============
代码规范
=============

文档字符串
=========
Please use the `Numpydoc Style <https://stackoverflow.com/a/24385103>`_.

持续集成
======================
持续集成（CI）工具通过在每次推送新提交时运行测试并将结果反馈到拉取请求中，帮助您遵守质量标准。

当您提交PR请求时，可以在网页底部的"检查"部分查看您的代码是否通过了CI测试。

1. Qlib会使用black检查代码格式。如果您的代码不符合Qlib的标准（例如常见的错误是混用空格和制表符），PR将会报错。

   您可以通过在命令行输入以下代码来修复这个错误。

.. code-block:: bash

    pip install black
    python -m black . -l 120


2. Qlib will check your code style pylint. The checking command is implemented in [github action workflow](https://github.com/microsoft/qlib/blob/0e8b94a552f1c457cfa6cd2c1bb3b87ebb3fb279/.github/workflows/test.yml#L66).
   有时pylint的限制并不那么合理。你可以像这样忽略特定的错误

.. code-block:: python

    return -ICLoss()(pred, target, index)  # pylint: disable=E1130


3. Qlib will check your code style flake8. The checking command is implemented in [github action workflow](https://github.com/microsoft/qlib/blob/0e8b94a552f1c457cfa6cd2c1bb3b87ebb3fb279/.github/workflows/test.yml#L73).

   你可以通过在命令行中输入以下代码来修复这个错误。

.. code-block:: bash

    flake8 --ignore E501,F541,E402,F401,W503,E741,E266,E203,E302,E731,E262,F523,F821,F811,F841,E713,E265,W291,E712,E722,W293 qlib


4. Qlib已集成pre-commit，这将使开发者更容易格式化他们的代码。

   只需运行以下两条命令，在执行git commit命令时，代码就会自动使用black和flake8进行格式化。

.. code-block:: bash

    pip install -e .[dev]
    pre-commit install


=================================
开发指南
=================================

作为开发者，你经常希望对`Qlib`进行修改，并希望它能直接反映在你的环境中而无需重新安装。你可以使用以下命令以可编辑模式安装`Qlib`。
`[dev]`选项将帮助你在开发`Qlib`时安装一些相关包（例如pytest、sphinx）

.. code-block:: bash

    pip install -e ".[dev]"