Python-Deployment

Python部署工作流程示例

使用 Sphinx 和 Read the Docs 的文档

设置 Sphinx

为了从文档字符串生成文档，我们将使用 Sphinx。

1. 在项目的根目录下创建一个 docs 目录。

mkdir docs
cd docs

2. 使用 Sphinx 提供的 quickstart 脚本。

sphinx-quickstart

并使用以下设置。

3. 修改 source/conf.py。首先需要取消注释并修改文件顶部的以下行。

import os
import sys
sys.path.insert(0, os.path.abspath('../../'))

还需要添加一些额外的扩展。 autosummary 扩展从文档字符串生成函数/方法/属性摘要列表，napoleon 允许 Sphinx 解析 Numpy 和 Google 风格的文档字符串。最后，numpydoc 扩展加载了几个扩展，以更好地支持 Numpy。

extensions = ['sphinx.ext.autodoc',
    'sphinx.ext.intersphinx',
    'sphinx.ext.coverage',
    'sphinx.ext.imgmath',
    'sphinx.ext.ifconfig',
    'sphinx.ext.viewcode',
    'sphinx.ext.autosummery',
    'sphinx.ext.napoleon',
    'numpydoc']

还需要一些其他更改

• master_doc = 'contents' 以获得更好的概览页面，稍后我们将添加它。
• html_style = 'sphinx_rtd_theme' 以获得更美观的主题。
• 为了与 Read the Docs 兼容

html_theme_options = {
    #    'canonical_url': '',
    #    'analytics_id': '',
    'logo_only': False,
    'display_version': True,
    'prev_next_buttons_location': "top",
    #    'style_external_links': False,
    #    'vcs_pageview_mode': '',
    # Toc options
    'collapse_navigation': False,
    'sticky_navigation': True,
    'navigation_depth': 4,
    'includehidden': True,
    'titles_only': False,
}

• 取消注释 # html_static_path = ['_static']
• 如果您使用托管在某处的图片，请添加

suppress_warnings = [
    "image.nonlocal_uri",
    #    'app.add_directive',  # this evtl. suppresses the numpydoc induced warning
]

• 最后，添加一些 intersphinx 映射以进行链接

intersphinx_mapping = {
    "Python 3.7": ("https://docs.pythonlang.cn/3.6", None),
    "Python": ("https://docs.pythonlang.cn/", None),
    "NumPy": ("https://docs.scipy.org.cn/doc/numpy/", None),
    "SciPy": ("https://docs.scipy.org.cn/doc/scipy/reference", None),
    "matplotlib": ("https://matplotlib.net.cn", None),
}

现在您已经准备好创建文档了。查看 docs/source/ 文件夹以获取示例和如何在源文件中使用 autosummary 的说明。

在 Read the Docs 上发布

1. 在 docs/ 文件夹中创建一个文件 requirements.txt，内容如下：

numpy>=1.14.5
numpydoc

2. 在 Read the Docs 上登录或注册。
3. 点击 导入项目，选择你的 GitHub 仓库并激活高级选项。
4. 选择 Python 作为编程语言。
5. 将 docs/requirements.txt 路径添加到 需求文件 字段。
6. 勾选 使用系统包。

现在，你的文档应该已经准备好并托管在 Read the Docs 上。每次向你的仓库推送时，Read the Docs 都会自动构建文档。

如果你想添加一个 Read the Docs 徽章，请查看此项目 README.md 标题之后的第 一行。