# Eugene forest's notebook ![GitHub issues](https://img.shields.io/github/issues/Eugene-Forest/NoteBook) ![GitHub closed issues](https://img.shields.io/github/issues-closed-raw/Eugene-Forest/NoteBook) [![GitHub last commit][github-badge]][github-link] [![Documentation Status][rtd-badge]][rtd-link] > **文档构建时间: {sub-ref}`today`** 这是笔者在学习过程中的一些笔记，可能包括软件的安装配置、技术的知识点、技术的使用技巧、软件的使用方法、以及学习过程当中的感悟、学习过程中出现的疑问以及疑问的解决。 本项目是通过 [Sphinx](https://www.sphinx-doc.org/zh_CN/master/index.html) 工具来实现的，使用了并涉及了 [reStructureText](https://www.sphinx-doc.org/zh_CN/master/usage/restructuredtext/index.html) 、 Markdown 、[MyST](https://myst-parser.readthedocs.io/en/latest/index.html) 标记语言以及其他基于这些语言的 Sphinx 插件扩展语法来编写文档，并托管与 [Read the Docs](https://readthedocs.org/) 平台运行。 项目分为三个分支。其中， **main** 分支是主分支，是 **k-doc** 和 **builder-doc** 分支的结合；而 **k-doc** 分支记载笔者的工作、学习的笔记和感悟；而 **builder-doc** 分支主要是介绍本项目的相关编写语法和工具，涉及 [MyST](https://myst-parser.readthedocs.io/en/latest/index.html) 、 [reStructureText](https://www.sphinx-doc.org/zh_CN/master/usage/restructuredtext/index.html) 和 [Sphinx](https://www.sphinx-doc.org/zh_CN/master/index.html) 文档工具和插件等。 ```{toctree} :caption: "knowledge 笔记记录" :hidden: :maxdepth: 1 Git 笔记记录 Java 笔记记录 Spring 笔记记录 SQL 笔记记录 Redis 笔记记录 Node 笔记记录 TypeScript 笔记记录 JavaScript 笔记记录 Vue2 笔记记录 Vue3 笔记记录 Element-UI 笔记记录 Python 笔记记录 Linux 和 Shell 笔记记录 Batch&Shell 笔记记录 效率工具：代码模板 ``` ```{toctree} :caption: "软件或工具包安装以及配置记录" :hidden: :maxdepth: 1 bladex 快速开发平台的使用 vscode 一些常用软件的快捷键 Navicat Premium 实用技巧 ``` ```{toctree} :caption: "构建文档的工具和标记语言" :hidden: :maxdepth: 1 Sphinx 工具和 reST 标记语言 Markdown 标记语言 MyST Sphinx 扩展工具 MyST-NB ``` ## 关于 `MyST` _MyST_ 建立在 _markdown-it_ 定义的标记之上，所以 _MyST_ 遵守 [CommonMark 规范](https://spec.commonmark.org/)。为此，它使用了 [markdown-it-py 解析器](https://github.com/executablebooks/markdown-it-py)，这是一个结构良好的 _Python_ 降价解析器，符合 _CommonMark_ 规范且可扩展。 _MyST_ 向 _CommonMark_ 添加了几个新的语法选项，以便与 _Sphinx_ 一起使用，而 _Sphinx_ 是 _Python_ 生态系统中广泛使用的文档生成引擎。 ## 为什么使用 `MyST` 虽然 _Markdown_ 无处不在，但它的功能还不足以编写现代的、功能齐全的文档。为此需要一些 _Markdown_ 支持功能，但没有围绕这些功能的各种语法选择的社区标准。 _Sphinx_ 是一个用 _Python_ 编写的文档生成框架。它大量使用了 _reStructuredText_ 语法，这是另一种用于编写文档的标记语言。特别是， _Sphinx_ 定义了两个非常有用的扩展点： 内联角色和块级指令。 _MyST_ 试图将 _Markdown_ 的简单性和可读性与 _reStructuredText_ 和 _Sphinx_ 平台的强大功能和灵活性相结合。它从 _CommonMark_ 降价规范开始，并有选择地添加了一些额外的语法片段以利用 _reStructuredText_ 最强大的部分。 ## `MyST` 、 `reStructuredText` 和 `Sphinx` 之间的关系 _MyST_ 提供了与 _reStructuredText_ 语法等效的 _Markdown_ ，这意味着您可以在 _MyST_ 中做任何可以用 _reStructuredText_ 做的事情。 _Sphinx_ 文档引擎支持多种不同的输入类型。默认情况下， _Sphinx_ 读取 _reStructuredText_ ( `.rst`) 文件。 _Sphinx_ 使用解析器将输入文件解析为它自己的内部文档模型（由核心 _Python_ 项目 `docutils` 提供）。 开发人员可以扩展 _Sphinx_ 以支持其他类型的输入文件。任何内容文件都可以读入 _Sphinx_ 文档结构，前提是有人为该文件编写了 解析器。一旦内容文件被解析为 _Sphinx_ ，它的行为与任何其他内容文件几乎相同，无论它是用什么语言编写的。 _MyST_ 解析器是用于 _MyST_ 降价语言的 _Sphinx_ 解析器。当您使用它时， _Sphinx_ 将知道如何解析包含 _MyST_ 的内容文件（默认情况下， _Sphinx_ 会假设任何以 结尾的文件.md 都是用 _MyST_ 编写的）。一旦文档被解析为 _Sphinx_ ，无论它是用 `rST` 还是 _MyST_ 编写的，它的行为都是一样的。 ``` myst markdown (.md) ------> myst parser ---+ | +-->Sphinx document (docutils) | reStructuredText (.rst) --> rst parser ----+ ``` ## 项目对应的电子书在线查看 本项目已经挂载在 [Read the Docs](https://readthedocs.org/) 中，点击下方链接即可在线查看项目的实现即电子书。链接如下： ## 关于免费的开源托管平台 Read the Docs [Read the Docs](https://readthedocs.org/) 通过自动为您构建，版本控制和托管文档来简化软件文档。 [github-badge]: https://img.shields.io/github/last-commit/Eugene-Forest/NoteBook [github-link]: https://img.shields.io/github/last-commit/Eugene-Forest/NoteBook [rtd-badge]: https://readthedocs.org/projects/studynotes/badge/?version=k-doc [rtd-link]: https://studynotes.readthedocs.io/zh/k-doc/?badge=k-doc