我是一个程序员,文档是个很头疼的东东。一直在找一个对于自己来说好用一些的生成文档的工具,前一阵找到了Markdown,相当不错的写作工具,最近一直在使用。最近公司要求生成内部API文档,写起来很麻烦,特别是生成word文档,需要的各种格式调整,费时费力。我使用Markdown写了一个版本,但是其他人都用word写的,无法整合,于是我在网上不停的寻找,终于让我找到了,Justmd + Markdown + Python + Mkdocs , 这个组合,简直是无与伦比啊。
简单的说明一下:
1. 软件安装
- 首先需要安装Python, 我安装的3.6版本,网上有很多安装教程,这里就不一一说明了。
- 安装Justmd,市面上有不少的 Markdown 编辑器,每个编辑器都有各自的特色功能。 justmd编辑器,除了能在多平台上使用以外,它还有一个智能粘贴的功能。
这个智能粘贴功能支持图片、HTML 内容、Word 文档内容等,简单来说,就是将你复制的富文本内容转换为 Markdown 语言并粘贴,省去了你不少的操作呢。使用方法也很简单,复制后,使用菜单或者快捷键「Alt + V」来粘贴就可以了。 - Markdown工具,可以使用上面的Justmd,也可以使用其他的工具, 我个人觉得Typora更适合我个人的写作。这部分仁者见仁智者见智,我就不多做推荐了
- 安装Mkdocs,这个是Python下的一个模块,使用PIP安装即可,如下:
pip install mkdocs
2. 生成
安装完上述工具后就可以使用Markdown工具进行写作了,根据需要可以写多个Markdown文档,统一写完后,放在同一个目录下面。
然后在命令行中生成Mkdocs目录
mkdocs new project-name
cd project-name
image.png
使用任意文本工具修改mkdocs.yml文档,格式说明如下:
site_name: MkLorum (文档的名称)
pages: (所有界面都在这个下面)
- Home: index.md (目录名称:文档名称.md)
- About: about.md
theme: readthedocs (主题设置)
default.theme
readthedocs.theme
上面是2个主题的效果图。
3. 启动项目:
$ mkdocs serve
INFO - Building documentation...
INFO - Cleaning site directory
[I 160402 15:50:43 server:271] Serving on http://127.0.0.1:8000
[I 160402 15:50:43 handlers:58] Start watching changes
[I 160402 15:50:43 handlers:60] Start detecting changes
然后在浏览器中访问http://127.0.0.1:8000 就可以看到相应的文档了。
基本介绍就到这里了,如果有任何问题,可以给我留言大家一起学习。
后记:
Mkdocs还可以生成静态页面,命令如下:
$mkdocs build --clean
生成 的静态页面在同目录下:site文件夹
网友评论