“Read the Docs” 提供自动构建，版本控制和在线托管，来简化软件文档的发布和管理。...它使用 Sphinx 生成 html 静态页面，通过 github 账户授权，在本地项目 push 到 github 仓库时，自动完成文档的生成和在线更新。...1.3 两者关系 可以简单认为 Sphinx 是一个独立的文档生成工具，可以支持不同的主题；而 Read the Docs 是一个免费的在线文档托管平台，它使用 Sphinx 作为文档生成工具，并提供自己的主题...给已有项目添加文档 以笔者真实托管在 GitHub 上的项目 imgkernel 为例。读者以自己实际项目对相关部分做修改，下文不再单独讲述。...Read the Docs” 会重新拉取分支 docs，构建生成 html 。构建需要一点时间，构建完成后，点击页面主页右边的绿色按钮 【阅读文档】，即可打开最终我们需要的在线文档的地址。
学会使用以下工具链来发布一个完整的库： Readthedocs：文档托管 Travis-CI：集成测试托管 Codecov：代码覆盖率统计托管 Sphinx：用reStructuredText写文档 MkDocs...另外，Hamaa其实已经完成了有一个月了，之所以拖了那么久才介绍是因为： 本来是打算用Sphinx+reStructuredText写API文档的，但是如果用Sphinx+reST写API文档，就意味着和...因为Hamaa的文档目前托管在ReadTheDocs上，而RTD只能要么使用Sphinx要么用MkDocs作为文档引擎。...考虑到文档编写、网站外貌（Sphinx很强大，但是他的autodoc功能导出的API文档在RTD主题下实在有点丑），最终选择了MkDocs+Markdown来编写文档。...但是这样又有了另外一个问题，MkDocs没有autodoc功能。如果手动编写，就意味着我要同时保持代码中的注释与API文档中的介绍一致。
丰富的扩展 结构化文档 自动索引 支持语法高亮 sphinx使用reStructuredtext作为它的标记语言。...index.rst称之为主文档，它被sphinx作为欢迎页面。 index.rst中包含了目录树指令toctree，sphinx使用它链接其他子文档。...toctree指令的初始值为空： .. toctree:: :maxdepth: 2 接下来就可以给它添加子文档的链接了，直接使用文档的名称即可，省略掉文件后缀，如果是多级目录，则使用/分隔开。...添加内容 在sphinx源文件中，使用reStructuredText标记语言进行文档编写，除此之外，sphinx还格外提供了一些指令。...为了使用autodoc，首先需要在配置文件的extensions选项中添加'sphinx.ext.autodoc'。然后我们就可以使用autodoc的指令了。
这些工具可以帮助您方便快捷地生成高质量的文档，并且轻松进行团队协作和社区分享。如果您正在寻找一个功能强大又易于上手的工具来构建静态网站或在线文档，请考虑尝试其中之一。...用户可以将其作为命令行工具在本地构建图书，并且也可通过 legacy.gitbook.com 在线发布并进行更新。...它支持使用 reStructuredText 编写的 Sphinx 文档，并可以从 Subversion、Bazaar、Git 和 Mercurial 仓库中拉取代码，然后为您构建和托管文档。...强大而灵活：通过结合 reStructuredText 和 Sphinx 的功能，在 Read the Docs 上编写丰富格式化和交互式内容变得更加容易。...快速生成：利用预渲染技术，在每次部署时将页面转换为静态 HTML 文件，从而实现快速加载和响应式体验。 多平台适配：无论是在电脑上还是移动设备上浏览您的文档网站都能得到良好呈现。
/tutorial.html 我们实现上述的目的,使用的是Sphinx: Sphinx 是一种文档工具，它可以令人轻松的撰写出清晰且优美的文档, 由 Georg Brandl 在BSD 许可证下开发....本站当然也是使用 Sphinx 生成的，它采用reStructuredText! Sphinx还在继续开发....您可以在根路径中使用目录“ _build”，也可以单独使用 根路径中的“源”和“构建”目录。 有一些提示,自己摁 项目名称将在生成的文档中的多个位置出现。...使用Makefile构建文档，如下所示： 使建设者 其中“构建器”是受支持的构建器之一，例如html，latex或linkcheck。...HTML页面位于build \ html中。 编译过后的目录是这样的 里面有三个html文件,都打开看看 以上是打开的三个网页文档 那我写完就想自动预览文档,咋办?
因此，您可以向函数添加文档字符串。 我最喜欢的文档字符串样式之一是“ Google”样式 。 标记很轻巧，当它位于源代码中时很好。...但是函数的文档只是成功的一半。 散文文档对于上下文化代码用法很重要。 在这种情况下，背景是令人讨厌的技术采访。...这三个Sphinx扩展特别有用： sphinx.ext.autodoc ：从模块内部获取文档 sphinx.ext.napoleon ：支持Google样式的文档字符串 sphinx.ext.viewcode...：将ReStructured Text源与生成的文档打包在一起 为了告诉Sphinx什么以及如何生成，我们在docs / conf.py中配置一个辅助文件： extensions = [ 'sphinx.ext.autodoc...basepython = python3.7 现在，无论何时运行Tox，它都会为您的Python代码生成漂亮的文档。 Python文档非常出色 作为Python开发人员，我们可以使用的工具链很棒。
创建仓库 首先，我们需要在GitHub上创建仓库并将该仓库克隆到本地，当然你也可以直接在原有仓库上进行操作。 ?...注册账号并连接到GitHub 接着我们需要在ReadtheDocs官网注册一个账号，https://readthedocs.org/ ，注册成功后在设置中选择已连接的服务，并点击Connect to GitHub...项目导入 在个人面板点击Import a Project，选择需要创建文档的项目，若是未找到目标项目，可以点击右上角的刷新并等待。 ?...构建文档 导入项目之后，我们点击Build version即可成功创建文档 ? 等待片刻后即可构建完成，Webhook自动添加之后只要更新GitHub仓库，项目文档就会自动重新构建。 ?...sphinx-quickstart 可以通过一直回车来使用默认配置，在这里我主要选择了source和build目录分离，并且使用中文为项目语言。
3 修改测试程序 Sphinx默认只支持reST格式的文件，reST的使用语法介绍见：https://zh-sphinx-doc.readthedocs.io/en/latest/rest.html ?...4 项目托管到gitee 以上的操作，只能在本地的浏览器查看文档，若想让所有人都能看到，需要部署到ReadtheDocs展示，在部署之前，要把代码托管到代码托管平台，这里选用gitee，国内使用速度快。...先到gitee上（https://gitee.com/）建立一个公开的仓库，然后将本地项目文件上传即可，如我是建立一个名为SphinxDemo的仓库。...在上传文件之前，先自己写一个.gitignore文件，用于指示编辑的文件（build目录）不上传到代码仓库，.gitignore文件内容如下： build/ 然后使用就是在本地的项目文件夹内使用基本的...Build成功后，点击阅读文档即可查看效果 https://sphinxdemotest.readthedocs.io/en/latest/ ?
一、基础概念 利用sphinx+pandoc+github+readthedocs构建个人博客 Sphinx： 是一个基于ReStructuredText的文档生成工具，可以令人轻松的撰写出清晰且优美的文档...新版的Python文档就是由Sphinx生成的，并且它已成为Python项目首选的文档工具，同时它对C/C++项目也有很好的支持；并计划对其它开发语言添加特殊支持。...Read the Docs是一个在线文档托管服务，可以从各种版本控制系统中导入文档。支持webhooks，当你提交代码时，文档将被自动构建。...二、流程 Sphinx + GitHub + ReadtheDocs 作为一个文档写作工具，利用pandoc文本转换， 用Sphinx生成文档，GitHub托管文档，再导入到 ReadtheDocs。...，生成的html静态文件都存放在这里 ├── make.bat ├── Makefile #编译文件用 make 命令时，可以使用这些指令来构建文档输出 └── source
如果不需要使用read_the_docs格式也可以不安装后者，只是后者在python的开源项目中还是最常用的一种文档格式，并且可以配合read_the_docs网站进行API文档的托管，因此推荐使用。...同时，为了展示API文档的制作过程，这里我们在类与函数内都写了一部分的示例注释代码，在下一个章节介绍一下文档的效果。...补充说明（2021.03.27） 如果在使用sphinx的过程中，发现代码中的注释文件并未被成功生成。...在上述示例中，src/hiqfermion是源代码的存放地址，而docs/source是生成的rst文件存放的位置。一般我们需要先生成这些rst文件，再使用sphinx-build执行文档构建。...总结概要 在这篇文章中，我们主要通过一个量子线路打印的python项目介绍，也顺带通过sphinx将python项目的注释文档自动化的生成API接口文档，完成了一个项目开发及文档输出流程的简要分析，在实战中掌握更多的工具使用方法
文档 文档的话，并没有严格要求必须使用什么样的工具进行构建，也没有很严格的格式要求。...还有很关键的一点是Sphinx有autodoc和automodule的扩展， 可以从代码中提取出文档，与代码直接进行关联。提供一个例子可以方便的在文档和源码中进行跳转。...Read the Docs 持续文档集成 说完写文档就不得不提到Read the Dosc了,这是一个第三方的文档托管平台,使用Django开发，它可以很轻松的和Github上的项目进行集成，在每次代码提交的时候会自动进行文档构建...，你就上传成功了，去PyPI上看看有没有上传成功的包，并且试着用pip进行安装吧！...项目托管在Github上 开源到Github上后，就是继续维护和开发，这点就不多说了。 开发相关 建议使用virtualenv之类的工具构建纯净的环境，重复的动作交给Make之类的工具。
这一切是一个组织在维护： https://www.pypa.io/en/latest/ Python Packaging Authority (PyPA) 是一个工作组，负责维护 Python 打包中使用的一组核心软件项目...任何动态的或在安装时确定的项目，以及扩展模块或 setuptools 的扩展，都需要进入setup.py. setup.cfg应首选静态元数据 ( )。...大概就是这样的一个情况 https://pypa-build.readthedocs.io/en/stable/index.html 构建工具的地址 执行后报错，我查了一下，应该是在虚拟环境构建 https...你就当我构建成功了。...一般这样的目录就是一个不错的包 一个好的包一定少不了一个文档，那下面就安装一下 py -m pip install -U sphinx 安装好以后 sphinx-quickstart 执行这个
实现的大体的思路如下： Markdown：书写文档 Pandoc：格式转化 Sphinx：生成网页 GitHub：托管项目 ReadtheDocs：发布网页 接下来，就来看看到底是如何实现的？...02 安装Sphinx ---- 安装之前，请确认下Python版本。我这里使用的是Python 2.7.14，其他版本请自行尝试（Py3有点不一样，不想踩坑的，请跟我一样使用 Py2）。...这里我将工程文件，托管在GitHub上，然后由Read the Docs发布。 在托管之前呢，我们需要准备工作。...然后把mkdocs这个目录下的所有文件都提交上去。步骤很简单，这里就不细讲。 06 发布上线 ---- 托管完成后，我们要发布它，让别人可以访问。...这里要提醒一下的是，Sphinx的文档格式，默认是 rst 格式，如果你习惯了使用Markdown来写文章，可以使用 Pandoc 这个神器转换一下。 这里给出转换命令。
背景知识 当我开始使用 Python 并创建我的第一个包时，我很困惑。创建和管理包似乎比我预想的要困难得多。此外，存在多种工具，但我不确定该使用哪一种。我相信你们大多数人过去都遇到过同样的问题。...用于此目的的工具收集在环境管理类别中。大多数工具使用虚拟环境，但有些工具使用另一个称为 “本地包”（Local Packages） 的概念，我们稍后会讨论。 您可能希望与其他开发人员共享您的代码。...(>=7.0,sphinx-argparse-cli (>=1.5)", "sphinx-autodoc-typehints (>=1.10)", "sphinx-issues (>...Flit Flit（https://flit.pypa.io/en/stable/）尝试创建一种简单的方法将 Python 包和模块放在 PyPI 上。...但是，由于定期发布新版本，因此将来可能会添加此内容。 该工具是否管理依赖关系？✅ 它是否解析/锁定依赖关系？✅ 是否有干净的构建/发布流程？✅ 它允许使用插件吗？
当我开始使用 Python 并创建我的第一个包时，我很困惑。创建和管理包似乎比我预想的要困难得多。此外，存在多种工具，但我不确定该使用哪一种。我相信你们大多数人过去都遇到过同样的问题。...用于此目的的工具收集在环境管理类别中。大多数工具使用虚拟环境，但有些工具使用另一个称为 “本地包”（Local Packages） 的概念，我们稍后会讨论。 您可能希望与其他开发人员共享您的代码。...(>=7.0,sphinx-argparse-cli (>=1.5)", "sphinx-autodoc-typehints (>=1.10)", "sphinx-issues (>...Flit Flit（flit.pypa.io/en/stable/）尝试创建一种简单的方法将 Python 包和模块放在 PyPI 上。...但是，由于定期发布新版本，因此将来可能会添加此内容。 该工具是否管理依赖关系？✅ 它是否解析/锁定依赖关系？✅ 是否有干净的构建/发布流程？✅ 它允许使用插件吗？
，我们根据它的语法规则写出一些工作流，在符合一定条件时，这些工作流会被触发，自动执行。...比如这里 runs-on 我就定义了在 ubuntu-latest 版本上运行，另外定义了一些并行策略和参数，比如这里就定义了 Python 的三个版本参数，在 3.5、3.6、3.7 版本上运行。...可以看到这里初始化了三个版本的 Python 环境，同时都运行了其中的测试流程。如果测试成功，会打绿色的勾，如果失败，会提示红色的叉，并有邮件提示。 这样以来，一些自动化的测试就完成了！！！ ?...写项目免不了的要写文档，这里文档我是用 Sphinx 来写的，可以借助于 ReadTheDocs 自动构建并分发到 readthedocs.io 上面，类似这样子： ?...•每个历史版本，每次发布版本的版本号，都标记一个 tag。 最后我们自动构建的镜像都自动 Push 到 Docker Hub 上面，这样大家都可以使用了。
在本章中，我们将涵盖以下食谱： 使用 Doxygen 构建文档 使用 Sphinx 构建文档 结合 Doxygen 和 Sphinx 引言 文档在所有软件项目中都是必不可少的：对于用户...如果你导航到类列表，你可以例如浏览Message类的文档： 工作原理 CMake 默认不支持文档构建。但是，我们可以使用add_custom_target来执行任意操作，这是我们在本食谱中利用的机制。...需要注意的是，我们需要确保系统上存在构建文档所需的工具（在本例中为 Doxygen 和 Perl）。...与在线 Read the Docs 服务（readthedocs.org）结合使用，它提供了一种快速开始编写和部署文档的绝佳方式。本食谱将向您展示如何使用 CMake 基于 Sphinx 构建文档。...我们更愿意使用 Sphinx 来实现这一点，因为生成的 HTML 也可以在移动设备上工作，而且我们可以将文档部署到 Read the Docs（readthedocs.org）。
由于 readme 文件应该相当综合，因此通常会有一个更详细的文档。你可以用 sphinx 来完成，然后在 readthedocs 上管理文档。与文档相关的文件通常放在 docs/文件夹中。...image 包含标签和说明的项目库示例 第 6 步：创建持续集成 此时，你的项目离发布就绪不远了。但是，在每次提交之后，必须更新文档、运行测试以及检查样式和覆盖率似乎有点难以应付。...幸运的是，持续集成（CI）可以帮助你完成。你可以在每次提交之后使用 GitHub 的 webhook 来自动执行所有的这些操作。...首先要做的是在 GitHub 上创建你的第一个 release——这是为了在给定的时间点跟踪项目的状态，每次版本更改时都需要创建新的 release。...虽然大部分工作都完成了，但是你仍然需要维护你的项目，你需要进行一些更新：这大体上意味着每次进行重大更改时都要更改版本，创建新的 release，并再次执行第 7 步。
由于 readme 文件应该相当综合，因此通常会有一个更详细的文档。你可以用 sphinx 来完成，然后在 readthedocs 上管理文档。与文档相关的文件通常放在 docs/文件夹中。...包含标签和说明的项目库示例 第 6 步：创建持续集成 此时，你的项目离发布就绪不远了。但是，在每次提交之后，必须更新文档、运行测试以及检查样式和覆盖率似乎有点难以应付。...幸运的是，持续集成（CI）可以帮助你完成。你可以在每次提交之后使用 GitHub 的 webhook 来自动执行所有的这些操作。...首先要做的是在 GitHub 上创建你的第一个 release——这是为了在给定的时间点跟踪项目的状态，每次版本更改时都需要创建新的 release。...虽然大部分工作都完成了，但是你仍然需要维护你的项目，你需要进行一些更新：这大体上意味着每次进行重大更改时都要更改版本，创建新的 release，并再次执行第 7 步。 ?
由于 readme 文件应该相当综合，因此通常会有一个更详细的文档。你可以用 sphinx 来完成，然后在 readthedocs 上管理文档。与文档相关的文件通常放在 docs/文件夹中。...包含标签和说明的项目库示例 第 6 步：创建持续集成 此时，你的项目离发布就绪不远了。但是，在每次提交之后，必须更新文档、运行测试以及检查样式和覆盖率似乎有点难以应付。...幸运的是，持续集成（CI）可以帮助你完成。你可以在每次提交之后使用 GitHub 的 webhook 来自动执行所有的这些操作。...首先要做的是在 GitHub 上创建你的第一个 release——这是为了在给定的时间点跟踪项目的状态，每次版本更改时都需要创建新的 release。...虽然大部分工作都完成了，但是你仍然需要维护你的项目，你需要进行一些更新：这大体上意味着每次进行重大更改时都要更改版本，创建新的 release，并再次执行第 7 步 原文链接： https://medium.freecodecamp.org
领取专属 10元无门槛券
手把手带您无忧上云
云服务器
ICP备案
腾讯会议
云直播
对象存储
