• 代码文档

    为您的团队和您未来的自己代码文档。

    Intuition

    代码告诉你_怎么_做，注释告诉你_为什么_。——杰夫·阿特伍德

    可以通过代码文档来进一步组织代码，让其他人（以及未来的自己）更容易轻松地导航和扩展它。在完成编写代码库的那一刻就最了解代码库，但幸运的是，记录它将使能够快速回到熟悉的心态。文档对开发人员来说可能意味着很多不同的东西，所以让定义最常见的组件：

    • comments：关于为什么存在一段代码的简短描述。
    • typing：函数输入和输出数据类型的规范，提供与函数消耗和产生的内容有关的信息。
    • docstrings：对描述整体效用、参数、返回等的函数和类的有意义的描述。
    • docs：呈现的网页，总结了所有的功能、类、工作流程、示例等。

    目前，将在本地生成文档，但请务必查看应用程序的自动生成文档页面。每次对代码库进行更改时，将在CI/CD课程中学习如何自动创建文档并使其保持最新。

    代码协作

    您目前如何与团队中的其他人共享您的代码？有什么可以改进的？

    Typing

    对代码尽可能明确是很重要的。已经讨论过为变量、函数等选择显式名称，但可以显式的另一种方法是为函数的输入和输出定义类型。

    到目前为止，函数看起来像这样：

    def some_function(a, b):
        return c
    • 1

    但是可以使用打字来合并更多信息：

    from typing import List
    def some_function(a: List, b: int = 0) -> np.ndarray:
        return c
    • 1

    在这里定义了：

    • 输入参数 a是一个列表
    • 输入参数 b是一个整数，默认值为0
    • 输出参数 c是一个 NumPy 数组

    可以使用许多其他数据类型，包括List、Set、Dict、和更多Tuple，以及包含的类型，例如,等。您还可以使用安装的包（例如）甚至自己定义的包中的类型类（例如）。Sequenceint``float``np.ndarray``LabelEncoder

    从 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)
        ```
        

        [[1 2]
         [3 4]]
        


        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
    • 1

    让解压这个函数文档字符串的不同部分：

    • [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"):
        ...
    • 1

    理想情况下，会在开发函数和类时将文档字符串添加到它们中，而不是在最后一次完成。

    Tip

    如果使用Visual Studio Code，请务必使用Python Docstrings Generator扩展，这样您就可以"""在函数下键入，然后点击该Shift键生成模板文档字符串。它将使用输入信息甚至代码中的异常自动填充部分文档字符串！

    vscode 文档字符串生成
    vscode 文档字符串生成

    文档

    所以正在经历所有这些努力，将类型和文档字符串包括到函数中，但它们都隐藏在脚本中。如果可以收集所有这些努力并自动将其显示为文档会怎样？好吧，这正是将对以下开源包所做的 → 最终结果在这里。

    1. 安装所需的包：

      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"
      ]
      • 1

      然后将其添加到setup()脚本中的对象：

    # Define our package
    setup(
        ...
        install_requires=[required_packages],
        extras_require={
            "dev": docs_packages,
            "docs": docs_packages,
        },
    )
    • 1

    现在可以安装这个包：

    python3 -m pip install -e ".[docs]"

    还定义了一个dev选项，将在课程中更新该选项，以便开发人员可以在一次调用中安装所有必需的和额外的包，而不是一次调用每个额外的必需包。

    python3 -m pip install -e ".[dev]"

    创建了一个显式doc选项，因为用户只想下载文档包来生成文档（不需要其他包）。当使用CI/CD 工作流通过 GitHub Actions 自动生成文档时，将看到这一点。

    1. 初始化 mkdocs

      python3 -m mkdocs new .

      这将创建以下文件：

      .
      ├─ docs/
      │  └─ index.md
      └─ mkdocs.yml
      • 1

    2. 将首先用项目的特定信息 覆盖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)
      • 1

    3. 接下来将为目录中的每个脚本创建文档文件tagifai：

      mkdir docs/tagifai
      cd docs/tagifai
      touch main.md utils.md data.md train.md evaluate.md predict.md
      cd ../../
      • 1

    让docs目录结构尽可能模仿项目的结构是有帮助的。随着在以后的课程中记录更多目录，这一点变得更加重要。

    1. 接下来将添加tagifai.到docs/tagifai. tagifai/.py这将使用有关mkdocstrings插件的函数和类（使用它们的文档字符串）的信息填充文件。

      请务必查看mkdocs 插件的完整列表。

      # docs/tagifai/data.md
      ::: tagifai.data
      • 1

    2. 最后，将在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
      • 1

    3. 在本地提供文档：

      python3 -m mkdocs serve

    出版

    可以使用公共存储库的GitHub 页面以及私有存储库的私有文档轻松地免费提供文档。甚至可以将其托管在自定义域（例如公司的子域）上。

    请务必查看为应用程序自动生成的文档页面。每次对代码库进行更改时，将在CI/CD课程中学习如何自动创建文档并使文档保持最新。

    信息架构构建

    信息架构的逻辑呈现的 5 个过程

    图片
    图片

    本文主体源自以下链接：

    @article{madewithml,
        author       = {Goku Mohandas},
        title        = { Made With ML },
        howpublished = {\url{https://madewithml.com/}},
        year         = {2022}
    }
    • 1

    本文由 mdnice 多平台发布

  • 相关阅读:
    阿里面试官终于把Java八股文整理成册了，共计12w字，太全了
    带长度限制的最大子段和，无名一
    MYSQL之DCL
    Redis - 启动
    LeetCode 695. 岛屿的最大面积
    python淘宝商品数据抓取之后数据解析出错怎么办
    自己最好的canny实现（c#)
    通过QT管理网络状态和网络连接
    gunicorn参数说明英文及译文
    MySQL01
  • 原文地址：https://blog.csdn.net/hengfanz/article/details/128128554