项目预览

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
test_mkdocs
│
├─my_docs
│  │  gen_md_from_src.py
│  │  mkdocs.yml
│  │  readme.md
│  │
│  └─docs
│      │  index.md
│      │  帮助文档.md
│      │
│      └─API
│              fun_1.md
│              fun_2.md
│
└─src
        fun_1.m
        fun_2.py

最终的 mkdocs.yml

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
site_name: Xdd的帮助系统
theme:
  name: material
  palette:
    primary: 'Blue'
  icon:
    repo: fontawesome/brands/github
  features:
    - search.highlight

plugins:
    - search:
        separator: '[\s\u200b\-]'

extra:
  # social:
  #   - icon: fontawesome/solid/paper-plane
  #     link: mailto:[email protected]
  generator: false


markdown_extensions:
  - meta                  # 元数据
  - pymdownx.arithmatex:  # 数学公式
      generic: true
  - pymdownx.highlight    # 代码高亮

repo_url: https://github.com/xie-dd/mkdocs
copyright: Copyright © xie-dd
use_directory_urls: false

安装与生成文档

安装与配置 mkdocs

1
2
3
4
pip install mkdocs
pip install mkdocs-material
cd test_mkdocs
mkdocs new my_docs

由代码脚本的注释生成文档

1
2
cd my_docs
python gen_md_from_src.py

启动本地服务器

1
2
mkdocs serve
浏览器打开：127.0.0.1:8000

其他问题

本地使用 index.html 问题

解决方法：添加use_directory_urls关键字

1
2
3
repo_url: https://github.com/xie-dd/mkdocs
copyright: Copyright © xie-dd
use_directory_urls: false

下划线被替换为空格

markdown 文件生成的 html 的文件在侧边导航栏中下划线会被替换为空格

解决方法：在 markdown 文档中添加title

1
2
3
---
title: A-A.A2
---

中文搜索

  1. 修改文件 mkdocs.yml，添加 plugins-search 部分
1
2
3
4
5
6
7
8
site_name: Xdd的帮助系统
theme:
  name: material
  palette:
    primary: 'green'
plugins:
    - search:
        separator: '[\s\u200b\-]'
  1. 安装分词模块：pip install jieba
  2. 修改文件 mkdocs.contrib.search.search_index.py
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
def _add_entry(self, title, text, loc):
    """
    A simple wrapper to add an entry and ensure the contents
    is UTF8 encoded.
    """
    import jieba
    text = text.replace('\u3000', ' ') # 替换中文全角空格
    text = text.replace('\u00a0', ' ')
    text = re.sub(r'[ \t\n\r\f\v]+', ' ', text.strip())

    # 给正文分词
    text_seg_list = jieba.cut_for_search(text) # 结巴分词，搜索引擎模式，召回率更高
    text = " ".join(text_seg_list) # 用空格连接词语

    # 给标题分词
    title_seg_list = jieba.cut(title, cut_all=False) # 结巴分词，精确模式，更可读
    title = " ".join(title_seg_list) # 用空格连接词语

    self._entries.append({
        'title': title,
        'text': str(text.encode('utf-8'), encoding='utf-8'),
        'location': loc
    })

部署到 github page

注意：和 docsify 一样，不用部署到 ***.github.io 仓库

  1. 把程序上传到 Github 任意仓库
  2. 在本地项目执行下面代码，会生成一个 site 文件夹
1
2
mkdocs build
mkdocs gh-deploy --clean
  1. 登录 github—>找到对应仓库—>Settings—>Pages—>Source:Deploy from a branch—>Branch:gh-pages, root—>Save
  2. 访问 usename.github.io/repo_name 即可。如 xie-dd.github.io/mkdocs

简化提交程序

在mkdocs.yml文件相同目录下添加一个git_push.sh文件，文件内容为：

1
2
3
4
5
6
7
8
9
10
11
12
# @echo off
# python gen_md_from_src.py
mkdocs build
mkdocs gh-deploy --clean

git pull
git add .
read -p "input commit message: " msg
git commit -m "$msg"
# git commit -m 'WIN10'
git push
read -p "===== git push ok, Type enter to exit. ===== " msg00

批量将 Python/Matlab 文件的注释生成文档

函数：gen_md_from_src.py

https://www.yuque.com/xdd1997/ek3kug/oown6is8ts58iyde?singleDoc# 密码：rzab

使用条件：代码的注释是 markdown 格式

1
2
3
4
5
6
7
8
9
10
11
12
13
function c = add(a,b)
% ## Function
% 计算两个数的和
%
% ## Args
%     - a: *int* 第1个加数
%     - b: `int` 第2个加数
%
% ## Return
%     - c: 两个数的和
% ## End

c = a+b;

在mkdocs.yml文件中添加下面内容即可。如果不指定nav，mkdocs 将根据文件名自动生成nav

1
2
3
4
5
6
7
8
9
10
11
nav:
  - Home: "index.md"
  - B:
      - B1: "writing-your-docs.md"
      - B2: "styling-your-docs.md"
  - C:
      - C1: "license.md"
      - C2: "release-notes.md"
  - API:
      - "A-A.A2": "API/A-A.A2.md"
      - "A-A.A3": "API/A-A.A3.md"

添加自定义的 CSS

资料：https://zhuanlan.zhihu.com/p/568788779

  1. 新建文件docs\stylesheets\extra.css，内容如下
1
2
3
4
5
6
7
.md-typeset h1,
.md-typeset h2,
.md-typeset h3 {
  font-size: 1.22em;
  font-weight: bold;
  color: #4052b5;
}
  1. 在mkdocs.yml文件添加如下内容
1
extra_css: -stylesheets/extra.css;
  1. 执行mkdocs serve预览

注：extra_css 的根目录是 docs