几款文档框架：Mkdocs、Sphinx、Teadocs、docsify

网编 2023年04月14日 17:43 213 0

文档框架

同博客框架 wordpress、Hexo 等一样，Web 文档也有自己的框架，如比如 Java 的 Javadoc，Python 的 pydoc，以及Python-sphinx。对于 Python 有专门文档标记语言 reStructuredText（RST），常见的 Python 各种库和工具的帮助文档基本都是用 RST 所写。如 Requests、Flask、Scrapy 等。

不过，用 RST 编写对于已经会了 Markdown（更为流行）的读者来说，有点浪费，而且两者的语法差异较大，容易造成记忆冲突。幸运的是有了 mkdocs，不仅能轻松制作类似 Scrapy 帮助文档的文档项目，而且支持 markdown 语法。

安装 MkDocs

pip install mkdocs

创建项目

执行下面命令就在当前目录下，生成一个 testdocs 文件夹，就是创建的文档项目

mkdocs new testdocs

cd命令进入文件夹，查看结构

几款文档框架：Mkdocs、Sphinx、Teadocs、docsify

mkdocs.yml 为配置文件
docs 文件夹中为文档文件目录，文件使用 markdown 编写

文档预览

进入创建的文档项目目录，执行 mkdocs serve：

mkdocs serve

INFO     -  Building documentation...
INFO     -  Cleaning site directory
INFO     -  Documentation built in 0.16 seconds
INFO     -  [18:16:18] Serving on http://127.0.0.1:8000/

将启动一个 Web 服务器，用于预览 testdocs 文件项目，效果如下：将启动一个 Web 服务器，用于预览 testdocs 文件项目，效果如下：

几款文档框架：Mkdocs、Sphinx、Teadocs、docsify

进行配置

mkdocs 的配置简单明了，采用 yml 格式：

site_name: MkLorum
site_url: https://example.com/
nav:
    - Home: &apos;index.md&apos;
    - About: &apos;markdown.md&apos;
theme: readthedocs

当文档比较复杂时，可以通过嵌套的方式对 nav 进行配置，例如在 Home 下还有子菜单，menu1 和 menu2：

nav:
    - Home: &apos;index.md&apos;
    - &apos;User Guide&apos;:
        - &apos;Writing your docs&apos;:
            - Menu1 : &apos;menu1.md&apos;
            - Menu2 : &apos;menu2.md&apos;
        - &apos;Styling your docs&apos;: &apos;./style/styling-your-docs.md&apos;
    - About:
        - &apos;License&apos;: &apos;license.md&apos;
        - &apos;Release Notes&apos;: &apos;release-notes.md&apos;

效果如下：

几款文档框架：Mkdocs、Sphinx、Teadocs、docsify

如果菜单名中有空格需要用引号(单双皆可)括起来
文档文件不要同导航结构配合，可以为导航配置相对文件路径
菜单层级可以无限嵌套
默认情况下，即在不配置导航 (nav) 的情况下，会按照文件名，目录结构生成导航菜单

更换主题

下载主题：

pip **install** mkdocs-material mkdocs-windmill

mkdocs.yml里添加:

theme:
  name: &apos;material&apos;
# &#x4E5F;&#x53EF;&#x4EE5;&#x9009;bootstrap

其他的一些配置：

theme:
  name: &quot;material&quot;
  # logo: &apos;images/logo.svg&apos;
  logo:
      icon: &quot;mkdocs&quot;
  palette:
      primary: &quot;black&quot;
      accent: &quot;deep orange&quot;
  language: &quot;zh&quot;

material页面风格：

几款文档框架：Mkdocs、Sphinx、Teadocs、docsify

@H_301_147@更多主题：https://github.com/mkdocs/mkdocs/wiki/MkDocs-Themes 一些约定

站点首页默认情况下，必须创建一个 index.md 作为站点首页。同时也支持 README.md 作为首页，会将其转化为 index.html。如果 index.md 和 README.md 同时存在，将忽略 README.md
非 markdown 文件 markdown 文件，即扩展名为 md 的文件，会被转化为 html。非 markdown 文件，会被原封拷贝，不做任何修改@H_403_155@
内部链接如果需要引用另一个文件，只需要按照 markdown 链接的方式，连接到这个文件就可以了，例如详情请参考。不要担心文件名，因为生成站点时会自动换成 html 文件路径

生成站点

执行mkdocs build命令，生成站点，点击index.html即可

mkdocs build

使用sphinx 安装sphinx和主题

pip install sphinx sphinx_rtd_theme

创建项目

创建一个文件夹后，执行命令

sphinx-quickstart

编写文档

几款文档框架：Mkdocs、Sphinx、Teadocs、docsify

修改主题

在conf.py文件中添加这两行代码，修改主题

import sphinx_rtd_theme
html_theme = &apos;sphinx_rtd_theme&apos;

# &#x8BB0;&#x5F97;&#x5220;&#x9664;&#x4E0B;&#x9762;&#x7684;html_theme = &apos;alabaster&apos;

更多主题请参考：https://sphinx-themes.org/

构建站点

在根目录输入命令，即可生成网站构建。在build/html目录下即可看到生成的网站

make html

点击index.html即可查看

几款文档框架：Mkdocs、Sphinx、Teadocs、docsify

使用Teadocs

Teadocs 是一款能够帮你快速构建html文档的工具，它基于nodejs编写，并使用markdown来编写文档内容。

Teadocs 提供内置的搜索技术，除了编写好你引以为豪的内容以外，你无需关注的任何额外的技术问题。

你可以使用它来编写开源书籍、api文档学习、笔记、学习心得、甚至可以用来写博客。

安装

需要nodejs版本 >= 8.0，npm 版本 > 3.

$ npm install -g teadocs

初始化一个文档项目

$ teadcos init mydocs

进入这个文档目录

$ cd mydocs

此步骤是进入文档编辑模式（开发模式），此模式将监视markdown文件的变化，实时热替换html页面。

$ teadocs dev

自动生成项目初始结构

如果你想偷懒，那么你可以在编写好tree.md（菜单的配置文件）的情况下，直接运行以下命令，teadocs可以自动帮你生成md文件。

$ teadocs init

编译成html

$ teadocs build

文档目录结构介绍

testdocs
&#x251C;&#x2500; build  #&#x8FD9;&#x4E2A;&#x662F;&#x7F16;&#x8BD1;&#x8F93;&#x51FA;&#x7684;&#x76EE;&#x5F55;
&#x2502;    &#x251C;&#x2500; config
&#x2502;    &#x2502;    &#x251C;&#x2500; main.html
&#x2502;    &#x2502;    &#x251C;&#x2500; nav.html
&#x2502;    &#x2502;    &#x2514;&#x2500; structure.html
&#x2502;    &#x251C;&#x2500; custom_theme.html
&#x2502;    &#x251C;&#x2500; data.js
&#x2502;    &#x251C;&#x2500; deploy.html
&#x2502;    &#x251C;&#x2500; index.html
&#x2502;    &#x251C;&#x2500; install.html
&#x2502;    &#x251C;&#x2500; quick_start.html
&#x2502;    &#x251C;&#x2500; static
&#x2502;    &#x2502;    &#x251C;&#x2500; css
&#x2502;    &#x2502;    &#x251C;&#x2500; font-awesome-4.7.0
&#x2502;    &#x2502;    &#x251C;&#x2500; fonts
&#x2502;    &#x2502;    &#x251C;&#x2500; images
&#x2502;    &#x2502;    &#x2514;&#x2500; js
&#x2502;    &#x2514;&#x2500; template_markdown.html
&#x251C;&#x2500; docs #&#x8FD9;&#x4E2A;&#x662F;&#x6587;&#x6863;&#x7684;&#x6E90;&#x6587;&#x4EF6;&#x76EE;&#x5F55;&#xFF0C;&#x4E5F;&#x5C31;&#x662F;markdown&#x6587;&#x4EF6;&#x76EE;&#x5F55;&#x3002;
&#x2502;    &#x251C;&#x2500; config
&#x2502;    &#x2502;    &#x251C;&#x2500; main.md
&#x2502;    &#x2502;    &#x251C;&#x2500; nav.md
&#x2502;    &#x2502;    &#x2514;&#x2500; structure.md
&#x2502;    &#x251C;&#x2500; custom_theme.md
&#x2502;    &#x251C;&#x2500; deploy.md
&#x2502;    &#x251C;&#x2500; index.md
&#x2502;    &#x251C;&#x2500; install.md
&#x2502;    &#x251C;&#x2500; quick_start.md
&#x2502;    &#x2514;&#x2500; template_markdown.md
&#x251C;&#x2500; static # &#x8FD9;&#x4E2A;&#x5730;&#x65B9;&#x662F;&#x7528;&#x4E8E;&#x5B58;&#x653E;&#x6587;&#x6863;&#x4E2D;&#x9700;&#x8981;&#x7528;&#x8981;&#x7684;&#x9759;&#x6001;&#x6587;&#x4EF6;&#xFF0C;&#x4F8B;&#x5982;&#x56FE;&#x7247;&#x7B49;&#xFF0C;&#x5B83;&#x4F1A;&#x81EA;&#x52A8;copy&#x5230;build&#x76EE;&#x5F55;&#x4E0B;&#x3002;
|
&#x251C;&#x2500; teadocs.config.js # &#x8FD9;&#x662F;teadocs&#x7684;&#x4E3B;&#x914D;&#x7F6E;&#x6587;&#x4EF6;
&#x2514;&#x2500; tree.html # &#x8FD9;&#x662F;&#x6587;&#x6863;&#x7684;&#x83DC;&#x5355;&#x914D;&#x7F6E;&#x6587;&#x4EF6;

主配置文件说明

菜单的配置文件是你文档根目录下面的 teadocs.config.js，它是一个javascript的文件。

主配置文件的所有配置项都不是必填你完全可以什么也不填写，它的代码如下：

&apos;use strict&apos;;
const path = require(&apos;path&apos;)

module.exports = {
    doc: {
        name: &quot;&quot;, //&#x6587;&#x6863;&#x540D;&#x79F0;
        description: &quot;&quot;, //&#x6587;&#x6863;&#x7684;&#x63CF;&#x8FF0;
        version: &quot;&quot;, //&#x6587;&#x6863;&#x7684;&#x7248;&#x672C;
        dir: &quot;&quot;, //&#x6587;&#x6863;&#x7684;&#x76EE;&#x5F55;
        outDir: &quot;&quot;, //&#x6587;&#x6863;&#x7F16;&#x8BD1;&#x6210;html&#x65F6;&#x8F93;&#x51FA;&#x7684;&#x76EE;&#x5F55;
        staticDir: &quot;&quot; //&#x6587;&#x6863;&#x6240;&#x7528;&#x5230;&#x7684;&#x9759;&#x6001;&#x6587;&#x4EF6;&#x7684;&#x5730;&#x5740;
    }, 
    theme: {
        dir: &quot;&quot;, //&#x4E3B;&#x9898;&#x7684;&#x76EE;&#x5F55;&#xFF0C;&#x53EF;&#x81EA;&#x5B9A;&#x4E49;&#x4E3B;&#x9898;
        title: &quot;&quot;, //html&#x7684;title&#x6807;&#x7B7E;
        headHtml: &quot;&quot;, //html head &#x7684;&#x4EE3;&#x7801;
        footHtml: &quot;&quot;, //html &#x5E95;&#x90E8; &#x7684;&#x4EE3;&#x7801;
        isMinify: true, //&#x662F;&#x5426;&#x4E3A;&#x8F93;&#x51FA;&#x7684;html&#x542F;&#x7528;&#x538B;&#x7F29;
        rootPath: &quot;/&quot; //&#x8868;&#x793A;&#x6839;&#x8DEF;&#x5F84;&#xFF0C;&#x5982;&#x679C;&#x90E8;&#x7F72;&#x5728;&#x6DF1;&#x76EE;&#x5F55;&#x4E0B;&#x9762;&#xFF0C;&#x8FD9;&#x4E2A;&#x914D;&#x7F6E;&#x9879;&#x5FC5;&#x586B;&#xFF0C;&#x4E0D;&#x7136;&#x4F1A;&#x51FA;&#x73B0;&#x627E;&#x4E0D;&#x5230;&#x8D44;&#x6E90;&#x8DEF;&#x5F84;&#x7684;&#x9519;&#x8BEF;&#x3002;
    },
    nav: {
        tree: &quot;./tree&quot;
    }
}

默认配置

module.exports = {
    doc: {
        name: &quot;&#x6B22;&#x8FCE;&#x4F7F;&#x7528;Teadocs&#x6587;&#x6863;&#x751F;&#x6210;&#x7CFB;&#x7EDF;&quot;,
        description: &quot;&#x6B22;&#x8FCE;&#x4F7F;&#x7528;Teadocs&#x6587;&#x6863;&#x751F;&#x6210;&#x7CFB;&#x7EDF;&quot;,
        version: &quot;0.0.1&quot;,
        dir: &quot;./docs&quot;,
        outDir: &quot;./build&quot;,
        staticDir: &quot;./static&quot;
    },
    theme: {
        dir: __dirname + &apos;/../themes/default&apos;,
        title: &quot;&#x6B22;&#x8FCE;&#x4F7F;&#x7528;Teadocs&#x6587;&#x6863;&#x751F;&#x6210;&#x7CFB;&#x7EDF;&quot;,
        headHtml: `
        &lt;Meta name=&quot;description&quot; content=&quot;&#x6B22;&#x8FCE;&#x4F7F;&#x7528;Teadocs&#x6587;&#x6863;&#x751F;&#x6210;&#x7CFB;&#x7EDF;&quot; /&gt;
        &lt;Meta name=&quot;keywords&quot; content=&quot;teadocs, &#x6587;&#x6863;&#x751F;&#x6210;&#x5668;&quot; /&gt;
        `,
        footerHtml: &quot;&quot;,
        isMinify: false,
        rootPath: &quot;/&quot;
    },
    nav: {
        tree: &quot;&lt;ul&gt;&lt;li&gt;&lt;a&gt;&#x6B22;&#x8FCE;&#x4F7F;&#x7528;Teadocs&#x6587;&#x6863;&#x751F;&#x6210;&#x7CFB;&#x7EDF;&lt;/a&gt;&lt;/li&gt;&lt;/ul&gt;&quot;
    }
}

菜单配置文件说明

菜单的配置文件是你文档根目录下面的 tree.md 文件，它采用了markdown语法来进行书写。

菜单结构

例如，本文档的菜单结构如下：

- [&#x4ECB;&#x7ECD;](/index)
- [&#x5FEB;&#x901F;&#x5165;&#x95E8;](/quick_start)
- [&#x5B89;&#x88C5;](/install)
- +&#x914D;&#x7F6E;&#x4ECB;&#x7ECD;
    - [&#x6587;&#x6863;&#x76EE;&#x5F55;&#x7ED3;&#x6784;&#x4ECB;&#x7ECD;](/config/structure)
    - [&#x4E3B;&#x914D;&#x7F6E;&#x6587;&#x4EF6;&#x8BF4;&#x660E;](/config/main)
    - [&#x83DC;&#x5355;&#x914D;&#x7F6E;&#x6587;&#x4EF6;&#x8BF4;&#x660E;](/config/nav)
- [markdown&#x6A21;&#x7248;](/template_markdown)
- [&#x81EA;&#x5B9A;&#x4E49;&#x4E3B;&#x9898;](/custom_theme)
- [&#x90E8;&#x7F72;](/deploy)

符号介绍

语法完全使用markdown里的无序列表定义语法，但是要特别注意以下几点：

[] 里的内容表示菜单的标题，如果不写[]则代表这个菜单没有链接仅作为一个菜单名称。 () 里的内容表示菜单的markdown文件的地址，并且也代表了生成后的html文件url。

代表了在生成的html里默认展开这个菜单，需要注意的是，这不是markdown的语法，这是teadocs的规定，+一定要写在文本的前面，而不是[的前面

markdown模版

你编写的markdown文件可以使用内置的ejs模版引擎，比如我们可以轻而易举的写个循环，像这样：

**&lt;** **%** **[****1****,****2****,****3****,****4****]****.****forEach****(****function** **(****)** **{** **%** **&gt;**
**-** &#x6B22;&#x8FCE;&#x4F7F;&#x7528;Teadocs&#x6587;&#x6863;&#x751F;&#x6210;&#x5DE5;&#x5177;
**&lt;** **%** **}****)** **%** **&gt;**

效果：

<% [1,2,3,4].forEach(function () { %>