用MkDocs打造Python项目文档
原文：
towardsdatascience.com/documenting-python-projects-with-mkdocs-60e26b64380e
简介
项目文档是必要的。非常必要，我强调这一点。
在我的职业生涯初期，我艰难地意识到一个项目必须要有文档。
让我们回到 2000 年代——那时我作为大型美国公司的客户代表工作。我是团队的一员，我和我的同事几乎在同一个月加入公司。所以，有一段时间，我们不需要担心，因为没有人会在开始新工作几周或几个月后休假。
然而，过了一段时间，这种情况不可避免地会发生。我们都被分配去互相备份。那时，文档开始在我的职业生涯中扮演重要角色。
当第一个人休假几天时，我惊慌失措！我投入工作，不知道该做什么，甚至不知道从哪里开始。任务不断涌来，堆积如山，而我正在试图弄清楚如何处理它们。
最后，一切都很顺利。我设法弄明白了，并继续前进。但从那天起，我知道无论何时休假或团队变动，如晋升或离职，都需要有文档。
在这篇文章中，我们将学习如何使用 Python 中的mkdocs创建一个简单（且有效）的项目文档。最终结果将类似于MkDocs 文档。
构建文档
mkdocs是 Python 中的一个模块，允许我们使用 Markdown 语言创建简单的网页。好处是它高度可定制，给你的文档带来专业的外观，并且可以轻松地与 GitHub 集成。
此外，mkdocs利用 Markdown 标记语言，使用起来非常简单，它只是普通的文本，加上一些符号来指明标题、副标题、项目符号、斜体、粗体等。为了说明，Medium使用 Markdown 语言进行博客写作。
Markdown是一种轻量级标记语言，用于使用纯文本编辑器创建网页格式化的文本。
准备
我相信创建文档的最佳时机是在项目完成后。到那时，我们已经知道哪些模块被使用了，它是如何部署的，以及项目如何启动和维护。因此，是时候为用户记录这些步骤了。
当记录某事时，我的经验告诉我应该：
-
就像向一个完全的外行人描述如何运行项目一样来描述它。
-
尽量避免使用高度技术性的术语和公司中使用的缩写。
-
使用清晰简洁的语言描述每个步骤。
-
如果概念过于复杂，或者任务过于复杂，尝试将其分解成要点。
在开始编写文档之前，让我们快速创建一个示例项目，使用uv模块进行虚拟环境管理。在这里，我正在使用uv和 VSCode。
-
打开终端并使用
pip install uv安装uv -
创建一个名为“p2”的新项目：
uv init p2 -
更改目录以访问新文件夹：
cd p2 -
设置项目的 Python 版本：
pyenv local 3.12.1 -
创建一个新的虚拟环境：
uv venv --python 3.12.1 -
激活环境：
venv/Scripts/activate -
添加一些包：
uv add pandas, numpy, scikit-learn, streamlit
样本项目已创建。图片由作者提供。
入门
项目创建完成后，让我们添加mkdocs。
# Install mkdocs
uv add mkdocs
接下来，我们将创建一个新的文档文件夹。
# create a new documentation folder in your project
mkdocs new .
该命令将生成一个docs文件夹和文档所需的文件。
-
文件
mkdocs.yml：它用于配置你的文档网页，如标题、主题和网站结构，如添加新标签。 -
包含文件
index.md的docs文件夹：这是你将编写文档的地方。
文档文件夹。图片由作者提供。
如果我们想查看我们的文档，我们已经可以了。只需使用 serve 命令。
# Open a local server to display the docs
mkdocs serve
本地版本在 8000 端口运行。图片由作者提供。
现在，我们只需将 HTTP 复制粘贴到浏览器中（或 Ctrl + 点击）即可查看当前的文档状态。
MkDocs 文档“开箱即用”。图片由作者提供。
自定义
是时候自定义我们的文档了。
让我们从更改文档页面的标题开始。打开mkdocs.yml文件。你将只看到默认文件中的site_name标题。
mkdocs.yml 默认文件。图片由作者提供。
让我们更改它。
site_name: P2 Project Documentation
我们可以添加一个名为“关于”的新标签，其中包含有关项目的信息。为此，我们还需要在docs文件夹中添加一个 markdown 文件about.md。
site_name: P2 Project Documentation
nav:
- Home: index.md
- About: about.md
如果我们想更改主题，也可以。检查内置可用主题。或者可安装主题库。
site_name: P2 Project Documentation
nav:
- Home: index.md
- About: about.md
theme: mkdocs
到目前为止，这是结果。
Mkdocs 易于自定义。图片由作者提供。
接下来，让我们开始编写文档。这应该在docs文件夹内的 markdown 文件中完成。
我会将整个示例文档写入文件 index.md，项目元信息将放入文件 about.md。
- 文件 index.md
我们将擦除其中的示例文本，并写入我们的文档。
# P2 Project
This project is an example of how we can write a professional documentation using `mkdocs` module in Python.<br>
To learn MarkDown notation, use this [Cheatsheet](https://github.com/adam-p/markdown-here/wiki/Markdown-Here-Cheatsheet).
---
## Python Version
This project was built using **Python 3.12.1**
---
## Modules
* mkdocs >= 1.6.1
* numpy >= 2.1.3
* pandas >= 2.2.3
* scikit-learn >= 1.5.2
* seaborn >= 0.13.2
* streamlit >= 1.40.1
---
## Quick Start
To create a documentation with MkDocs, these are the main bash commands:
* Install mkdocs: `pip install mkdocs`
* Create a new documentation folder: `mkdocs new .`
* `mkdocs.yml` is the file to customize the web page, such as creating tabs, changing titles and themes.
* The files in the folder **docs** are the ones to hold the documentation text, using MarkDown notation.
- 文件 about.md
# About This Project
<br>
* **Author:** Your Name
* **Purpose:** Exemplify how to create a professional looking documentation for your projects using MarkDown notation in Python.
---
### Contact
Find me on [Linkedin](https://www.linkedin.com/in/profile)
最终结果是这个漂亮的文档网站。
最终的文档网站。图片由作者提供。
添加函数和文档字符串
MkDocs 还具有从代码中提取函数及其相应文档字符串的能力。为此，首先使用 pip install mkdocstrings-python 添加模块 MkDocstrings-Python。在我们的例子中，我使用 uv。
uv add mkdocstrings-python
接下来，调整 mkdocs.yml 文件以添加插件。将以下行添加到文件末尾并保存。
plugins:
- mkdocstrings:
default_handler: python
现在，让我们看看我们的代码。在这个示例项目中，我们只有一个包含两个函数的 hello.py 文件。
Python 文件中的函数。图片由作者提供。
将它们添加到文档中很简单。使用三个 ::: 后跟文件路径。由于此文件位于项目的根目录中，我们只需添加 file_name.function。如果它在文件夹内，可以使用类似 folder.file.function 的格式。
### Function
These are the functions used in the code `hello.py`
::: hello.main_func
::: hello.calculations
保存文件后，我们可以查看结果 mkdocs serve。
直接从 .py 文件中提取的函数。图片由作者提供。
现在让我们部署文档。
部署
部署我们的文档页面很简单。
首先，我们必须为项目创建一个 GitHub 页面，如果我们还没有的话。
接下来，回到 IDE 终端，我们将使用下一个命令构建我们的页面。此命令将创建部署文档网站所需的文件夹和文件。
mkdocs build
[OUT]:
INFO - Cleaning site directory
INFO - Building documentation to directory: C:MyDocumentstestesp2site
INFO - Documentation built in 0.06 seconds
现在，需要在 mkdocs.yml 文件中添加 GitHub 存储库，以便模块知道将文档部署到哪里。
在 mkdocs.yml 中添加存储库名称。图片由作者提供。
然后我们打开 Git Bash 终端以初始化 Git 并提交。
# Initialize Git
git init
# Add the reference repository
git remote add origin https://github.com/gurezende/MkDocs-Example.git
# Add files from the project
git add .
# Commit the files
git commit -m "Project Code and documentation"
# Create Branch Main
git branch -M main
# Push files to GitHub
git push -u origin main
然后我们可以使用以下 PowerShell 终端的 bash 代码来部署文档。
mkdocs gh-deploy
## Output ##
INFO - Cleaning site directory
INFO - Building documentation to directory: C:MyDocumentstestesp2site
INFO - Documentation built in 0.08 seconds
WARNING - Version check skipped: No version specified in previous deployment.
INFO - Copying 'C:MyDocumentstestesp2site' to 'gh-pages' branch and pushing to GitHub.
Enumerating objects: 39, done.
Counting objects: 100% (39/39), done.
Delta compression using up to 12 threads
Compressing objects: 100% (37/37), done.
Writing objects: 100% (39/39), 829.12 KiB | 11.68 MiB/s, done.
Total 39 (delta 2), reused 0 (delta 0), pack-reused 0
remote: Resolving deltas: 100% (2/2), done.
remote:
remote: Create a pull request for 'gh-pages' on GitHub by visiting:
remote: https://github.com/gurezende/MkDocs-Example/pull/new/gh-pages
remote:
To https://github.com/gurezende/MkDocs-Example.git
* [new branch] gh-pages -> gh-pages
INFO - Your documentation should shortly be available at: https://gurezende.github.io/MkDocs-Example/
注意，在最后一行，我们有文档部署的 URL。这个地址可以添加到你的 GitHub 读取文件中。
部署后，我们只需再次使用 Git Bash 终端的以下命令推送更新以更新 GitHub。
git add .
git commit -m "Online documentation added"
git push origin main
就这样！文档已上线！
从现在开始，每次我们更新项目中的 markdown 文件并命令 mkdocs gh-deploy，网页就会更新，我们的文档保持最新。就像这样简单！
项目的 GitHub 页面. 图片由作者提供。
在你离开之前
记录你的项目是很重要的。
最终，没有人知道你在开发某物时头脑中想的是什么。因此，记录就像展示你的思维过程，以及达到目的所使用的步骤。
打开你的心扉，向其他人展示你是如何创建这个产品以及如何使用它的。
MkDocs 使其变得非常简单，看起来超级专业。我确信它将极大地帮助你在工作中记录项目，帮助同事导航你的代码，以及积极影响从现在开始查看你的作品集的任何人。
如果你喜欢这个内容，请关注我获取更多。
GitHub 仓库
这里是这篇文章的 GitHub 仓库。
GitHub – gurezende/MkDocs-Example: 使用 mkdocs 为 Python 项目创建文档
了解更多
如果你想以视频形式查看这个内容，这里有一个来自我的 Gumroad 页面的产品。
扫一扫
1212
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
