使用MKDocs构建Markdown格式API文档(macOS)

￡神魔★判官ぃ 2022-09-24 01:27 398阅读 0赞

1.  **MkDocs是什么?**
    
    [MKDocs][]就是一个能快速，简单，优雅的生成静态文档站点的项目。文档用Markdown书写，目录用YAML配置，弄好之后你可以把它放到Github的Pages 上，或者自己服务器上就可以了。并且也有好几套UI供你选择MkDocs UI，特别适合那些做开源项目的童鞋，生成说明文档使用。总的来说，就是省时省力，效果还不错
2.  **安装**
    
    我的机子装了brew，所以可以直接命令行安装软件。
    
    1.  安装Python
        
        在终端输入下面指令：`brew install python`
        
        查看版本：
        
            python --version
            Python 2.7.10
    2.  安装mkdocs
        
        在终端输入下面指令：`pip install mkdocs`
        
        查看版本：
        
            mkdocs --version
            mkdocs, version 0.15.3
3.  实战一下
    
    1.  在终端输入下面指令：`mkdocs new project`。创建一个名为project的mkdocs的项目。
    2.  运行项目：
        
            cd project
            mkdocs serve
    3.  显示如下：
        
            Running at: http://127.0.0.1:8000/
    4.  在浏览器中访问上面的链接即可。
4.  解释一下
    
    1.  在project文件下，会有一个doc目录和一个mkdocs.yml文件，.yml就是配置文件。修改里面的内容就可以修改样式以及需要添加的展示内容。
    2.  给出几个样式：
        
            theme: readthedocs
            theme: bootstrap
            theme: amelia
            theme: cosmo
            theme: slate
            theme: yeti
            theme: united
            theme: journal
5.  其他指令
    
        $mkdocs build /*生成网站的site目录，里面有一些静态资源*/
        $mkdocs build --clean
        $mkdocs --help
6.  说明
    
    系统：macOS
    
    其他详细的说明，可以去官网查看[MKDocs][]。

--------------------

参考资料：  
MKDocs官网文档  
备注：  
转载请注明出处：[http://blog.csdn.net/wsyw126/article/details/51997395][http_blog.csdn.net_wsyw126_article_details_51997395]  
作者：WSYW126

[MKDocs]: http://www.mkdocs.org/
[http_blog.csdn.net_wsyw126_article_details_51997395]: http://blog.csdn.net/wsyw126/article/details/51997395