mkdocs build markdown 过程（含python 创建独立env）

选型

在进行后台开发时，需呈现API文档到用户，可选择方案有

• 作业部落
• mkdocs
• Swagger

前两种方式能很好低于markdowm 兼容，也就是直接从markdown 形式的API文档生成即可，但作业部落 适合于私人项目，对一个公司的项目来说不大合适，因为采用的是别人的网站。

Swagger 是RestFul API 很流行的一种格式，可 自动提供测试，无需等待后端真正开发出来，利于前后端分离的模式。针对我们现有的markdown API 文档来说，不兼容，需重新建立 yaml, 较为繁杂，因而舍之。

mkdocs 是python 的一个包，针对markodown 可以build 出html, 再采用nginx 做映射，就可以线上访问。mkdocs 的好处是，与markdown 无缝兼容，一个markdown 就是一个页面，支持markdown 的特性，build 出来的页面相对比较美观。

使用 mkdocs

综上分析，我们采用mkdocs 进行API文档的 生成。

mkdocs 是python 的一个包，可采用pip install mkdocs 进行安装

考虑到生产环境的python 多版本包的问题（虽然在这，没这问题，为熟悉virtualEnv）,采用virtualEnv 来进行 运行环境隔离，python 的运行环境控制工具比较多，如pyenv 等。virtualenv 实际上隔离的是 python 的site-packages 避免包的版本冲突。

virtual env使用方法

转载源(已实测)：

• 用对应版本的pip 进行 virtualenv 安装:

  /data/env/python36cmdb/bin/pip install virtualenv

• 创建目录:

• 创建一个独立的Python运行环境，命名为vev：

  virtualenv --no-site-packages venv

  命令virtualenv就可以创建一个独立的Python运行环境，我们还加上了参数--no-site-packages，这样，已经安装到系统Python环境中的所有第三方包都不会复制过来，这样，我们就得到了一个不带任何第三方包的“干净”的Python运行环境。

  新建的Python环境被放到当前目录下的venv目录。有了venv这个Python环境，可以用source进入该环境：

• 激活环境

  source venv/bin/activate

  注意到命令提示符变了，有个(venv)前缀，表示当前环境是一个名为venv的Python环境。

  下面正常安装各种第三方包，并运行python命令：

• pip 进行所需的包安装

  pip install mkdocs

• 退出环境

  在venv环境下，用pip安装的包都被安装到venv这个环境下，系统Python环境不受任何影响。也就是说，venv环境是专门针对myproject这个应用创建的。

  退出当前的venv环境，使用deactivate命令：

  deactivate 

mkdocs 使用

​ 通过上一步 已把mkdocs 安装至python site-packages

• 创建一个项目

  mkdocs new my-project

• 启动服务

  mkdocs serve

  这时在 http://lcoalhost:8000 地址上就可以访问到示例

• 修改 模板，配置好相应的资源

  mkdocs: 主要的配置文件

  docs: markdown 文件存放处

  readme ： 自己加的说明

  本次主要 有两个文件，一个是index.md 还有一个是cmdb-api-doc.md

  mkdocs.yml 如下:

  site_name: CMDB文档资源
  site_url: null
  theme: mkdocs
  site_description: 'CMDB文档资源'
  
  docs_dir: docs
  site_dir: null
  
  pages:
  - Home: index.md
  - APIDocs: cmdb-api-doc.md
  
  
  markdown_extensions:
    - extra
    - tables
    - toc
    - fenced_code
    - smarty
    - footnotes
  
  copyright: Copyright &copy; 2014-2016 <a href="https://wutongtree.com" target="_blank">wutongtree.com</a>
  

  注意： docs /下的markdown 不支持中文文件名、中文路径，index.md 必须存在

• build 生成html,

  build的时候要进入，mkdoc.yml (docs/) 所在的目录

  mkdocs build

  执行以上命令后，将会在当前文件夹下出现一个site 文件夹，里面就是生成的html页面完整文件,执行后结果截图：

  (

  site/ 截图：

  nginx 映射

​

nginx 配置

server {
    listen    82;
    server_name cmdb.apidoc.com  www.cmdb.apidoc.com;
    location /{
    index index.html;
    root /data/web/cmdb-api-docs/mkdocs/site;
     }
  }

转载于:https://www.cnblogs.com/huangyuezhen/p/7732095.html