mkdocs

绝对完美

已于 2025-01-23 15:37:34 修改

阅读量134

点赞数 2

分类专栏： python 文章标签： python

于 2025-01-21 18:22:15 首次发布

本文链接：https://blog.csdn.net/wokoone/article/details/145288248

版权

python 专栏收录该内容

4 篇文章

订阅专栏

mkdocs介绍

地址：

https://github.com/mkdocs/mkdocs

https://doc.1r1g.com/mkdocs/getting-started/

https://github.com/squidfunk/mkdocs-material

https://squidfunk.github.io/mkdocs-material/setup/

MkDocs是一个快速的、简单的、优美的静态站点生成器，主要用于构建项目文档。文档源文件采用Markdown格式，配置文件采用一个YAML格式文件。

mkdocs安装

安装mkdocs前需要安装python环境。

安装mkdocs非常简单，只需要在控制台运行如下命令即可：

pip install mkdocs

查看mkdocs是否安装成功，只需要运行如下命令：

mkdocs --version

创建一个项目

mkdocs new dir_name

在创建的目录下，有一个子目录docs，其中包含了源文件、页面等数据。

在创建的目录下，有一个文件mkdocs.yml，这就是配置文件。

生成文档

紧接着我们可以通过下面的命令生成文档

mkdocs build

如果之前的文档后后来的文档有较大的差别，也可以使用下面的命令，下面的命令会删除那些多余的文件

mkdocs build --clean

然后我们就能看到现在多了一个 site 文件夹，这个文件夹里面就是已经生成好的网站，现在我们有两种方法可以查看，一种是直接打开，还有一种可以通过在命令行里面输入

mkdocs serve

来打开一个动态的服务器，当文档内容发生改变的时候页面也会实时刷新，推荐使用这种方法。

Pydantic文档

地址

https://docs.pydantic.dev/latest/

在 Python 中写文档是一件很累的事情，有的时候写文档比写代码还要累，于是这个时候就有一个自动写文档的工具，就是 mkdocs，通过自动提取文章中的谷歌函数注释来达到对模块中的功能进行自动写文档的效果。

而大部分的文档都有点复古，直到我看到了 pydantic 的文档，我去了解一下才发现，这个是用 mkdocs 写出来的。

mkdocs 可以从代码中提取函数文档，模块文档，以及类文档，将他们按照你的要求展示出来，同时他还有很多扩展插件可以显示 mermaid 流程图，数据公式，另外这个 mkdocs 也可以拿来写博客。

安装

在开始写文档之前，需要安装 3 个库

mkdoc
- 主要的文档库核心
mkdocstrings[python]
- 负责从代码中提取文档
mkdocs-material
- 一个好看的代码主题

pip install mkdocs -U
pip install "mkdocstrings[python]" -U
pip install mkdocs-material -U

配置文件

现在我们需要一些已经写好的代码，现在把他们放到 src 文件夹下面

calc.py

"""This module provides some basic math functions.

该程序提供了一些基本的数学函数，包括加减乘除四则运算。

Example:
    >>> add(1, 2)
    3.0
    >>> subtract(1, 2)
    -1.0
    >>> multiply(1, 2)
    2.0
    >>> divide(1, 2)
    0.5
"""

from typing import TypeVar

T = TypeVar('T', int, float)


def add(a: T, b: T) -> float:
    """Add two numbers.

    Args:
        a (T): 第一个数
        b (T): 第二个数

    Returns:
        float: 两个数的和
    """
    return float(a + b)


def subtract(a: T, b: T) -> float:
    """Subtract two numbers.

    Args:
        a (T): 第一个数
        b (T): 第二个数

    Returns:
        float: 两个数的差
    """
    return float(a - b)


def multiply(a: T, b: T) -> float:
    """Multiply two numbers.

    Args:
        a (T): 第一个数
        b (T): 第二个数

    Returns:
        float: 两个数的积
    """
    return float(a * b)


def divide(a: T, b: T) -> float:
    """Divide two numbers.

    Args:
        a (T): 第一个数
        b (T): 第二个数

    Raises:
        ZeroDivisionError: 除数为0

    Returns:
        float: 两个数的商
    """
    if b == 0:
        raise ZeroDivisionError("division by zero")
    return float(a / b)

mkdocs 部分

创建 docs

在工程目录下(src 的父文件夹),输入下面的代码，如果已经有项目则不需要创建

mkdocs new ./

然后等待创建成功，如果创建成功可以看到目录里面多了一个 mkdocs.yml 文件和docs文件夹紧接着我们要配置这个文件。

配置 mkdocs.yml

site_name: My Docs

theme:
  name: "material"

plugins:
  - search:
      lang: en
  - mkdocstrings:
      handlers:
        python:
          paths: [/src]

然后build并启动项目。

注意：如果报错 accessing 'src' raises ModuleNotFoundError: No module named 'src'

解决方案：在src下创建个文件 exportPath.py

import sys
import os
# 把当前文件所在文件夹的父文件夹路径加入到PYTHONPATH
sys.path.append(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
print(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
print(os.path.dirname(os.path.abspath(__file__)))

# 检查Python的模块搜索路径
print(sys.path)