使用mkdocs 生成文档

简介

mkdocs 是一个简单、快速 并且 完全静态的网站生成工具。用以构建项目文档页面。

使用Markdown编写文档源文件,YAML 编写配置文件

可以部署到任何地方

由于 mkdocs 生成的是完全静态页面,所以它可以部署到任何地方(Github pages,Amazon S3,Gitlab pages,或任何你能想到的地方

基础配置

首先,需要一个配置文件

mkdocs.yml:

site_name: 文档或项目名
pages:
- 1 主页: index.md
theme: material #readthedocs

这里,描述了标题,并且有一个pages ,下面是各个页面的导航结构。

可配置多层结构如:

pages:
- A:
  -A.1: a.1.md
  -A.2: a.1.md

docs/index.md:


## 这里是示例主页

进阶配置

这里,使用一个带比较完备扩展的示例

mkdocs.yml:

site_name: 文档或项目名
pages:
- 1 主页: index.md
theme: material #readthedocs
extra:
  palette:
    primary: 'cyan'
    accent: 'purple'
markdown_extensions:
  - toc
  - smarty
  - pymdownx.arithmatex
  - pymdownx.betterem:
      smart_enable: all
  - pymdownx.caret
  - pymdownx.critic
  - pymdownx.details
  - pymdownx.emoji:
      emoji_generator: !!python/name:pymdownx.emoji.to_svg
  - pymdownx.inlinehilite
  - pymdownx.magiclink
  - pymdownx.mark
  - pymdownx.smartsymbols
  - pymdownx.superfences
  - pymdownx.tasklist:
      custom_checkbox: true
  - pymdownx.tilde
plugins:
  - search

docs/index.md:


## 这里是示例主页

扩展语法参考: pydownx

使用docker进行构建

docker run --rm -v `pwd`:/docs squidfunk/mkdocs-material:2.2.0 build -d public

使用原生python 进行安装

pip install mkdocs mkdocs-material pymdown-extensions

mkdocs 使用甘特图

该功能由于比较复杂所以放在 mkdocs-diagram 进行迭代开发

在mkdocs.yaml 文件添加

site_name: 文档或项目名
pages:
- 1 主页: index.md
theme: material #readthedocs
extra:
  palette:
    primary: 'cyan'
    accent: 'purple'
extra_javascript:
  - https://unpkg.com/mermaid@7.1.0/dist/mermaid.min.js
  - https://cdnjs.cloudflare.com/ajax/libs/raphael/2.2.7/raphael.min.js
  - https://cdnjs.cloudflare.com/ajax/libs/underscore.js/1.8.3/underscore-min.js
  - https://cdnjs.cloudflare.com/ajax/libs/js-sequence-diagrams/1.0.6/sequence-diagram-min.js
  - https://cdnjs.cloudflare.com/ajax/libs/flowchart/1.6.5/flowchart.min.js
  - js/umlconvert.js
markdown_extensions:
  - toc
  - smarty
  - pymdownx.arithmatex
  - pymdownx.betterem:
      smart_enable: all
  - pymdownx.caret
  - pymdownx.critic
  - pymdownx.details
  - pymdownx.emoji:
      emoji_generator: !!python/name:pymdownx.emoji.to_svg
  - pymdownx.inlinehilite
  - pymdownx.magiclink
  - pymdownx.mark
  - pymdownx.smartsymbols
  - pymdownx.superfences:
      custom_fences: [
            {name: flow, class: uml-flowchart}
           ,{name: sequence, class: uml-sequence-diagram}
           ,{name: mermaid, class: uml-mermaid}
      ]
  - pymdownx.tasklist:
      custom_checkbox: true
  - pymdownx.tilde
plugins:
  - search

添加文件

docs/js/umlconvert.js

//from: http://www.cmky.net/blog/tool/mkdocs.html
//author: humboldt
//new on : https://github.com/humboldt-xie/mkdocs-diagram
function EachTag(arr,tag,callback){
	var i=0,maxItem=arr.length;
	for (; i < maxItem; i++) {
		if(arr[i].tagName && arr[i].tagName.toLowerCase() == tag.toLowerCase()){
			callback(arr[i])
		}
	}
}

function code2Text(codeEl){
	var text = "",j;
	for (j = 0; j < codeEl.childNodes.length; j++) {
		var curNode = codeEl.childNodes[j];
		whitespace = /^\s*$/;
		if (curNode.nodeName === "#text" && !(whitespace.test(curNode.nodeValue))) {
			text = curNode.nodeValue;
			break;
		}
	}
	return text
}
function mermaidConvert(index,text,el){
	var insertSvg = function(svgCode) {
		el.innerHTML = svgCode;
	};
	mermaid.parse(text)
	mermaid.render('mermaid-' + index.toString(), text, insertSvg);
	return null
}

function flowchartConvert(index,text,el){
	diagram=flowchart.parse(text)	
	diagram.drawSVG(el,{});
	return null
}
function sequenceConvert(index,text,el){
	diagram=Diagram.parse(text)	
	diagram.drawSVG(el,{theme: 'simple'});
	return null
}
var diagramType={
	"gantt":mermaidConvert,
	"sequenceDiagram":mermaidConvert,
	"flowchart":mermaidConvert,
	"graph TD":mermaidConvert,
	"graph LR":mermaidConvert,
	"uml-flowchart":flowchartConvert,
	"uml-sequence-diagram":sequenceConvert
}
function convertUML() {
	var pre= document.querySelectorAll("pre")
	for (var i=0; i<pre.length; i++){
		var codeEl= pre[i];
		var parentEl = pre[i];
		EachTag(parentEl.childNodes,"code",function(code){
			codeEl=code;
		})
		var text=code2Text(codeEl);
		var type=mermaid.mermaidAPI.detectType(text);
		var conv=diagramType[type];
		if(text.indexOf("graph")==0){
			conv=mermaidConvert;
		}
		var pclass=parentEl.classList
		for(var j=0;!conv && j<parentEl.classList.length;j++){
			conv=diagramType[parentEl.classList[j]]
			if(conv){
				break;
			}
		}
		if(conv){
			el = document.createElement('div');
			el.className = type;
			try {
				parentEl.parentNode.insertBefore(el, parentEl);
				conv(i,text,el)
				parentEl.parentNode.removeChild(parentEl);
			}catch(err){
				codeEl.title=err.str;
			}
		}
		
	}
};

function onReady(fn) {
	if (document.addEventListener) {
		document.addEventListener('DOMContentLoaded', fn);
	} else {
		document.attachEvent('onreadystatechange', function() {
			if (document.readyState === 'interactive')
				fn();
		});
	}
}
(function (document) {
	onReady(function(){
		convertUML();
	});
})(document);

一些示例 效果

```mermaid
gantt
dateFormat  YYYY-MM-DD
title Adding GANTT diagram functionality to mermaid

section A section
Completed task:done,    des1, 2014-01-06,2014-01-08
Active task:active,  des2, 2014-01-09, 3d
gantt
dateFormat  YYYY-MM-DD
title Adding GANTT diagram functionality to mermaid

section A section
Completed task:done,    des1, 2014-01-06,2014-01-08
Active task:active,  des2, 2014-01-09, 3d

```mermaid
gantt
dateFormat  YYYY-MM-DD
title Adding GANTT diagram functionality to mermaid

section A section
Completed task            :done,    des1, 2014-01-06,2014-01-08
Active task               :active,  des2, 2014-01-09, 3d
Future task               :         des3, after des2, 5d
Future task2              :         des4, after des3, 5d

section Critical tasks
Completed task in the critical line :crit, done, 2014-01-06,24h
Implement parser and jison          :crit, done, after des1, 2d
Create tests for parser             :crit, active, 3d
Future task in critical line        :crit, 5d
Create tests for renderer           :2d
Add to mermaid                      :1d

section Documentation
Describe gantt syntax               :active, a1, after des1, 3d
Add gantt diagram to demo page      :after a1  , 20h
Add another diagram to demo page    :doc1, after a1  , 48h

section Last section
Describe gantt syntax               :after doc1, 3d
Add gantt diagram to demo page      :20h
Add another diagram to demo page    :48h
```
gantt
dateFormat  YYYY-MM-DD
title Adding GANTT diagram functionality to mermaid

section A section
Completed task            :done,    des1, 2014-01-06,2014-01-08
Active task               :active,  des2, 2014-01-09, 3d
Future task               :         des3, after des2, 5d
Future task2              :         des4, after des3, 5d

section Critical tasks
Completed task in the critical line :crit, done, 2014-01-06,24h
Implement parser and jison          :crit, done, after des1, 2d
Create tests for parser             :crit, active, 3d
Future task in critical line        :crit, 5d
Create tests for renderer           :2d
Add to mermaid                      :1d

section Documentation
Describe gantt syntax               :active, a1, after des1, 3d
Add gantt diagram to demo page      :after a1  , 20h
Add another diagram to demo page    :doc1, after a1  , 48h

section Last section
Describe gantt syntax               :after doc1, 3d
Add gantt diagram to demo page      :20h
Add another diagram to demo page    :48h

输入:

```flow
st=>start: Start:>http://www.google.com[blank]
e=>end:>http://www.google.com
op1=>operation: My Operation
sub1=>subroutine: My Subroutine
cond=>condition: Yes
or No?:>http://www.google.com
io=>inputoutput: catch something...
st->op1->cond
cond(yes)->io->e
cond(no)->sub1(right)->op1
```

输出:

st=>start: Start:>http://www.google.com[blank]
e=>end:>http://www.google.com
op1=>operation: My Operation
sub1=>subroutine: My Subroutine
cond=>condition: Yes
or No?:>http://www.google.com
io=>inputoutput: catch something...
st->op1->cond
cond(yes)->io->e
cond(no)->sub1(right)->op1

输入:

```sequence
Title: Here is a title
A->B: Normal line
B-->C: Dashed line
C->>D: Open arrow
D-->>A: Dashed open arrow
```

输出:

Title: Here is a title
A->B: Normal line
B-->C: Dashed line
C->>D: Open arrow
D-->>A: Dashed open arrow
gantt
dateFormat  YYYY-MM-DD
title Adding GANTT diagram functionality to mermaid

section A section
Completed task:done,    des1, 2014-01-06,2014-01-08
Active task:active,  des2, 2014-01-09, 3d

使用mermaid原理

通过遍历dom各个pre标签,取到里面code 内容,然后转换成text。

并识别text 开头,是gantt 等mermaid 格式,然后使用mermaid 进行绘制。

如果转换失败,则设置pre 或code 的title 显示错误信息。这样既不干扰阅读,又能看到错误信息。

同时,还使用了 - pymdownx.superfences:

superfences 会将制定的语言,打上相应的class,这样可以在前端找到它。

如 {name: flow, class: uml-flowchart} 则会在 ```flow 生成的pre 标签打上 class=uml-flowchart

humboldt Written by:

humboldt 的趣味程序园