• GitHub: https://github.com/MacHu-GWU/Python-with-GitHub-PyPI-and-Readthedoc-Guide
• PyPI: https://pypi.python.org/pypi/canbeAny
• Tutorial (教程请戳我): http://www.wbh-doc.com.s3.amazonaws.com/Python-with-GitHub-PyPI-and-Readthedoc-Guide/index.html

注: 本页面是文档首页的源码, 请移步 教程 观看图片完整的文档。

前言:

本文提供的演示项目的网址: https://github.com/MacHu-GWU/Python-with-GitHub-PyPI-and-Readthedoc-Guide, 可以用于跟着本文的介绍, 完整地练习一遍。

• 示例Github项目主页: https://github.com/MacHu-GWU/windtalker
• 示例PyPI页面: https://pypi.python.org/pypi/windtalker
• 示例在线文档网站: http://windtalker.readthedocs.org/

传送门:

• 使用Github保管你的代码库
• 创建你的setup.py文件
• 部署你的项目在PyPI上的主页
• 让你的包能通过pip install被安装
• 部署你的文档网站
• Readthedoc简明介绍

正文 ~~ 当你开始使用第三方Python扩展包时, 经常看到各种各样的第三方Python扩展包有完整的:

• 项目主页
• Github代码库: https://github.com/
• PyPI页面, 支持pip下载: https://pypi.python.org/
• 漂亮的在线文档网站: https://readthedocs.org/

很羡慕是不是? 别着急, 本文就是要详细地介绍在项目开发完成之后, 用Github保管你的代码, 如何添加到Pypi, 部署你的在线文档网站。更进阶地, 还要教会你如何在版本更新时, 用最少的工作更新这些事情。

一个组织良好的Python扩展包项目的文件结构看起来应该是这样的:

<project_name> # 项目名称
        |--- build # setup.py 生成的build文件, sphinx生成的html网站
        |--- source # document 源代码
        |--- tests # 单元测试 (可选)
        |--- <package_name> # 你开发的扩展包的名字, 你的Python代码都在这里了
        |--- LICENSE.txt # 版权信息
        |--- requirements.txt # 为pypi提供了所依赖的其他包的信息
        |--- MANIFEST.in # PyPI上传安装包时候的发布文件信息
        |--- setup.cfg # setup的额外配置信息
        |--- setup.py # 安装文件
        |--- readme.rst (or readme.md) # github, pypi项目主页说明文档
        |--- make.bat # sphinx用于生成网站的批处理文件

对于 MANIFEST.in 文件, 需要特别注意: 和 package_data 不同的是, 这个储存的是包之外的文件。 详情请看: https://docs.python.org/2/distutils/sourcedist.html#manifest-template

另外地, 出于个人开发方便起见, 有一些自定义的文件, 目前就不进行详细介绍了。

<project_name>
        |--- build_dist.bat    # 用于一键生成安装包, 在执行 pypi upload 命令先试用, 看是否和你预期要上传到PyPI的内容一致
        |--- build_doc.bat     # 用于一键重新安装package到本地, 执行 create_doctree.py, 执行 make.bat
        |--- install.bat       # 用于一键安装package到本地, 替换已装的版本
        |--- pypi_register.bat # 用于一键上传package信息到pypi
        |--- pypi_upload.bat   # 用于一键发布当前版本到pypi
        |--- view_doc.bat      # 用于一键打开build好的网站主页
        |--- create_doctree.py # 用于生成 module and index 的源文档的脚本

如何使用Github管理你的代码版本, 并不在本文的讨论范围之内, 请自行咨询 谷神, 度娘。

Github提供了一个 release 功能, 其功能是将你当前Commit的代码库打包成一个 .zip 和 .tar.gz 文件, 并加上标签。然后其他人就可以通过 https://github.com/<username>/<project_name>/archive/<tag>.zip 进行下载了。所以在PyPI页面或者其他页面, 只要你附上这个链接, 别人就可以直接下载你的源代码。在 setup.py 中专门有一项 download_url 就是起这个作用的。这个下载链接在之后的PyPI页面中会用到。

具体管理tag的方法, 你可以使用:

1. Github网页界面: Github repository -> release (推荐)。 2. 在github shell中使用 $ git tag ... 命令。在git中管理tag请参考: https://git-scm.com/book/en/v2/Git-Basics-Tagging

很久以前Python社区为了让大家能够更佳容易地发布自己的开源扩展包, 所以在标准库中包含了 distutils 库帮助用户distribute自己的扩展包。

在PyPI社区壮大, 成为Python扩展包的主发布社区后, 出现了 pip 这一跨平台的工具使得用户进行管理自己的Python第三方包变得异常轻松。在用户安装 pip 时, 另一个强大的工具 setuptools 也会被自动安装。这一工具不仅是 pip 所依赖的, 而且可以替代 distutils, 用更简单的方式完成更复杂的工作。

• 如何写setup.py文件: https://docs.python.org/2/distutils/setupscript.html

关于setup.py文件的详细介绍, 我会在我的 另一篇文章 中详细陈述。

我们以 requests 这一Python社区最流行的http扩展包(作者是Python社区顶级大牛, 他的项目值得每一个Python开发者作为教科书来学习, 无论是代码还是文档)为例进行解说。

首先我们来看看PyPI页面有哪几个主要元素?

1. Long Description, 一段长的文本介绍, 介绍你的扩展包的所有相关信息。

这部分用 reStructuredText 标记语言所写成。通常使用 readme.rst 文件中的内容, 同时也通常被作为github主页的页面。值得注意的是, 这部分内容中使用的是纯rst文件所支持的语法。并不支持sphinx中所支持的特殊语法。

2. File, 用户可下载的文件。

这部分默认会包含一个源代码包, 通常文件名是 <package_name>-<version>.tar.gz。这部分是当用户使用 pip install package_name 时所下载的源码包, 然后 pip 会自动完成 build, install, clean up的全过程。 这个源码包的生成是自动的, 具体原理在下一节中介绍。

同时用户还可以自己上传一些其他格式的安装文件, 比如: .egg, .whl, .zip, .exe (用于windows下的安装)。我们可以通过命令:

        $ python setup.py sdist upload -r pypi

上传, 也可以登录你的PyPI, 找到你的包, 然后使用网页界面手动上传。其他安装包的制作和上传, 请参考: `The Python Package Index (PyPI) <https://docs.python.org/2/distutils/packageindex.html>`_

3. MetaData, 其他相关信息。

这里存放的是你在 setup.py 文件中填写的例如: Author, Home Page, Lisence。这部分可以在 setup.py 中定义, 也可以在PyPI网站界面进行手动填写。

了解其他的 meta-data field 请戳这里

当用户完成了 setup.py 文件的制作之后, 就可以将这些信息**注册到PyPI了**。具体做法是在命令行中输入如下命令:

$ python setup.py register -r pypi

第一次注册时, 会需要你的PyPI账号密码, 然后系统会在你的操作系统用户根目录下生成一个.pypirc文件, 里面包含了你的身份信息。在同一台机器同一个账户, 以后就不会需要输入账号密码了。

如果你有仔细阅读上一节的内容, 其实在 File 部分中所提到的一个默认的源代码包。(可以没有其他 .whl, .exe 但一定会有的源码包)。使用下面的命令所上传的安装包是带有版本信息记录的, 只要你上传过一次, 就会在PyPI服务器上留下记录, 以同样的软件版本号无法再次上传。当开发流程熟悉稳定之后, 用户可以使用 upload 命令上传所有种类的安装包。但我推荐新手自己build安装包, 然后针对一个版本号在网页界面进行手动上传, 删除管理。

为防止忘记, 附上上传默认源码安装包的命令:

$ python setup.py sdist upload -r pypi

在 sphinx 的帮助下, 我们完全可以将生成的静态网页部署在自己的网站上。例如 Amazon Web Service S3 就是一种很方便很便宜的选择。既然如此, 那 https://readthedocs.org/ 的好处是什么呢?

1. 完全免费。 2. 自动关联Github账户, 当有更新时, 自动更新网站。 3. 同时维护多个版本的文档。让使用老版本用户也能看到老版本的文档。 4. 可以关联google analytic, 追踪访问量。

如果使用自己的网站, 每当你有更新时, 你都要更新你的网页文件。而如果使用readthedoc, 当你的source目录内的文件在Github上有更新, readthedoc会自动检测到更新, 并重新build所有页面。所以你所要做的就是在commit之前, 在本地使用 make_html.bat build一次网页, 确认无误之后更新到github即可。

注意: 如果你的包对其他第三方包的依赖较大, 那么就需要设置requirements.txt, 以及virtual environment。requirements.txt告诉readthedoc在build的时候要安装哪些依赖的包, virtual env能配置出合适的虚拟环境。这是因为sphinx在build网页的时候, 要保证包里所有的模块都是可以被import的。这算是使用readthedoc的一个不好的地方吧。

• 问: 我申请了readthedoc账号, 第一件事要做什么?

从github导入你的项目。具体方法是:

1. 登陆你的github, 进入你的github repository 2. settings -> webhooks & service -> add readthedoc 3. 回到readthedoc, Import a project -> Import from github -> 找到你的项目 -> Create

• 问: 我已经导入了我的项目了, 那怎么让readthedoc开始生成我的文档网站?

首先你要进行一些设置, 告诉readthedoc一些信息:

1. 进入你的readthedoc project 2. 进入Admin菜单 3. 进入Setting菜单 4. 指定Programming language = Python。(我们都是大蟒蛇~) 5. 进入Advance菜单 6. 如果你的包依赖其他第三方库, 请勾选: Install your project inside a virtualenv using setup.py install. 并指定requirement file, 通常为 requirements.txt。这样在尝试Build网站时, readthedoc就会使用 pip 把 requirements.txt 中的包都安装了。 7. 如果你只想要保留最新的文档(通常需要保证你的库向下兼容), 请勾选: Single version 8. 在 Python configuration file: 一栏中填写从项目目录到 Sphinx 的 conf.py 的路径。这样readthedoc才能找到你的文档放在哪里了。 9. 在 Python interpreter 中选择Python2/3。保持这个和你开发时测试所使用的一致。 10. 如果想要用Google Analytic, 填写 Analytics Code

然后回到readthedoc project页面, 进入Build菜单, 如果还没有开始自动Build, 则点击Build。如果发生Failed, 点击Failed查看错误信息。如果Passed, 恭喜你, 可以点击View Docs浏览你的文档了!

至此, 你应该可以顺利的完成, 源代码保管在github, 在pypi发布你的扩展包, 支持pip install安装和发布你的在线文档网站了。撒花, 撒花!

CopyRight: Sanhe Hu 2015, 转载请注明出处