文档和类型提示

pyglet文档写在 reStructuredText (RST)，并建造 Sphinx .如果您不熟悉reStructuredtext，它与MarkDown类似，但提供了更强大的创建技术文档的功能。这是Sphinx中使用的默认语言。大多数文档都是用纯语法编写的，因此您仍然可以修改或添加到其中，而不需要了解太多语法。

该文档可以作为pyglet存储库的一部分在 doc 子文件夹。主要指数位于 pyglet/doc/index.rst ，其中包括主着陆页，并定义了三个toctree：

  • 编程指南

  • API文档

  • 发展指南

编程指南

节目指南由许多个人组成 .rst 文件，位于 pyglet/doc/programming_guide/ 文件夹.此文件夹中的所有文件也在index.rst中定义，以便将它们包含在构建过程中。

API文档

API文档是由以下人员直接从源代码文档字符串生成的 autodoc ，Sphinx包含的插件扩展。生成本身大部分是自动的，但声明文件对于指示Sphinx如何以及应该包括哪些模块和类是必要的。查看现有文件 pyglet/doc/modules/ 来了解一下这是什么样子。

文档字符串规则

  • 无需打字的Google格式。

  • 文档字符串主要用于用户或一般信息，而不是实现详细信息。

  • 散列 (# ）当开发人员或贡献者需要向其他开发人员提供信息时，应使用评论。

  • 任何没有文档字符串的方法或函数都不会出现在API文档中。

  • 文档将隐藏私有属性，除非在rst中以其他方式重写。

  • 如果足够直接，则不需要参数描述，除非需要澄清。

  • 如果必须添加参数描述，则必须为该函数中的每个参数添加一个。(None或全部）

  • 返回描述是可选的。

  • 所有类和函数都应该有一个包含至少一行简洁描述的头。

  • 对于类属性，请使用 Attributes: 在标题中。可以指定类型提示，因为目前它们不会自动拾取。

    • 必需：您还需要添加这些 :exclude-members: <attribute> 手动在rst文件中。否则，autodoc将拾取它两次。

    • 类属性通常用于：

      1. 以某种形式改变班级的全局行为。（例如： Texture.default_mag_filter )

      2. 为用户简化子类别。（示例：Sprite的group_Class）

      3. 故障排除目的。

  • 为了清晰起见，参数描述应在新行中缩入。

  • 为了清楚起见，参数描述之间可以有一行空白。

  • 对于类实例属性，这些属性应该用#：comment记录下来<description>。

  • 对于您希望向文档隐藏的类实例属性。或者：

    1. 考虑将它们私有化（通过 _name ）如果有意义的话。

    2. 用以下格式的评论标记它们：#：：Meta private：

类型规则

  • 不要将类型信息放入文档字符串中，依赖注释。

  • 如果您正在使用类注释，则必须具有 from __future__ import annotations 位于模块的顶部。

  • 添加注释时，如果文件中未使用类类型，则必须仅在GROUP_CLARKING中导入

  • 没有必要太过分，如果还没有足够的方法，可以设置忽略一些规则。

  • 即使 None 。

示例

class Class1():
    """Short description of the class

    This is a good place for a general high level description
    of what the class is, and what it is used for. For example:
    Class1 is used for X and Y, which makes Z possible, etc.
    """

    #: This is the default thing.
    some_default_thing: float = 123.0

    #: :meta private:
    dont_show_me: int = 456

    def __init__(self, name: str, size: float):
        """Constructor description

        Here is where you can describe how to make an instance of the
        class. If any of the arguments need further explaination, that
        detail can be added as necessary. For example:
        You must provide a name and a size, etc. etc.

        Args:
            name: The name of this object.
            size: The size, in centimeters.
        """
        self.name = name
        self.size = size

        #: :This will show in the docs
        self.attribute_one: int = None

        self.attribute_two: str = "hello"

    def set_size(self, centimeters: float) -> None:
        """Simple description + type hints are enough."""
        self.size = centimeters

    def calculate_scaled_size(self, scale: float) -> float:
        """Detailed method description

        You can add more details here.

        Args:
            scale: The argument description.

        Returns:
            Describe what is being returned, if not already clear.
        """
        # This is a developer comment, which is not intended for end users to
        # see. These can be used to explain to future developers why something
        # is implemented a certain way, or any other developer focused notes, etc.
        return self.size * scale


def function_with_pep484_type_annotations(param1: int, param2: str) -> bool:
    """Example function with PEP 484 type annotations.

    Args:
        param1: The first parameter.
        param2: The second parameter.

    Returns:
       When necessary, you can describe the return value in
       more detail. This can be skipped if it's obvious from
       the return type hint.
    """
    ...

文档提示

有时您可能希望或不希望某些类属性显示在API文档中。根据放置注释和/或评论的方式以及放置位置，您可以控制文档构建期间拾取的内容。下面显示了一些例子。

以下内容将在没有文档字符串的文档中显示：：

class Test:
    blah: int

以下内容将显示在带有doc字符串的文档中：：

class Test:
    #: :My description.
    blah: int

以下内容不会显示在文档中：：

class Test:
    def __init__(self):
        self.blah: int = 0

以下内容将显示在文档中：：

class Test:
    def __init__(self):
        #: :This is documented.
        self.blah: int = 0

开发人员参考

以开发人员为中心的文档位于 pyglet/doc/internal/ 文件夹.其中包含有关用于开发pyglet的工具的各个页面、您现在正在阅读的文档页面、有关单元测试的信息等。这些页面对于任何想要贡献的人都很有用。

建筑

在本地构建文档需要一些依赖项。看到 开发环境 了解有关如何安装它们的更多信息。安装了Sphinx及其依赖项后，您就可以继续构建。第一种构建方法是使用pyglet的包含 make.py 效用它位于存储库的根中，并且包括一些用于常见构建和分发相关任务的帮助器函数。对于文档，执行：：

./make.py docs --open

如果构建成功，将打开浏览器窗口。您可以通过省略来跳过此内容 --open .生成的静态网页将在 doc/_build/html 。

您还可以使用Sphinx的构建文档 Makefile ：

cd pyglet/doc
make html       # Posix
make.bat html   # Windows

请注意，除了HTML之外还有其他构建目标，但它们可能需要安装其他依赖项。运行 make help 查看其中的列表：

$ make help
Please use `make <target>' where <target> is one of
html       to make standalone HTML files
dirhtml    to make HTML files named index.html in directories
singlehtml to make a single large HTML file
pickle     to make pickle files
json       to make JSON files
htmlhelp   to make HTML files and a HTML help project
qthelp     to make HTML files and a qthelp project
devhelp    to make HTML files and a Devhelp project
epub       to make an epub
latex      to make LaTeX files, you can set PAPER=a4 or PAPER=letter
latexpdf   to make LaTeX files and run them through pdflatex
text       to make text files
man        to make manual pages
texinfo    to make Texinfo files
info       to make Texinfo files and run them through makeinfo
gettext    to make PO message catalogs
changes    to make an overview of all changed/added/deprecated items
linkcheck  to check all external links for integrity
doctest    to run all doctests embedded in the documentation (if enabled)

自动生成的详细信息

日期

2024/07/13 22:42:56

pyglet版

2.0.16