كيف أقوم بتوثيق وحدة في بايثون؟

Question

هذا كل شيء.إذا كنت ترغب في توثيق دالة أو فئة، يمكنك وضع سلسلة بعد التعريف مباشرة.على سبيل المثال:

def foo():
    """This function does nothing."""
    pass

ولكن ماذا عن الوحدة النمطية؟كيف يمكنني توثيق ما أ file.py يفعل؟

Answer 1

بالنسبة للحزم، يمكنك توثيقها في __init__.py.بالنسبة للوحدات، يمكنك إضافة سلسلة مستندية ببساطة في ملف الوحدة.

جميع المعلومات هنا: http://www.python.org/dev/peps/pep-0257/

Answer 2

أضف سلسلة المستندات الخاصة بك باسم البيان الأول في الوحدة.

"""
Your module's verbose yet thorough docstring.
"""

import foo

# ...

بالنسبة للحزم، يمكنك إضافة سلسلة المستندات الخاصة بك إلى __init__.py.

Answer 3

هنا مثال على مستندات Google Style Python حول كيفية توثيق الوحدة.توجد في الأساس معلومات حول الوحدة وكيفية تنفيذها ومعلومات حول متغيرات مستوى الوحدة وقائمة عناصر المهام.

"""Example Google style docstrings.

This module demonstrates documentation as specified by the `Google
Python Style Guide`_. Docstrings may extend over multiple lines.
Sections are created with a section header and a colon followed by a
block of indented text.

Example:
    Examples can be given using either the ``Example`` or ``Examples``
    sections. Sections support any reStructuredText formatting, including
    literal blocks::

        $ python example_google.py

Section breaks are created by resuming unindented text. Section breaks
are also implicitly created anytime a new section starts.

Attributes:
    module_level_variable1 (int): Module level variables may be documented in
        either the ``Attributes`` section of the module docstring, or in an
        inline docstring immediately following the variable.

        Either form is acceptable, but the two should not be mixed. Choose
        one convention to document module level variables and be consistent
        with it.

Todo:
    * For module TODOs
    * You have to also use ``sphinx.ext.todo`` extension

.. _Google Python Style Guide:   
http://google.github.io/styleguide/pyguide.html

"""

module_level_variable1 = 12345

def my_function():   
    pass 
... 
...

Answer 4

أنت تفعل ذلك بنفس الطريقة بالضبط.ضع سلسلة كالبيان الأول في الوحدة.

Answer 5

إنه أمر سهل، ما عليك سوى إضافة سلسلة مستندية في الجزء العلوي من الوحدة.