Hvordan kan jeg dokumentere en modul i Python?

stemmer
47

Det er det. Hvis du ønsker å dokumentere en funksjon eller en klasse, legger du en streng like etter definisjonen. For eksempel:

def foo():
    This function does nothing.
    pass

Men hva om en modul? Hvordan kan jeg dokumentere hva en file.py gjør?

Publisert på 04/09/2008 klokken 16:06
kilden bruker
På andre språk...                            


6 svar

stemmer
40

For pakkene, kan du dokumentere det på __init__.py. For modulene, kan du legge til en docstring bare i modulen filen.

All informasjon er her: http://www.python.org/dev/peps/pep-0257/

Svarte 04/09/2008 kl. 16:12
kilden bruker

stemmer
34

Legg inn docstring som første setningen i modulen .

Siden jeg liker å se et eksempel:

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

import foo

# ...
Svarte 03/05/2014 kl. 23:29
kilden bruker

stemmer
11

Her er et eksempel google stil Python Docstrings om hvordan modulen kan dokumenteres. I utgangspunktet er det en informasjon om en modul, hvordan å kjøre den og informasjon om modulnivå variabler og liste over ToDo elementer.

"""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 
... 
...
Svarte 28/01/2017 kl. 19:34
kilden bruker

stemmer
7

Du gjør det på nøyaktig samme måte. Sett en streng i som den første setningen i modulen.

Svarte 04/09/2008 kl. 16:12
kilden bruker

stemmer
4

Det er enkelt, du bare legge et docstring på toppen av modulen.

Svarte 04/09/2008 kl. 16:12
kilden bruker

stemmer
0

For PyPI Pakker:

Hvis du legger doc strenger som dette i din __init__.py fil som vist nedenfor

"""
Please refer to the documentation provided in the README.md,
which can be found at gorpyter's PyPI URL: https://pypi.org/project/gorpyter/
"""

# <IMPORT_DEPENDENCIES>

def setup():
    """Verify your Python and R dependencies."""

Da vil du motta dette i daglige bruken av hjelpefunksjonen.

help(<YOUR_PACKAGE>)

DESCRIPTION
    Please refer to the documentation provided in the README.md,
    which can be found at gorpyter's PyPI URL: https://pypi.org/project/gorpyter/

PACKAGE CONTENTS


FUNCTIONS
    connect(project, api_key)
        Authenticate with your WXNC instance gateway.

    query(query, conn)
        Run a GOR query.

    setup()
        Verify your Python and R dependencies.

Merk at min hjelp DESCRIPTIONer utløst av å ha den første docstring på toppen av filen.

Svarte 16/08/2019 kl. 21:54
kilden bruker

Cookies help us deliver our services. By using our services, you agree to our use of cookies. Learn more