美文网首页flaskdjango
Python API文档生成记录

Python API文档生成记录

作者: Lucas_Wong | 来源:发表于2018-06-25 16:18 被阅读0次

    我是一个程序员,文档是个很头疼的东东。一直在找一个对于自己来说好用一些的生成文档的工具,前一阵找到了Markdown,相当不错的写作工具,最近一直在使用。最近公司要求生成内部API文档,写起来很麻烦,特别是生成word文档,需要的各种格式调整,费时费力。我使用Markdown写了一个版本,但是其他人都用word写的,无法整合,于是我在网上不停的寻找,终于让我找到了,Justmd + Markdown + Python + Mkdocs , 这个组合,简直是无与伦比啊。

    简单的说明一下:

    1. 软件安装

    1. 首先需要安装Python, 我安装的3.6版本,网上有很多安装教程,这里就不一一说明了。
    2. 安装Justmd,市面上有不少的 Markdown 编辑器,每个编辑器都有各自的特色功能。 justmd编辑器,除了能在多平台上使用以外,它还有一个智能粘贴的功能。
      这个智能粘贴功能支持图片、HTML 内容、Word 文档内容等,简单来说,就是将你复制的富文本内容转换为 Markdown 语言并粘贴,省去了你不少的操作呢。使用方法也很简单,复制后,使用菜单或者快捷键「Alt + V」来粘贴就可以了。
    3. Markdown工具,可以使用上面的Justmd,也可以使用其他的工具, 我个人觉得Typora更适合我个人的写作。这部分仁者见仁智者见智,我就不多做推荐了
    4. 安装Mkdocs,这个是Python下的一个模块,使用PIP安装即可,如下:
    pip install mkdocs
    

    官方文档:http://www.mkdocs.org/#mkdocs

    中文文档:http://markdown-docs-zh.readthedocs.io/zh_CN/latest/

    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文件夹

    相关文章

      网友评论

        本文标题:Python API文档生成记录

        本文链接:https://www.haomeiwen.com/subject/ekuyyftx.html