发展指南

本部分为希望为TomoPy项目做出贡献的开发人员解释基础知识。

使用GitHub

克隆存储库

该项目在GitHub上维护,GitHub是软件开发人员的版本控制和协作平台。第一个寄存器位于 GitHub and fork (make your own copy of) the TomoPy repository by clicking the Fork button in the header of the TomoPy repository

_images/fork-repo.png

这将在您的个人GitHub空间中创建项目的远程副本。接下来,将项目分支的副本克隆到本地计算机。您可以通过单击 Clone in Desktop 右手边栏底部的按钮:

_images/clone-in-desktop.png

这将启动GitHub桌面应用程序(两者均可用 MacWin )并询问您要将其保存在哪里。在您的计算机中选择一个位置,并轻松地在代码中进行修改。

提交更改

在代码中做了一些更改之后,获取一个 snapshot 你所做的编辑。那就是你做一个 commit 。为此,启动GitHub桌面应用程序,它应该会为您提供自上次提交以来代码中的所有更改。写一篇摘要 SummaryDescription 关于您所做的更改,然后单击 Commit 按钮:

_images/commit-screen.png

请记住,您编写这些消息是为了帮助其他人了解您对代码所做的更改。

发布您的更改

一旦您觉得您添加的功能将使社区受益,那么您应该考虑回馈TomoPy项目。您需要将本地提交推送到GitHub,然后转到项目的在线GitHub存储库并单击 green 按钮以比较、复查和创建拉式请求。

_images/create-revision.png

单击此按钮后,将显示一个审查页面,您可以在其中获得分支分支和原始TomoPy存储库之间到底发生了哪些变化的高级概述。当您准备好提交拉取请求时,请单击 Create pull request

_images/create-pr.png

点击 Create pull request 将您发送到讨论页,您可以在其中输入标题和有用的说明。重要的是要提供尽可能多的有用信息和理由,说明你为什么首先提出这个拉请求。

当你准备好输入你发自内心的论点时,点击 Send pull request 。你完蛋了!

建筑TomoPy

安装依赖项

要构建和运行TomoPy,您至少需要安装中列出的依赖项 envs/{platform}-{version}.yml 外加基于您的平台的其他依赖项。为方便起见,在Linux上构建Python3.6版本的安装要求可以按如下方式完成:

$ conda env create -f envs/linux-36.yml [-n ENVIRONMENT]

这将使用构建依赖项创建一个名为tomopy的新Conda环境。如果您已经有一个名为tomopy的conda环境。使用 -n 可以选择将其命名为其他名称。

其他Windows要求

Windows VC++2017编译器不能通过CONDA分发。该编译器的conda包创建了从系统提供的编译器到安装它的conda环境的链接。使用Windows生成工具安装程序安装VC++2017;生成TomoPy不需要使用Visual Studio(IDE)。

其他CUDA要求

CUDA编译器不能通过Conda分发。构建具有GPU功能的TomoPy需要CUDA工具包和NVCC。

编译TomoPy

TomoPy被构建/打包成两部分:仅支持python的模块和编译后的共享库。在导入时,Python模块在库路径中搜索已编译的共享库,如果没有找到,则发出错误/警告。因为编译部分和Python部分是分开的,所以开发Python部分不需要构建编译部分;可以使用conda预编译安装编译部分。

TomoPy(仅支持Python的模块)

在导航到 tomopy 目录中,您可以通过以典型的Python方式运行安装脚本来安装TomoPy:

$ pip install . --no-deps

Libtomo(编译后的共享库)

共享库是一个 CMake 以典型方式安装的项目::

$ mkdir build
$ cd build
$ cmake .. -GNinja -DCMAKE_INSTALL_PREFIX=$CONDA_PREFIX -DCMAKE_INSTALL_LIBDIR=lib
$ cmake --build .
$ cmake --install .

运行测试

TomoPy有一套Python单元测试,它们位于 /test 目录下的包遵循相同的树形结构。 /tomopy 。当您发出Pull请求时,TravisCI会自动运行这些服务(有关操作方法,请参阅下文)。您可以使用pytest或您喜欢的任何一种python测试运行器来手动运行它们。为了更容易对您对代码所做的更改运行测试,建议您在开发模式下安装TomoPy。 (python setup.py develop )

这个 pytest test runner ,可通过pip或anaconda获得。

要运行测试,请打开终端,导航到项目文件夹,然后运行 py.test

要运行测试的部分,请向py.test传递一个目录或文件路径,如下所示 py.test test/test_reconpy.test test/test_recon/test_rotation.py

在编写测试时,我们至少会尝试使用合成数据检查所有函数返回,以及一些维度、类型等。强烈建议您编写测试!

编码约定

我们尽量保持代码的一致性和可读性。因此,在开始编码之前,请记住以下样式和语法指南。

首先,代码应该被很好地记录,易于理解,并很好地集成到项目的其余部分。例如,在编写新函数时,请始终描述其用途和参数:

def my_awesome_func(a, b):
    """
    Adds two numbers.

    Parameters
    ----------
    a : scalar (float)
        First number to add

    b : scalar (float)
        Second number to add

    Returns
    -------
    output : scalar (float)
        Added value
    """
    return a+b

包版本控制

我们遵循X.Y.Z(主要、次要、补丁) semantic for package versioning 。对于不会更改软件API的微小更改和错误修复,补丁编号会递增。对于添加了新的但向后兼容的API功能的版本,次要版本是递增的,对于不向后兼容的API更改,主要版本是递增的。例如,依赖于API版本2.1.5的软件与版本2.2.3兼容,但不一定与3.2.4兼容。

我们使用git标记来管理我们的版本, setuptools_scm 包裹。