python部署
python-deployment的Python项目详细描述
python部署
python部署工作流的示例
sphinx文档并阅读文档
设置狮身人面像
为了从docstrings生成文档，我们将使用 斯芬克斯。
- 在项目主目录中创建一个
docs目录。
mkdir docs
cd docs
- 使用sphinx提供的快速启动脚本。
sphinx-quickstart
并使用以下设置。
- 更改
source/conf.py。首先要做的是取消注释和更改 在文件顶部跟随行。
importosimportsyssys.path.insert(0,os.path.abspath('../../'))
还应该添加一些额外的扩展。autosummary扩展
从docstrings生成函数/方法/属性摘要列表，
napoleon使sphinx能够解析numpy和google风格的docstring。
最后，numpydoc扩展加载几个扩展以获得更好的
支持努比。
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'一个更好的主题。- 为了与阅读文档兼容：
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.python.org/3.6",None),"Python":("https://docs.python.org/",None),"NumPy":("http://docs.scipy.org/doc/numpy/",None),"SciPy":("http://docs.scipy.org/doc/scipy/reference",None),"matplotlib":("http://matplotlib.org",None),}
现在您可以创建文档了。看看docs/source/
文件夹为例以及如何在源文件中使用自动摘要。
在阅读文档时发布
- 在
docs/文件夹中创建一个文件requirements.txt，其内容类似于
numpy>=1.14.5numpydoc
- 登录或注册Read the Docs
- 单击
Import a Project，然后选择github上的存储库并 激活高级选项。 - 选择python作为编程语言。
- 将
docs/requirements.txt路径添加到Requirements file字段。 - 勾选
Use system packages。
现在，您的文档应该已经准备好并托管在 Read the Docs。你的每一次努力 repo，文档将通过读取文档自动生成。
如果您想添加readthedocs徽章，请查看第一个
此项目的README.md标题后的行。
欢迎加入QQ群-->： 979659372
