为您的团队和您未来的自己代码文档。
Intuition
代码告诉你_怎么_做，注释告诉你_为什么_。——杰夫·阿特伍德
可以通过代码文档来进一步组织代码，让其他人（以及未来的自己）更容易轻松地导航和扩展它。在完成编写代码库的那一刻就最了解代码库，但幸运的是，记录它将使能够快速回到熟悉的心态。文档对开发人员来说可能意味着很多不同的东西，所以让定义最常见的组件：
comments：关于为什么存在一段代码的简短描述。typing：函数输入和输出数据类型的规范，提供与函数消耗和产生的内容有关的信息。docstrings：对描述整体效用、参数、返回等的函数和类的有意义的描述。docs：呈现的网页，总结了所有的功能、类、工作流程、示例等。
目前，将在本地生成文档，但请务必查看应用程序的自动生成文档页面。每次对代码库进行更改时，将在CI/CD课程中学习如何自动创建文档并使其保持最新。
代码协作
您目前如何与团队中的其他人共享您的代码？有什么可以改进的？
Typing
对代码尽可能明确是很重要的。已经讨论过为变量、函数等选择显式名称，但可以显式的另一种方法是为函数的输入和输出定义类型。
到目前为止，函数看起来像这样：
def some_function(a, b):
return c
但是可以使用打字来合并更多信息：
from typing import List
def some_function(a: List, b: int = 0) -> np.ndarray:
return c
在这里定义了：
- 输入参数
a是一个列表 - 输入参数
b是一个整数，默认值为0 - 输出参数
c是一个 NumPy 数组
可以使用许多其他数据类型，包括List、Set、Dict、和更多Tuple，以及包含的类型，例如,等。您还可以使用安装的包（例如）甚至自己定义的包中的类型类（例如）。Sequenceintfloatnp.ndarrayLabelEncoder
从 Python 3.9+ 开始，内置了常用类型，因此不再需要导入它们
from typing import List, Set, Dict, Tuple, Sequence。
文档字符串
可以通过添加文档字符串来描述整体实用程序、参数、返回、异常等，从而使代码更加明确。让看一个例子：
from typing import List
def some_function(a: List, b: int = 0) -> np.ndarray:
"""Function description.
```python
c = some_function(a=[], b=0)
print (c)
```
<pre>
[[1 2]
[3 4]]
</pre>
Args:
a (List): description of `a`.
b (int, optional): description of `b`. Defaults to 0.
Raises:
ValueError: Input list is not one-dimensional.
Returns:
np.ndarray: Description of `c`.
"""
return c
让解压这个函数文档字符串的不同部分：
[Line 3]: 函数整体效用的总结。[Lines 5-12]: 如何使用功能的例子。[Lines 14-16]: 函数输入参数的描述。[Lines 18-19]：函数中可能引发的任何异常。[Lines 21-22]：函数输出的描述。
将在下面的文档部分呈现这些文档字符串以生成：
花时间用文档字符串更新项目中的所有函数和类，并确保参考存储库作为指南。请注意，您可能必须将某些库显式导入某些脚本，因为type需要它。例如，没有在data.py脚本中明确使用 Pandas 库，但是，确实使用 pandas 数据帧作为输入参数。
# tagifai/data.py
import pandas as pd
from typing import List
def replace_oos_labels(df: pd.DataFrame, labels: List, label_col: str, oos_label: str = "other"):
...
理想情况下，会在开发函数和类时将文档字符串添加到它们中，而不是在最后一次完成。
Tip
如果使用Visual Studio Code，请务必使用Python Docstrings Generator扩展，这样您就可以
"""在函数下键入，然后点击该Shift键生成模板文档字符串。它将使用输入信息甚至代码中的异常自动填充部分文档字符串！
文档
所以正在经历所有这些努力，将类型和文档字符串包括到函数中，但它们都隐藏在脚本中。如果可以收集所有这些努力并自动将其显示为文档会怎样？好吧，这正是将对以下开源包所做的 → 最终结果在这里。
-
安装所需的包：
pip install mkdocs==1.3.0 mkdocstrings==0.18.1不会将这些要求直接添加到
requirements.txt文件中，而是将其与所需的核心库隔离开来。想这样做是因为不是每个人都需要创建文档，因为它不是核心机器学习操作（训练、推理等）。将调整setup.py脚本来实现这一点。将在一个docs_packages对象下定义这些包：# setup.py docs_packages = [ "mkdocs==1.3.0", "mkdocstrings==0.18.1" ]然后将其添加到
setup()脚本中的对象：
# Define our package
setup(
...
install_requires=[required_packages],
extras_require={
"dev": docs_packages,
"docs": docs_packages,
},
)
现在可以安装这个包：
python3 -m pip install -e ".[docs]"
还定义了一个dev选项，将在课程中更新该选项，以便开发人员可以在一次调用中安装所有必需的和额外的包，而不是一次调用每个额外的必需包。
python3 -m pip install -e ".[dev]"
创建了一个显式doc选项，因为用户只想下载文档包来生成文档（不需要其他包）。当使用CI/CD 工作流通过 GitHub Actions 自动生成文档时，将看到这一点。
-
初始化 mkdocs
python3 -m mkdocs new .这将创建以下文件：
. ├─ docs/ │ └─ index.md └─ mkdocs.yml -
将首先用项目的特定信息 覆盖
index.md目录中的默认文件：docs## Documentation - [Workflows](tagifai/main.md): main workflows. - [tagifai](tagifai/data.md): documentation of functionality. ## MLOps Lessons Learn how to combine machine learning with software engineering to develop, deploy & maintain production ML applications. - Lessons: [https://madewithml.com/](https://madewithml.com/#mlops) - Code: [GokuMohandas/mlops-course](https://github.com/GokuMohandas/mlops-course) -
接下来将为目录中的每个脚本创建文档文件
tagifai：mkdir docs/tagifai cd docs/tagifai touch main.md utils.md data.md train.md evaluate.md predict.md cd ../../
让
docs目录结构尽可能模仿项目的结构是有帮助的。随着在以后的课程中记录更多目录，这一点变得更加重要。
-
接下来将添加
tagifai.<SCRIPT_NAME>到docs/tagifai.tagifai/<SCRIPT_NAME>.py这将使用有关mkdocstrings插件的函数和类（使用它们的文档字符串）的信息填充文件。请务必查看mkdocs 插件的完整列表。
# docs/tagifai/data.md ::: tagifai.data -
最后，将在
mkdocs.ymlmkdocs 自动创建的文件中添加一些配置：# mkdocs.yml site_name: Made With ML site_url: https://madewithml.com/ repo_url: https://github.com/GokuMohandas/mlops-course/ nav: - Home: index.md - workflows: - main: tagifai/main.md - tagifai: - data: tagifai/data.md - evaluate: tagifai/evaluate.md - predict: tagifai/predict.md - train: tagifai/train.md - utils: tagifai/utils.md theme: readthedocs plugins: - mkdocstrings watch: - . # reload docs for any file changes -
在本地提供文档：
python3 -m mkdocs serve
出版
可以使用公共存储库的GitHub 页面以及私有存储库的私有文档轻松地免费提供文档。甚至可以将其托管在自定义域（例如公司的子域）上。
请务必查看为应用程序自动生成的文档页面。每次对代码库进行更改时，将在CI/CD课程中学习如何自动创建文档并使文档保持最新。
信息架构构建
信息架构的逻辑呈现的 5 个过程
更多干货，第一时间更新在以下微信公众号：
您的一点点支持，是我后续更多的创造和贡献
转载到请包括本文地址 更详细的转载事宜请参考文章如何转载/引用
本文主体源自以下链接：
@article{madewithml,
author = {Goku Mohandas},
title = { Made With ML },
howpublished = {\url{https://madewithml.com/}},
year = {2022}
}
