同博客框架 WordPress、Hexo 等一样,Web 文档也有自己的框架,如比如 Java 的 Javadoc,Python 的 pydoc,以及Python-sphinx。对于 Python 有专门文档标记语言 reStructuredText(RST),常见的 Python 各种库和工具的帮助文档基本都是用 RST 所写。如 Requests、Flask、Scrapy 等。
不过,用 RST 编写对于已经会了 Markdown(更为流行) 的读者来说,有点浪费,而且两者的语法差异较大,容易造成记忆冲突。幸运的是有了 mkdocs,不仅能轻松制作类似 Scrapy 帮助文档的文档项目,而且支持 markdown 语法。
pip install mkdocs
执行下面命令就在当前目录下,生成一个 testdocs 文件夹,就是创建的文档项目
mkdocs new testdocs
cd命令进入文件夹,查看结构
进入 创建的文档项目目录,执行 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 的配置简单明了,采用 yml 格式:
site_name: MkLorum
site_url: https://example.com/
nav:
- Home: 'index.md'
- About: 'markdown.md'
theme: readthedocs
当文档比较复杂时,可以通过嵌套的方式对 nav 进行配置,例如在 Home 下还有子菜单,menu1 和 menu2:
当文档比较复杂时,可以通过嵌套的方式对 nav 进行配置,例如在 Home 下还有子菜单,menu1 和 menu2:
nav:
- Home: 'index.md'
- 'User Guide':
- 'Writing your docs':
- Menu1 : 'menu1.md'
- Menu2 : 'menu2.md'
- 'Styling your docs': './style/styling-your-docs.md'
- About:
- 'License': 'license.md'
- 'Release Notes': 'release-notes.md'
效果如下:
默认情况下,即在不配置导航 (nav) 的情况下,会按照文件名,目录结构生成导航菜单
下载主题:
pip **install** mkdocs-material mkdocs-windmill
mkdocs.yml里添加:
theme:
name: 'material'
# 也可以选bootstrap
其他的一些配置:
theme:
name: "material"
# logo: 'images/logo.svg'
logo:
icon: "mkdocs"
palette:
primary: "black"
accent: "deep orange"
language: "zh"
material页面风格:
执行mkdocs build命令,生成站点,点击index.html即可
mkdocs build
pip install sphinx sphinx_rtd_theme
创建一个文件夹后,执行命令
sphinx-quickstart
在conf.py文件中添加这两行代码,修改主题
import sphinx_rtd_theme
html_theme = 'sphinx_rtd_theme'
# 记得删除下面的html_theme = 'alabaster'
更多主题请参考:https://sphinx-themes.org/
在根目录输入命令,即可生成网站构建。在build/html目录下即可看到生成的网站
make html
点击index.html即可查看
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
$ teadocs build
testdocs
├─ build #这个是编译输出的目录
│ ├─ config
│ │ ├─ main.html
│ │ ├─ nav.html
│ │ └─ structure.html
│ ├─ custom_theme.html
│ ├─ data.js
│ ├─ deploy.html
│ ├─ index.html
│ ├─ install.html
│ ├─ quick_start.html
│ ├─ static
│ │ ├─ css
│ │ ├─ font-awesome-4.7.0
│ │ ├─ fonts
│ │ ├─ images
│ │ └─ js
│ └─ template_markdown.html
├─ docs #这个是文档的源文件目录,也就是markdown文件目录。
│ ├─ config
│ │ ├─ main.md
│ │ ├─ nav.md
│ │ └─ structure.md
│ ├─ custom_theme.md
│ ├─ deploy.md
│ ├─ index.md
│ ├─ install.md
│ ├─ quick_start.md
│ └─ template_markdown.md
├─ static # 这个地方是用于存放文档中需要用要的静态文件,例如图片等,它会自动copy到build目录下。
|
├─ teadocs.config.js # 这是teadocs的主配置文件
└─ tree.html # 这是文档的菜单配置文件
菜单的配置文件是你文档根目录下面的 teadocs.config.js
,它是一个javascript的文件。
主配置文件的所有配置项都不是必填你完全可以什么也不填写,它的代码如下:
'use strict';
const path = require('path')
module.exports = {
doc: {
name: "", //文档名称
description: "", //文档的描述
version: "", //文档的版本
dir: "", //文档的目录
outDir: "", //文档编译成html时输出的目录
staticDir: "" //文档所用到的静态文件的地址
},
theme: {
dir: "", //主题的目录,可自定义主题
title: "", //html的title标签
headHtml: "", //html head 的代码
footHtml: "", //html 底部 的代码
isMinify: true, //是否为输出的html启用压缩
rootPath: "/" //表示根路径,如果部署在深目录下面,这个配置项必填,不然会出现找不到资源路径的错误。
},
nav: {
tree: "./tree"
}
}
module.exports = {
doc: {
name: "欢迎使用Teadocs文档生成系统",
description: "欢迎使用Teadocs文档生成系统",
version: "0.0.1",
dir: "./docs",
outDir: "./build",
staticDir: "./static"
},
theme: {
dir: __dirname + '/../themes/default',
title: "欢迎使用Teadocs文档生成系统",
headHtml: `
<meta name="description" content="欢迎使用Teadocs文档生成系统" />
<meta name="keywords" content="teadocs, 文档生成器" />
`,
footerHtml: "",
isMinify: false,
rootPath: "/"
},
nav: {
tree: "<ul><li><a>欢迎使用Teadocs文档生成系统</a></li></ul>"
}
}
菜单的配置文件是你文档根目录下面的 tree.md
文件,它采用了markdown语法来进行书写。
例如,本文档的菜单结构如下:
- [介绍](/index)
- [快速入门](/quick_start)
- [安装](/install)
- +配置介绍
- [文档目录结构介绍](/config/structure)
- [主配置文件说明](/config/main)
- [菜单配置文件说明](/config/nav)
- [markdown模版](/template_markdown)
- [自定义主题](/custom_theme)
- [部署](/deploy)
语法完全使用markdown里的无序列表定义语法,但是要特别注意以下几点:
[] 里的内容表示菜单的标题,如果不写[]则代表这个菜单没有链接仅作为一个菜单名称。 () 里的内容表示菜单的markdown文件的地址,并且也代表了生成后的html文件url。
你编写的markdown文件可以使用内置的ejs模版引擎,比如我们可以轻而易举的写个循环,像这样:
**<** **%** **[****1****,****2****,****3****,****4****]****.****forEach****(****function** **(****)** **{** **%** **>**
**-** 欢迎使用Teadocs文档生成工具
**<** **%** **}****)** **%** **>**
效果:
<% [1,2,3,4].forEach(function () { %>
你可以构建自己的主题文件,只要符合Teadocs的主题规范,具体可以自行参考默认主题。
如何使用自己构建的主题? 在 teadocs.config.js 文件的 theme.dir 配置项中指定你的自定义主题路径就可以了。
可以你的文档源文件上传到github上,使用 .gitignore 屏蔽 ./build 目录。
建议使用nginx等静态服务器软件搭建一个静态服务器进行访问即可。
teadocs dev
默认端口号是3210
https://docsify.js.org/#/zh-cn/ docsify是一个超级好用的文档站点生成器!特点是使用简单,跟着官网教程输入两行命令就能完成安装和生成站点了,生成的文档样式也很精简优雅,并且是响应式的,手机上看也很不错。
阿里推出的文档站点生成工具,也是输入几行命令就能得到文档网站。和 docsify 不同的是,Dumi 专为 组件开发 场景而生,很适合作为组件库的文档。可以嵌入和折叠代码块、提供组件在终端中的浏览效果等,Dumi 生成的网站很精简,而且封面支持自定义特性的展示,因此也很适合作为项目或产品的官方文档。
参考文章:「https://blog.csdn.net/m0_46521785/article/details/119812280」