一、基础概念 利用sphinx+pandoc+github+readthedocs构建个人博客 Sphinx： 是一个基于ReStructuredText的文档生成工具，可以令人轻松的撰写出清晰且优美的文档...新版的Python文档就是由Sphinx生成的，并且它已成为Python项目首选的文档工具，同时它对C/C++项目也有很好的支持；并计划对其它开发语言添加特殊支持。...支持全平台操作，以命令行的方式进行转换。...二、流程 Sphinx + GitHub + ReadtheDocs 作为一个文档写作工具，利用pandoc文本转换， 用Sphinx生成文档，GitHub托管文档，再导入到 ReadtheDocs。...└── source #文件夹，文档源文件全部应全部放在source根目录下 ├── conf.py #Sphinx 的配置文件 ├── index.rst
安装 使用pip进行安装： pip install sphinx 设置源文件目录 包含.rst文件的根目录称之为源文件目录，目录中还包含sphinx的配置文件conf.py。...进入源文件目录，执行以下命令，会指引用户配置整个项目： sphinx-quickstart 定义文件结构 执行上述命令之后，sphinx会在源文件目录中自动生成conf.py文件以及index.rst。...index.rst称之为主文档，它被sphinx作为欢迎页面。 index.rst中包含了目录树指令toctree，sphinx使用它链接其他子文档。...实际上还有一个更简便的方法，sphinx-quickstart生成了一个make.bat文件，可以直接运行这个脚本： make html 上述命令会直接在源文件目录中生成文档。...例如，生成函数io.open()的文档，只需要在rst文件中添加如下语句： .. autofunction:: io.open 也可以直接生成整个类的文档： .. automodule:: io
Sphinx 和 Read the Docs 1.1 Sphinx Sphinx 是一个强大的文档生成器，具有许多用于编写技术文档的强大功能，包括： 维护一份源文档，生成网页，可打印的PDF，用于电子阅读器...它使用 Sphinx 生成 html 静态页面，通过 github 账户授权，在本地项目 push 到 github 仓库时，自动完成文档的生成和在线更新。...1.3 两者关系 可以简单认为 Sphinx 是一个独立的文档生成工具，可以支持不同的主题；而 Read the Docs 是一个免费的在线文档托管平台，它使用 Sphinx 作为文档生成工具，并提供自己的主题...给已有项目添加文档 以笔者真实托管在 GitHub 上的项目 imgkernel 为例。读者以自己实际项目对相关部分做修改，下文不再单独讲述。...Read the Docs” 会重新拉取分支 docs，构建生成 html 。构建需要一点时间，构建完成后，点击页面主页右边的绿色按钮 【阅读文档】，即可打开最终我们需要的在线文档的地址。
Sphinx是一个功能强大的文档生成器，具有许多用于编写技术文档的强大功能 gitee是一种版本管理系统，相比github，有着更快的访问速度 Read the Docs是一个在线文档托管服务， 你可以从各种版本控制系统中导入文档...这里先简单说明一下各个文件的作用： build：生成的文件的输出目录 source: 存放文档源文件 _static：静态文件目录，比如图片等 _templates：模板目录 conf.py：进行 Sphinx...的配置，如主题配置等 index.rst：文档项目起始文件，用于配置文档的显示结构 cmd.bat：这是自己加的脚本文件（里面的内容是‘cmd.exe’）,用于快捷的打开windows的命令行 make.bat...'] 注：支持markdown后，文档文件可以使用markdown格式，但文档的配置文件index.rst还要使用reST格式 3.2 修改文档显示结构 3.2.1 index文件分析 修改文档结构，...然后再进入各个子文件夹，添加markdown格式的文档和index.rst文件，这里以01设计模式文件夹为例： ?
sphinx文档生成与效果一览 首先使用sphinx-quickstart来生成一些配置文件： [dechin@dechin-manjaro circuit]$ sphinx-quickstart 欢迎使用...这些rst文件没有被自动生成的情况下，可能需要使用sphinx-apidoc去手动的添加： [dechin@dechin-manjaro hiqfermion]$ sphinx-apidoc -f src...在上述示例中，src/hiqfermion是源代码的存放地址，而docs/source是生成的rst文件存放的位置。一般我们需要先生成这些rst文件，再使用sphinx-build执行文档构建。...当然，首先我们需要逐一的去执行sphinx-apidoc来生成一些模块化的rst文件：sphinx-apidoc -f src/hiqfermion/module1 -o docs/source/以及sphinx-apidoc..... toctree:: :maxdepth: 4 module2 这里rst文档会自动搜寻同目录下的module1.rst和module2.rst文件，并自动化的生成文档。
这样做的默认方式依赖于docstrings ，它们以三引号格式定义。 虽然文档的价值是有据可查的，但似乎似乎很普遍，没有足够的文档代码。 让我们来看一个有关强大文档功能的场景。...有一个添加更多文档的选项，Pythonic模式是使用通常在docs /目录下添加的rst文件（ reStructuredText的缩写）。...：将ReStructured Text源与生成的文档打包在一起 为了告诉Sphinx什么以及如何生成，我们在docs / conf.py中配置一个辅助文件： extensions = [ 'sphinx.ext.autodoc...最后，为了准确地记录我们希望文档如何生成，请使用 Tox 来管理虚拟环境，以确保我们顺利地生成文档： [tox] # By default, .tox is the directory....我们可以从docstrings开始，添加.rst文件，然后添加Sphinx和Tox为用户美化结果。 对于好的文档，您欣赏什么？ 你还有其他喜欢的策略吗？ 请在评论中分享它们！
，tests 目录中是测试文件，再加一个 docs 目录放文档，README.rst, 其他的用于构建的 setup, setup.cfg 和 Makefile 文件。...其中 make docs 可以生成一个很漂亮的 Web 文档。 ...它不关注文档的生成，代码规范的检查，代码覆盖率都没有。它的项目配置更集中，全部在 pyproject.toml 文件中，toml 是什么呢？...NodeJS 的 package.json 文件，比如 poetry add, poetry install 命令的行 # 往 pyproject.toml 中添加对 boto3 的依赖并安装(add...所以可以想见，poetry 的项目要生成文档或覆盖率都必须用 poetry run ... 命令来支持 sphinx, coverage 或 flake8。
，tests 目录中是测试文件，再加一个 docs 目录放文档，README.rst, 其他的用于构建的 setup, setup.cfg 和 Makefile 文件。...其中 make docs 可以生成一个很漂亮的 Web 文档。...它不关注文档的生成，代码规范的检查，代码覆盖率都没有。它的项目配置更集中，全部在 pyproject.toml 文件中，toml 是什么呢？...NodeJS 的 package.json 文件，比如 poetry add, poetry install 命令的行 # 往 pyproject.toml 中添加对 boto3 的依赖并安装(add...所以可以想见，poetry 的项目要生成文档或覆盖率都必须用 poetry run ... 命令来支持 sphinx, coverage 或 flake8。
YAML 官方网站称 YAML 是"一种所有编程语言可用的友好的数据序列化标准"。YAML Ain't Markup Language，和GNU一样，YAML是一个递归着说"不"的名字。...同时，YAML也有XML的下列优点： YAML可以基于流来处理； YAML表达能力强，扩展性好。 总之，YAML试图用一种比XML更敏捷的方式，来完成XML所完成的任务。...YAML文件格式主要集中于空格缩进的概念，它用于指出数据的层次结构 而不是使用XML嵌套标记或JSON的大括号（{}）和方括号（[]），实际上，它是JSON的一个超集，因此，在使用的时候，你可能需要采用...•Deserializing 多个文档 解释如何从流中加载多个 YAML 文件。...• YAML转换为 JSON 和JSON 转换为YAML ，使用 Json.NET 的 JSON 转换 YAML 显示如何将 YAML 文件转换为 JSON。
亿 YAML是一种数据序列化格式。...你可能有自己的偏好，但是许多项目都使用YAML作为配置文件，所以这个项目是很受欢迎的。 ...PEP 文档使用固定的reStructuredText模板编写，并使用docutils转换为格式正确的文档。 Docutils 也是Sphinx的核心。Sphinx用于创建文档项目。...你可能已经读过 readthedocs.org 上的文档，那里的大多数文档都是由Sphinx和docutils创建的。 ...你还有一个名为chardetect的命令行工具，用法如下： chardetect somefile.txt somefile.txt: ascii with confidence 1.0 你还能通过编程方式使用这个库
，tests 目录中是测试文件，再加一个docs 目录放文档，README.rst, 其他的用于构建的 setup, setup.cfg 和 Makefile 文件。...其中 make docs 可以生成一个很漂亮的 Web 文档。...它不关注文档的生成，代码规范的检查，代码覆盖率都没有。它的项目配置更集中，全部在pyproject.toml 文件中，toml 是什么呢？...NodeJS 的 package.json 文件，比如 poetry add, poetry install 命令的行 # 往 pyproject.toml 中添加对 boto3 的依赖并安装(add...所以可以想见，poetry的项目要生成文档或覆盖率都必须用 poetry run ... 命令来支持 sphinx, coverage 或flake8。
你可能有自己的偏好，但是许多项目都使用YAML作为配置文件，所以这个项目是很受欢迎的。...12 Docutils 下载次数：5.08 亿 Docutils是一个模块化系统，用来将纯文本文档处理为很多有用的格式，例如 HTML、XML 和 LaTeX 等。...PEP 文档使用固定的reStructuredText模板编写，并使用docutils转换为格式正确的文档。 Docutils 也是Sphinx的核心。Sphinx用于创建文档项目。...你可能已经读过 readthedocs.org 上的文档，那里的大多数文档都是由Sphinx和docutils创建的。...后，你还有一个名为chardetect的命令行工具，用法如下： chardetect somefile.txtsomefile.txt: ascii with confidence 1.0 你还能通过编程方式使用这个库
你可以自行决定使用哪一个，但许多项目都使用 YAML 作为配置文件，因此该项目的流行度非常高。...12. docutils：5.08亿次下载 Docutils 是一个模块化系统，用于将纯文本文档转换成其他格式，如 HTML、XML 和 LaTeX等。...PEP 文档就是使用固定的 reStructuredText 模板，然后通过 docutils 转换成漂亮的文档。 Sphinx 的核心也使用了 docutils。Sphinx 用于创建文档项目。...如果说 docutils 是一台机器，那么 Sphinx 就是一个工厂。它的最初设计目的是构建P ython 本身的文档，但许多其他项目也利用 Sphinx 来创建文档。...JMESPath，读作“James path”，能更容易地在 Python 中使用 JSON。你可以用声明的方式定义怎样从 JSON 文档中读取数据。
存储引擎 列类型的选择 数据库设计三范式与逆范式 MySQL中的执行计划 数据库中索引的设计 MySQL中的其他功能 MySQL分表技术 Sphinx 读写分离 表单传值 表单传值的方式 PHP接收数据的三种方式...接口是采用中立的方式进行定义的，它应该独立于实现服务的硬件平台、操作系统和编程语言。这使得构建在各种各样的系统中的服务可以以一种统一和通用的方式进行交互。...YAML语言 YAML是“YAML不是一种记语言”的外语缩写 [1] （见前方参考资料原文内容）；但为了强调这种语言以数据做为中心，而不是以置标语言为重点，而用返璞词重新命名。...配置文件 YAML做配置文件也不错。写YAML要比写XML快得多(无需关注标签或引号)，并且比ini文档功能更强。 比如Ruby on Rails的配置就选用的YAML。...简单来说就是网络请求,然后响应以后使用JavaScript操作DOM 数据格式（如JSON、XML） JSON (轻量级的数据交换格式) JSON(JavaScript Object Notation
话说这段时间学习和实践了一下开源工具Sphinx，实现了文档代码化开发和同源发布。...在此之前，我一直以为部署一套这样的系统，非得采购专门工具不可；万万没想到，一个免费开源的工具，竟然可以做到如此交付水平；而且完全不需要开发者掌握专门的xml/dita格式，只需要配合通用性更高的rst/...Sphinx，是一个基于Python，开源免费的文档生成工具。...在这里，只有一点需要特别说明的是： 如果想对Sphinx直出的PDF进行一定人工干预，如添加企业LOGO，或者应用自定义样式之类，那么，从源码到PDF之间，可以被编辑的中间文件，并不是我们所熟悉的Word...对于之前从来没有使用过Latex的开发者而言，前期势必会引入一些学习成本；但由于Latex同样是一种代码化的开发方式，在完成基本的模板设计后，完全可以通过Jenkins部署自动化地实现干预。
这包含 Doxygen 从你的源文件生成的 HTML 文档。使用你喜欢的浏览器打开index.html将显示 Doxygen 欢迎页面。...当与 Python 项目一起使用时，它可以解析源文件中的所谓 docstrings，并自动为函数和类生成文档页面。...我们使用关键字参数调用此函数，以设置我们的 Sphinx 文档构建。...紧随code-reference的文件包含 Breathe 指令，以在 Sphinx 中包含 Doxygen 生成的文档： Messaging classes ================= Message...XML 输出，Breathe 插件将能够以与所选 Sphinx 文档样式一致的形式呈现这些输出。
你可以自行决定使用哪一个，但许多项目都使用 YAML 作为配置文件，因此该项目的流行度非常高。...12. docutils 5.08亿次下载 Docutils 是一个模块化系统，用于将纯文本文档转换成其他格式，如 HTML、XML 和 LaTeX等。...PEP 文档就是使用固定的 reStructuredText 模板，然后通过 docutils 转换成漂亮的文档。 Sphinx 的核心也使用了 docutils。Sphinx 用于创建文档项目。...如果说 docutils 是一台机器，那么 Sphinx 就是一个工厂。它的最初设计目的是构建P ython 本身的文档，但许多其他项目也利用 Sphinx 来创建文档。...JMESPath，读作“James path”，能更容易地在 Python 中使用 JSON。你可以用声明的方式定义怎样从 JSON 文档中读取数据。
存储配置是一项很灵活的任务，因为只要开发人员知道他们的代码是如何将数据存入文件的，他们就可以轻松编写代码来根据需要提取数据。...JSON JSON 文件在技术上来说是 YAML 的子集，因此其数据结构是相同的，尽管其语法完全不同： { "Example": { "Name": [ "Tux" ],...由于与 Web 开发密切相关，JSON 是 Web API 的常见输出格式。大多数编程语言都有解析 JSON 的库。...只要始终坚持相同的构建规则，并有一个良好的库来解析它，你就可以准确而轻松地提取数据。 有一些很好的开源 linter 可以帮你验证 XML 文件，并且大多数编程语言都提供用于解析 XML 的库。...你无法查看这些文件，至少无法以任何有意义的方式查看，并且无法在其宿主应用程序之外编辑它们。选用二进制格式的一些原因如下： 速度： 程序员可以使用自定义符号在二进制配置文件中的某些点注册特定的信息位。
部署简单，可以将生成的HTML静态页面部署到任何Web服务器上。 使用 MkDocs，您可以快速创建漂亮的文档页面，非常适合技术写作、软件文档、项目文档等。...Pelican 的主要特点包括： 静态网站生成：Pelican 将输入的文本文件转换为静态HTML文件，不需要使用数据库或其他后端技术。...Gridsome 是一个基于 Vue.js 的静态网站生成器，它使用 GraphQL 来获取数据并生成静态页面。...Middleman 是一个用 Ruby 编写的静态站点生成器，它可以将 Markdown、ERB 模板和 YAML 配置文件转换为静态 HTML 文件。...20.Sphinx star 数 5K+。 Sphinx 是一个用于创建技术文档的工具，可以将文本文件（如reStructuredText、Markdown等）转换成HTML、PDF、EPUB等格式。
领取专属 10元无门槛券
手把手带您无忧上云
云服务器
ICP备案
实时音视频
即时通信 IM
对象存储
