5. Python代码和项目文档

老罗iot

共 3490字，需浏览 7分钟

· 2022-01-06

为什么需要记录Python代码？项目文档应该包括什么？如何编写和生成文档？

文档是软件开发的重要组成部分。如果没有适当的文档，内部和外部利益相关者可能很难或不可能使用或维护我们的代码。这也使得新加入的开发人员变得更加困难。甚至自己也看不懂自己写下的代码。

1 注释 vs 文档

文档是一个独立的资源，可以帮助其他人使用我们的API、程序包、库或框架等，而无需阅读源代码。而注释是供阅读源代码的开发人员使用的。文档应该告诉其他人：

什么时候用
怎么用

而注释应该告诉其他人：

这是啥？
这个函数做了什么？
为什么这样做？等。

2 Docstrings

Python的docstring是一种特殊的字符串，它作为模块、函数、类或方法定义中的第一条语句出现，形成给定对象的__doc__属性。它使您可以将文档直接嵌入到源代码中：

"""
The temperature module: Manipulate your temperature easily

Easily calculate daily average temperature
"""

from typing import List


class HighTemperature:
    """Class representing very high temperatures"""

    def __init__(self, value: float):
        """
        :param value: value of temperature
        """

        self.value = value


def daily_average(temperatures: List[float]) -> float:
    """
    Get average daily temperature

    Calculate average temperature from multiple measurements

    :param temperatures: list of temperatures
    :return: average temperature
    """

    return sum(temperatures) / len(temperatures)

我们可以看到daily_average的__doc__属性：

>>> from temperature import daily_average
>>>
>>> print(daily_average.__doc__)

    Get average daily temperature

    :param temperatures: list of temperatures
    :return: average temperature

我们可以用内置的help查看更详细的信息：

>>> import temperature
>>>
>>> help(temperature)

我们可以通过docstrings指定：

函数参数
函数返回
类属性
异常
边界或限制
示例代码等

比较流行的文档风格：

Google[1]
reStructuredText[2]
Numpy[3]
Epytext[4]

选择一种适合自己的文档风格，或者自定义一种属于自己的风格，使我们的项目更清晰。

3 Sphinx

将docstrings添加到代码中是很棒的，但是仍然需要将它呈现给用户。

这时就是Sphinx，Epydoc和MKDocs等工具发挥作用的时候了，这些工具会将项目的文档字符串转换为HTML和CSS。

Sphinx是迄今为止最受欢迎的。它被用于为许多开源项目生成文档（例如Python和Flask）。它也是Read the Docs支持的文档工具之一，仅举几例，它被数千个开源项目使用（如Requests，Flake8和pytest等）。

没安装的可以使用pip安装，一起看看怎么用：

$ sphinx-quickstart --version

sphinx-quickstart 3.5.4

在我们项目文件夹下新建一个temperature.py,添加上文提到的代码，然后运行：

$ sphinx-quickstart docs

> Separate source and build directories (y/n) [n]: n
> Project name: Temperature
> Author name(s): JKL
> Project release []: 1.0.0
> Project language [en]: en

这将会生成docs文件夹以及文件夹下面的一些文件。

更改docs/source/conf.py，将以下代码：

# import os
# import sys
# sys.path.insert(0, os.path.abspath('.'))

改为：

import os
import sys
sys.path.insert(0, os.path.abspath('../..'))

在extensions列表添加：

extensions = [
    'sphinx.ext.autodoc',
]

修改docs/source/index.rst：

.. Temperature documentation master file, created by
   sphinx-quickstart on Sat Apr 24 14:11:59 2021.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

Welcome to Temperature's documentation!
=======================================

.. toctree::
   :maxdepth: 2
   :caption: Contents:

.. automodule:: temperature
      :members:


Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`