Deploy docs from Travis to Github pages.
doctr的Python项目详细描述
doctr
=
一个自动将文档从travis ci部署到github页面的工具。
doctr通过管理生成、加密、管理ssh deploy
密钥以及将文件同步到"gh-p"等复杂任务，帮助将内容从travis ci部署到github页面。年龄分支。doctr最初是为文档而设计的，但它可以用于将任何类型的网站部署到可以在travis ci上构建的github页面。例如，您可以使用doctr
部署一个"blog
<；http://www.asmurer.com/blog/posts/自动将此博客部署到带有travis ci/>；`
的github页面或使用"静态站点生成器"的网站上，https://www.staticgen.com/>；``.
` github
<；https://github.com/drdoctr/doctr>；` `.
安装
----
代码：
pip install doctr
或conda
…代码：
conda install-c conda forge doctr
**请注意，doctr需要python 3.5或更新版本。**
usage
----
>运行doctr configure
~~~~~~~~~~~~~~~~~~~~~~~~~~~
首先使用doctr生成必要的密钥文件，以便travis可以将
推送到您的gh页面（o其他）分支。
运行
…代码：
doctr configure
并输入数据。您需要您的github用户名和密码，以及要为其生成文档的
repo组织/名称。
**注意**：应该已经用travis设置了该repo。我们建议为"gh pages"分支和其他分支启用
`分支保护<；https://help.github.com/articles/about protected branchs/>；``u
，因为docr使用的部署键
可以推送到回购中的任何分支。
编辑travis文件
~~~~~~~~~~~~~~~~~~~~~~~
doctr将输出一堆文本以及下一步的说明。你需要用这段文字编辑你的"travis.yml"。它包含让travis与github存储库通信的安全密钥，以及运行的代码（在``script:``````）以便构建文档和部署doctr。
代码：：yaml
doctr需要python>；=3.5
language:python
python:
-3.6
e脚本在travis上构建文档，然后部署
脚本：
-set-e
-pip install doctr
-cd docs
-make html
-cd..
-doctr deploy。--build docs path/to/build/html/
请参阅"travis配置文件"
<；https://github.com/drdoctr/doctr/blob/master/.travis.yml>；`，例如由doctr本身使用。
您可以通过在调用
to``deploy``中为其指定不同的路径，将其部署到不同的文件夹。例如，``doctr deploy docs/``.
警告：
请确保在"脚本"中添加"set-e"，以防止"doctr"在文档生成失败时运行。如果
使用"在成功后"，则不会导致
<；https://docs.travis ci.com/user/customization the build；中断生成>；`\br/>生成失败。
我将创建一个包含密钥的新文件。将其提交为
，并将更改提交到`.travis.yml``。一旦你推到github，travis应该会自动构建你的文档并部署它。
notes
----
**doctr需要python 3.5或更高版本。**be sur在构建矩阵的
python 3.5或更新版本中运行它。它应该与您的文档构建在构建矩阵中的
构建相同，因为它可以重用这些内容。
**doctr不需要sphinx。**它可以将任何内容部署到
github页面。但是，如果您确实使用sphinx，docr将自动找到您的sphinx
文档（否则使用"doctr deploy"。--构建文档<；docs path>；``）.
faq
--
-**为什么构建此文档？**
从travis部署到github页面并不困难，但这已经足够困难了，我们希望编写一次代码来完成它。我们发现travis文档上传脚本是一种很难复制的方式，特别是设置密钥的do once步骤。我不赞成。它也是完全独立的（它不依赖于travis的ruby gem）。"`doctr
deploy``命令处理密钥解密（用于部署密钥）和隐藏命令输出中的令牌（用于个人访问令牌）。
通用电气公司。github personal
访问令牌为给定用户授予对所有公共github存储库的读/写访问权。一种更安全的方法是使用github部署密钥，它只授予对单个存储库的读/写访问权。默认情况下，doctr会创建一个github deploy
密钥（尽管如果您知道自己在做什么，则可以选择使用令牌）。
-**为什么不阅读文档？**
阅读文档很好，但它有一些限制：
-您在阅读文档时可以安装的内容有限。travis允许您
运行任意代码，这可能是构建文档所必需的。
-阅读部署到read the docs.io的文档。doctr部署到github页面上。
这通常更方便，因为您的文档可以很容易地与github页面上项目的其他网站资料放在一起。
一般来说，您应该已经在travis上构建了您的文档（以测试它们的构建），所以看起来很自然地从那里部署它们。
-**为什么doctr需要python 3.5或更高版本？**
python有几个语言特性是我们想利用的
，这些特性在早期版本的python中是不可用的，例如"仅关键字
参数"lt；https://www.python.org/dev/peps/pep-3102/>；` `，
"子流程.运行
<；https://docs.python.org/3/library/subprocess.html subprocess.run>；`，和
`递归globs<；https://docs.python.org/3/library/glob.html>；`。这些
功能有助于保持doctr代码的干净和可维护性。
如果您无法在python 3中构建文档，则需要在travis中安装python3.6才能运行doctr。
-**这安全吗？**
doctr创建一个加密的ssh部署密钥，它允许任何travis构建在
您的repo上推送到部署repo。使用来自python密码模块的
<；https://cryptography.io/en/latest/fernet/>；`` fernet encryption对部署密钥进行加密。然后，使用"travis
公钥<；https://docs.travis ci.com/user/encryption keys/>；``将fernet密钥加密到travis的安全环境变量中。
travis不会使安全环境变量可用于请求生成。此外，默认情况下，doctr本身不会从
``master``以外的任何分支进行推送，尽管：ref:`可以更改<；any branch>；`.
>默认情况下，doctr使用部署密钥，但也可以使用github
个人访问令牌，使用``--token``标志。但是，作为Github个人帐户，不建议这样做ess令牌授予对整个
帐户的访问权限，而部署密钥只授予对单个
存储库的推送访问权限。
转到github中存储库的
：samp:`https://github.com/{org}/{repo}/settings/keys`，撤消docr创建的部署密钥。个人访问
令牌可以在"https://github.com/settings/tokens
<；https://github.com/settings/tokens>；"撤销。如果撤消密钥，则需要
重新运行"doctr configure"，以生成新密钥以继续使用doctr。
-**doctr可以执行x吗？**
请参阅：ref:`recipes`页面，了解许多常见的doctr用例配方。
doctr几乎支持任何涉及自动从travis ci推送到
github的功能。
-**我会使用它，但它缺少我想要的功能。**
doctr仍然非常不可用。电子战。我们欢迎所有"功能请求
<；https://github.com/drdoctr/doctr/issues>；``和"拉取请求
<；https://github.com/drdoctr/doctr/pulls>；``请求"。
-**为什么称为doctr？**
，因为它从**tr**\avis部署**doc**\umentation。这也让你感觉良好。
>使用doctr的项目
---------
-`sympy<；http://www.sympy.org/en/index.html>；` `
-`conda<；http://conda.pydata.org/docs/>；` ` `
-`doctr<；http://conda.pydata.org/docs/docs/>；` ` `
-`pygbe&pygbe<；http://www.sympy.http://www.sympy.com/www.sympy.org/sympy.org/www.org lt；https:///barbagroup.github.io/pygbe/docs/>；` `
>
-`xon sh<；http://xon.sh>；` `<
>
-`regro-cf自恋自恋自恋bot<；https://github.com/regro/cf scripts>；` ` ` `
>
-`xpd stack<；http://xpdacq.github.io/>；` ` ` ` ` ` ` ` ` ` ` ` ` ` ` ` ` ` ` ` ` ` ` ` ` ` ` `/>；`
唱博士歌？请将您的项目添加到列表中！< BR>
=
一个自动将文档从travis ci部署到github页面的工具。
doctr通过管理生成、加密、管理ssh deploy
密钥以及将文件同步到"gh-p"等复杂任务，帮助将内容从travis ci部署到github页面。年龄分支。doctr最初是为文档而设计的，但它可以用于将任何类型的网站部署到可以在travis ci上构建的github页面。例如，您可以使用doctr
部署一个"blog
<；http://www.asmurer.com/blog/posts/自动将此博客部署到带有travis ci/>；`
的github页面或使用"静态站点生成器"的网站上，https://www.staticgen.com/>；``.
` github
<；https://github.com/drdoctr/doctr>；` `.
安装
----
代码：
pip install doctr
或conda
…代码：
conda install-c conda forge doctr
**请注意，doctr需要python 3.5或更新版本。**
usage
----
>运行doctr configure
~~~~~~~~~~~~~~~~~~~~~~~~~~~
首先使用doctr生成必要的密钥文件，以便travis可以将
推送到您的gh页面（o其他）分支。
运行
…代码：
doctr configure
并输入数据。您需要您的github用户名和密码，以及要为其生成文档的
repo组织/名称。
**注意**：应该已经用travis设置了该repo。我们建议为"gh pages"分支和其他分支启用
`分支保护<；https://help.github.com/articles/about protected branchs/>；``u
，因为docr使用的部署键
可以推送到回购中的任何分支。
编辑travis文件
~~~~~~~~~~~~~~~~~~~~~~~
doctr将输出一堆文本以及下一步的说明。你需要用这段文字编辑你的"travis.yml"。它包含让travis与github存储库通信的安全密钥，以及运行的代码（在``script:``````）以便构建文档和部署doctr。
代码：：yaml
doctr需要python>；=3.5
language:python
python:
-3.6
e脚本在travis上构建文档，然后部署
脚本：
-set-e
-pip install doctr
-cd docs
-make html
-cd..
-doctr deploy。--build docs path/to/build/html/
请参阅"travis配置文件"
<；https://github.com/drdoctr/doctr/blob/master/.travis.yml>；`，例如由doctr本身使用。
您可以通过在调用
to``deploy``中为其指定不同的路径，将其部署到不同的文件夹。例如，``doctr deploy docs/``.
警告：
请确保在"脚本"中添加"set-e"，以防止"doctr"在文档生成失败时运行。如果
使用"在成功后"，则不会导致
<；https://docs.travis ci.com/user/customization the build；中断生成>；`\br/>生成失败。
我将创建一个包含密钥的新文件。将其提交为
，并将更改提交到`.travis.yml``。一旦你推到github，travis应该会自动构建你的文档并部署它。
notes
----
**doctr需要python 3.5或更高版本。**be sur在构建矩阵的
python 3.5或更新版本中运行它。它应该与您的文档构建在构建矩阵中的
构建相同，因为它可以重用这些内容。
**doctr不需要sphinx。**它可以将任何内容部署到
github页面。但是，如果您确实使用sphinx，docr将自动找到您的sphinx
文档（否则使用"doctr deploy"。--构建文档<；docs path>；``）.
faq
--
-**为什么构建此文档？**
从travis部署到github页面并不困难，但这已经足够困难了，我们希望编写一次代码来完成它。我们发现travis文档上传脚本是一种很难复制的方式，特别是设置密钥的do once步骤。我不赞成。它也是完全独立的（它不依赖于travis的ruby gem）。"`doctr
deploy``命令处理密钥解密（用于部署密钥）和隐藏命令输出中的令牌（用于个人访问令牌）。
通用电气公司。github personal
访问令牌为给定用户授予对所有公共github存储库的读/写访问权。一种更安全的方法是使用github部署密钥，它只授予对单个存储库的读/写访问权。默认情况下，doctr会创建一个github deploy
密钥（尽管如果您知道自己在做什么，则可以选择使用令牌）。
-**为什么不阅读文档？**
阅读文档很好，但它有一些限制：
-您在阅读文档时可以安装的内容有限。travis允许您
运行任意代码，这可能是构建文档所必需的。
-阅读部署到read the docs.io的文档。doctr部署到github页面上。
这通常更方便，因为您的文档可以很容易地与github页面上项目的其他网站资料放在一起。
一般来说，您应该已经在travis上构建了您的文档（以测试它们的构建），所以看起来很自然地从那里部署它们。
-**为什么doctr需要python 3.5或更高版本？**
python有几个语言特性是我们想利用的
，这些特性在早期版本的python中是不可用的，例如"仅关键字
参数"lt；https://www.python.org/dev/peps/pep-3102/>；` `，
"子流程.运行
<；https://docs.python.org/3/library/subprocess.html subprocess.run>；`，和
`递归globs<；https://docs.python.org/3/library/glob.html>；`。这些
功能有助于保持doctr代码的干净和可维护性。
如果您无法在python 3中构建文档，则需要在travis中安装python3.6才能运行doctr。
-**这安全吗？**
doctr创建一个加密的ssh部署密钥，它允许任何travis构建在
您的repo上推送到部署repo。使用来自python密码模块的
<；https://cryptography.io/en/latest/fernet/>；`` fernet encryption对部署密钥进行加密。然后，使用"travis
公钥<；https://docs.travis ci.com/user/encryption keys/>；``将fernet密钥加密到travis的安全环境变量中。
travis不会使安全环境变量可用于请求生成。此外，默认情况下，doctr本身不会从
``master``以外的任何分支进行推送，尽管：ref:`可以更改<；any branch>；`.
>默认情况下，doctr使用部署密钥，但也可以使用github
个人访问令牌，使用``--token``标志。但是，作为Github个人帐户，不建议这样做ess令牌授予对整个
帐户的访问权限，而部署密钥只授予对单个
存储库的推送访问权限。
转到github中存储库的
：samp:`https://github.com/{org}/{repo}/settings/keys`，撤消docr创建的部署密钥。个人访问
令牌可以在"https://github.com/settings/tokens
<；https://github.com/settings/tokens>；"撤销。如果撤消密钥，则需要
重新运行"doctr configure"，以生成新密钥以继续使用doctr。
-**doctr可以执行x吗？**
请参阅：ref:`recipes`页面，了解许多常见的doctr用例配方。
doctr几乎支持任何涉及自动从travis ci推送到
github的功能。
-**我会使用它，但它缺少我想要的功能。**
doctr仍然非常不可用。电子战。我们欢迎所有"功能请求
<；https://github.com/drdoctr/doctr/issues>；``和"拉取请求
<；https://github.com/drdoctr/doctr/pulls>；``请求"。
-**为什么称为doctr？**
，因为它从**tr**\avis部署**doc**\umentation。这也让你感觉良好。
>使用doctr的项目
---------
-`sympy<；http://www.sympy.org/en/index.html>；` `
-`conda<；http://conda.pydata.org/docs/>；` ` `
-`doctr<；http://conda.pydata.org/docs/docs/>；` ` `
-`pygbe&pygbe<；http://www.sympy.http://www.sympy.com/www.sympy.org/sympy.org/www.org lt；https:///barbagroup.github.io/pygbe/docs/>；` `
>
-`xon sh<；http://xon.sh>；` `<
>
-`regro-cf自恋自恋自恋bot<；https://github.com/regro/cf scripts>；` ` ` `
>
-`xpd stack<；http://xpdacq.github.io/>；` ` ` ` ` ` ` ` ` ` ` ` ` ` ` ` ` ` ` ` ` ` ` ` ` ` ` `/>；`
唱博士歌？请将您的项目添加到列表中！< BR>
欢迎加入QQ群-->： 979659372
