示例来源

  1. """This is the docstring for the example.py module.  Modules names should
  2. have short, all-lowercase names.  The module name may have underscores if
  3. this improves readability.
  5. Every module should have a docstring at the very top of the file.  The
  6. module's docstring may extend over multiple lines.  If your docstring does
  7. extend over multiple lines, the closing three quotation marks must be on
  8. a line by itself, preferably preceded by a blank line.
  10. """
  11. from __future__ import division, absolute_import, print_function
  13. import os  # standard library imports first
  15. # Do NOT import using *, e.g. from numpy import *
  16. #
  17. # Import the module using
  18. #
  19. #   import numpy
  20. #
  21. # instead or import individual functions as needed, e.g
  22. #
  23. #  from numpy import array, zeros
  24. #
  25. # If you prefer the use of abbreviated module names, we suggest the
  26. # convention used by NumPy itself::
  28. import numpy as np
  29. import matplotlib as mpl
  30. import matplotlib.pyplot as plt
  32. # These abbreviated names are not to be used in docstrings; users must
  33. # be able to paste and execute docstrings after importing only the
  34. # numpy module itself, unabbreviated.
  37. def foo(var1, var2, long_var_name='hi'):
  38.     r"""A one-line summary that does not use variable names or the
  39.     function name.
  41.     Several sentences providing an extended description. Refer to
  42.     variables using back-ticks, e.g. `var`.
  44.     Parameters
  45.     ----------
  46.     var1 : array_like
  47.         Array_like means all those objects -- lists, nested lists, etc. --
  48.         that can be converted to an array.  We can also refer to
  49.         variables like `var1`.
  50.     var2 : int
  51.         The type above can either refer to an actual Python type
  52.         (e.g. ``int``), or describe the type of the variable in more
  53.         detail, e.g. ``(N,) ndarray`` or ``array_like``.
  54.     long_var_name : {'hi', 'ho'}, optional
  55.         Choices in brackets, default first when optional.
  57.     Returns
  58.     -------
  59.     type
  60.         Explanation of anonymous return value of type ``type``.
  61.     describe : type
  62.         Explanation of return value named `describe`.
  63.     out : type
  64.         Explanation of `out`.
  65.     type_without_description
  67.     Other Parameters
  68.     ----------------
  69.     only_seldom_used_keywords : type
  70.         Explanation
  71.     common_parameters_listed_above : type
  72.         Explanation
  74.     Raises
  75.     ------
  76.     BadException
  77.         Because you shouldn't have done that.
  79.     See Also
  80.     --------
  81.     otherfunc : relationship (optional)
  82.     newfunc : Relationship (optional), which could be fairly long, in which
  83.               case the line wraps here.
  84.     thirdfunc, fourthfunc, fifthfunc
  86.     Notes
  87.     -----
  88.     Notes about the implementation algorithm (if needed).
  90.     This can have multiple paragraphs.
  92.     You may include some math:
  94.     .. math:: X(e^{j\omega } ) = x(n)e^{ - j\omega n}
  96.     And even use a Greek symbol like :math:`\omega` inline.
  98.     References
  99.     ----------
  100.     Cite the relevant literature, e.g. [1]_.  You may also cite these
  101.     references in the notes section above.
  103.     .. [1] O. McNoleg, "The integration of GIS, remote sensing,
  104.        expert systems and adaptive co-kriging for environmental habitat
  105.        modelling of the Highland Haggis using object-oriented, fuzzy-logic
  106.        and neural-network techniques," Computers & Geosciences, vol. 22,
  107.        pp. 585-588, 1996.
  109.     Examples
  110.     --------
  111.     These are written in doctest format, and should illustrate how to
  112.     use the function.
  114.     >>> a = [1, 2, 3]
  115.     >>> print [x + 3 for x in a]
  116.     [4, 5, 6]
  117.     >>> print "a\n\nb"
  118.     a
  119.     b
  121.     """
  123.     pass