From 62d64bec2a9c14c5d1515350cfc6b524118058c2 Mon Sep 17 00:00:00 2001 From: Xavier Cho Date: Fri, 22 Oct 2021 18:27:03 -0400 Subject: Docs: Fixes and improvements in API documentation Fixes several notable mistakes and missing information regarding the API documentation (*.rst). This will allow API stub generators like bpystubgen or fake-bpy-module to produce more accurate result. Differential Revision: https://developer.blender.org/D12639 --- extern/audaspace/bindings/python/PySound.cpp | 2 +- release/scripts/modules/bpy/path.py | 52 ++++++++++++++++++++--- source/blender/python/generic/bl_math_py_api.c | 22 +++++----- source/blender/python/gpu/gpu_py_texture.c | 2 +- source/blender/python/intern/bpy_rna.c | 4 +- source/blender/python/mathutils/mathutils_noise.c | 2 +- 6 files changed, 62 insertions(+), 22 deletions(-) diff --git a/extern/audaspace/bindings/python/PySound.cpp b/extern/audaspace/bindings/python/PySound.cpp index 2236057e7d2..1f149482914 100644 --- a/extern/audaspace/bindings/python/PySound.cpp +++ b/extern/audaspace/bindings/python/PySound.cpp @@ -290,7 +290,7 @@ PyDoc_STRVAR(M_aud_Sound_buffer_doc, ".. classmethod:: buffer(data, rate)\n\n" " Creates a sound from a data buffer.\n\n" " :arg data: The data as two dimensional numpy array.\n" - " :type data: numpy.ndarray\n" + " :type data: :class:`numpy.ndarray`\n" " :arg rate: The sample rate.\n" " :type rate: double\n" " :return: The created :class:`Sound` object.\n" diff --git a/release/scripts/modules/bpy/path.py b/release/scripts/modules/bpy/path.py index 30f93d051e5..37bdb939c07 100644 --- a/release/scripts/modules/bpy/path.py +++ b/release/scripts/modules/bpy/path.py @@ -67,6 +67,8 @@ def abspath(path, *, start=None, library=None): :arg library: The library this path is from. This is only included for convenience, when the library is not None its path replaces *start*. :type library: :class:`bpy.types.Library` + :return: The absolute path. + :rtype: string """ if isinstance(path, bytes): if path.startswith(b"//"): @@ -101,6 +103,8 @@ def relpath(path, *, start=None): :arg start: Relative to this path, when not set the current filename is used. :type start: string or bytes + :return: The relative path. + :rtype: string """ if isinstance(path, bytes): if not path.startswith(b"//"): @@ -123,6 +127,8 @@ def is_subdir(path, directory): :arg path: An absolute path. :type path: string or bytes + :return: Whether or not the path is a subdirectory. + :rtype: boolean """ from os.path import normpath, normcase, sep path = normpath(normcase(path)) @@ -141,6 +147,12 @@ def clean_name(name, *, replace="_"): such as writing to a file. All characters besides A-Z/a-z, 0-9 are replaced with "_" or the *replace* argument if defined. + :arg name: The path name. + :type name: string or bytes + :arg replace: The replacement for non-valid characters. + :type replace: string + :return: The cleaned name. + :rtype: string """ if replace != "_": @@ -207,8 +219,14 @@ def display_name(name, *, has_ext=True, title_case=True): Creates a display string from name to be used menus and the user interface. Intended for use with filenames and module names. - :arg has_ext: Remove file extension from name - :arg title_case: Convert lowercase names to title case + :arg name: The name to be used for displaying the user interface. + :type name: string + :arg has_ext: Remove file extension from name. + :type has_ext: boolean + :arg title_case: Convert lowercase names to title case. + :type title_case: boolean + :return: The display string. + :rtype: string """ if has_ext: @@ -233,6 +251,10 @@ def display_name_to_filepath(name): """ Performs the reverse of display_name using literal versions of characters which aren't supported in a filepath. + :arg name: The display name to convert. + :type name: string + :return: The file path. + :rtype: string """ for disp_value, file_value in _display_name_literals.items(): name = name.replace(disp_value, file_value) @@ -243,6 +265,10 @@ def display_name_from_filepath(name): """ Returns the path stripped of directory and extension, ensured to be utf8 compatible. + :arg name: The file path to convert. + :type name: string + :return: The display name. + :rtype: string """ name = _os.path.splitext(basename(name))[0] @@ -254,6 +280,10 @@ def resolve_ncase(path): """ Resolve a case insensitive path on a case sensitive system, returning a string with the path if found else return the original path. + :arg path: The path name to resolve. + :type path: string + :return: The resolved path. + :rtype: string """ def _ncase_path_found(path): @@ -315,11 +345,15 @@ def ensure_ext(filepath, ext, *, case_sensitive=False): """ Return the path with the extension added if it is not already set. + :arg filepath: The file path. + :type filepath: string :arg ext: The extension to check for, can be a compound extension. Should start with a dot, such as '.blend' or '.tar.gz'. :type ext: string :arg case_sensitive: Check for matching case when comparing extensions. - :type case_sensitive: bool + :type case_sensitive: boolean + :return: The file path with the given extension. + :rtype: string """ if case_sensitive: @@ -341,7 +375,7 @@ def module_names(path, *, recursive=False): :arg recursive: Also return submodule names for packages. :type recursive: bool :return: a list of string pairs (module_name, module_file). - :rtype: list + :rtype: list of strings """ from os.path import join, isfile @@ -374,6 +408,8 @@ def basename(path): Equivalent to ``os.path.basename``, but skips a "//" prefix. Use for Windows compatibility. + :return: The base name of the given path. + :rtype: string """ return _os.path.basename(path[2:] if path[:2] in {"//", b"//"} else path) @@ -381,6 +417,10 @@ def basename(path): def native_pathsep(path): """ Replace the path separator with the systems native ``os.sep``. + :arg path: The path to replace. + :type path: string + :return: The path with system native separators. + :rtype: string """ if type(path) is str: if _os.sep == "/": @@ -407,9 +447,9 @@ def reduce_dirs(dirs): (Useful for recursive path searching). :arg dirs: Sequence of directory paths. - :type dirs: sequence + :type dirs: sequence of strings :return: A unique list of paths. - :rtype: list + :rtype: list of strings """ dirs = list({_os.path.normpath(_os.path.abspath(d)) for d in dirs}) dirs.sort(key=lambda d: len(d)) diff --git a/source/blender/python/generic/bl_math_py_api.c b/source/blender/python/generic/bl_math_py_api.c index f17aaa4ca5d..5e938db0c35 100644 --- a/source/blender/python/generic/bl_math_py_api.c +++ b/source/blender/python/generic/bl_math_py_api.c @@ -77,14 +77,14 @@ static PyObject *py_bl_math_clamp(PyObject *UNUSED(self), PyObject *args) } PyDoc_STRVAR(py_bl_math_lerp_doc, - ".. function:: lerp(from, to, factor)\n" + ".. function:: lerp(from_value, to_value, factor)\n" "\n" " Linearly interpolate between two float values based on factor.\n" "\n" - " :arg from: The value to return when factor is 0.\n" - " :type from: float\n" - " :arg to: The value to return when factor is 1.\n" - " :type to: float\n" + " :arg from_value: The value to return when factor is 0.\n" + " :type from_value: float\n" + " :arg to_value: The value to return when factor is 1.\n" + " :type to_value: float\n" " :arg factor: The interpolation value, normally in [0.0, 1.0].\n" " :type factor: float\n" " :return: The interpolated value.\n" @@ -101,15 +101,15 @@ static PyObject *py_bl_math_lerp(PyObject *UNUSED(self), PyObject *args) PyDoc_STRVAR( py_bl_math_smoothstep_doc, - ".. function:: smoothstep(from, to, value)\n" + ".. function:: smoothstep(from_value, to_value, value)\n" "\n" - " Performs smooth interpolation between 0 and 1 as value changes between from and to.\n" + " Performs smooth interpolation between 0 and 1 as value changes between from and to values.\n" " Outside the range the function returns the same value as the nearest edge.\n" "\n" - " :arg from: The edge value where the result is 0.\n" - " :type from: float\n" - " :arg to: The edge value where the result is 1.\n" - " :type to: float\n" + " :arg from_value: The edge value where the result is 0.\n" + " :type from_value: float\n" + " :arg to_value: The edge value where the result is 1.\n" + " :type to_value: float\n" " :arg factor: The interpolation value.\n" " :type factor: float\n" " :return: The interpolated value in [0.0, 1.0].\n" diff --git a/source/blender/python/gpu/gpu_py_texture.c b/source/blender/python/gpu/gpu_py_texture.c index 5d136921300..c034c31d828 100644 --- a/source/blender/python/gpu/gpu_py_texture.c +++ b/source/blender/python/gpu/gpu_py_texture.c @@ -536,7 +536,7 @@ PyDoc_STRVAR(pygpu_texture_from_image_doc, "premultiplied or straight alpha matching the image alpha mode.\n" "\n" " :arg image: The Image datablock.\n" - " :type image: `bpy.types.Image`\n" + " :type image: :class:`bpy.types.Image`\n" " :return: The GPUTexture used by the image.\n" " :rtype: :class:`gpu.types.GPUTexture`\n"); static PyObject *pygpu_texture_from_image(PyObject *UNUSED(self), PyObject *arg) diff --git a/source/blender/python/intern/bpy_rna.c b/source/blender/python/intern/bpy_rna.c index 1296a6c174c..7b1877f3191 100644 --- a/source/blender/python/intern/bpy_rna.c +++ b/source/blender/python/intern/bpy_rna.c @@ -8786,7 +8786,7 @@ void pyrna_free_types(void) * - Should still be fixed - Campbell */ PyDoc_STRVAR(pyrna_register_class_doc, - ".. method:: register_class(cls)\n" + ".. function:: register_class(cls)\n" "\n" " Register a subclass of a Blender type class.\n" "\n" @@ -8971,7 +8971,7 @@ static int pyrna_srna_contains_pointer_prop_srna(StructRNA *srna_props, } PyDoc_STRVAR(pyrna_unregister_class_doc, - ".. method:: unregister_class(cls)\n" + ".. function:: unregister_class(cls)\n" "\n" " Unload the Python class from blender.\n" "\n" diff --git a/source/blender/python/mathutils/mathutils_noise.c b/source/blender/python/mathutils/mathutils_noise.c index 69d37b345c6..d5e27496af8 100644 --- a/source/blender/python/mathutils/mathutils_noise.c +++ b/source/blender/python/mathutils/mathutils_noise.c @@ -562,7 +562,7 @@ PyDoc_STRVAR(M_Noise_turbulence_vector_doc, " :type octaves: int\n" " :arg hard: Specifies whether returned turbulence is hard (sharp transitions) or " "soft (smooth transitions).\n" - " :type hard: :boolean\n" BPY_NOISE_BASIS_ENUM_DOC + " :type hard: boolean\n" BPY_NOISE_BASIS_ENUM_DOC " :arg amplitude_scale: The amplitude scaling factor.\n" " :type amplitude_scale: float\n" " :arg frequency_scale: The frequency scaling factor\n" -- cgit v1.2.3