mirror of
https://github.com/blender/blender
synced 2026-09-29 04:37:17 +03:00
PyDoc: use :param: instead of :arg: in Sphinx docstrings
While "arg" isn't deprecated "param" is preferred and used in all Sphinx's examples & tutorials. Ref !154039
This commit is contained in:
Campbell Barton
parent
40298aa015
commit
791505e2ed
96 changed files with 1131 additions and 1120 deletions
|
|
@ -45,10 +45,10 @@ def abspath(path, *, start=None, library=None):
|
|||
Returns the absolute path relative to the current blend file
|
||||
using the "//" prefix.
|
||||
|
||||
:arg start: Relative to this path,
|
||||
:param start: Relative to this path,
|
||||
when not set the current filename is used.
|
||||
:type start: str | bytes
|
||||
:arg library: The library this path is from. This is only included for
|
||||
:param 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.
|
||||
|
|
@ -82,9 +82,9 @@ def relpath(path, *, start=None):
|
|||
"""
|
||||
Returns the path relative to the current blend file using the "//" prefix.
|
||||
|
||||
:arg path: An absolute path.
|
||||
:param path: An absolute path.
|
||||
:type path: str | bytes
|
||||
:arg start: Relative to this path,
|
||||
:param start: Relative to this path,
|
||||
when not set the current filename is used.
|
||||
:type start: str | bytes
|
||||
:return: The relative path.
|
||||
|
|
@ -109,7 +109,7 @@ def is_subdir(path, directory):
|
|||
Returns true if *path* in a subdirectory of *directory*.
|
||||
Both paths must be absolute.
|
||||
|
||||
:arg path: An absolute path.
|
||||
:param path: An absolute path.
|
||||
:type path: str | bytes
|
||||
:return: Whether or not the path is a subdirectory.
|
||||
:rtype: bool
|
||||
|
|
@ -133,9 +133,9 @@ def clean_name(name, *, replace="_"):
|
|||
All characters besides A-Z/a-z, 0-9 are replaced with "_"
|
||||
or the *replace* argument if defined.
|
||||
|
||||
:arg name: The path name.
|
||||
:param name: The path name.
|
||||
:type name: str | bytes
|
||||
:arg replace: The replacement for non-valid characters.
|
||||
:param replace: The replacement for non-valid characters.
|
||||
:type replace: str
|
||||
:return: The cleaned name.
|
||||
:rtype: str
|
||||
|
|
@ -205,11 +205,11 @@ 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 name: The name to be used for displaying the user interface.
|
||||
:param name: The name to be used for displaying the user interface.
|
||||
:type name: str
|
||||
:arg has_ext: Remove file extension from name.
|
||||
:param has_ext: Remove file extension from name.
|
||||
:type has_ext: bool
|
||||
:arg title_case: Convert lowercase names to title case.
|
||||
:param title_case: Convert lowercase names to title case.
|
||||
:type title_case: bool
|
||||
:return: The display string.
|
||||
:rtype: str
|
||||
|
|
@ -238,7 +238,7 @@ 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.
|
||||
:param name: The display name to convert.
|
||||
:type name: str
|
||||
:return: The file path.
|
||||
:rtype: str
|
||||
|
|
@ -253,7 +253,7 @@ 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.
|
||||
:param name: The file path to convert.
|
||||
:type name: str
|
||||
:return: The display name.
|
||||
:rtype: str
|
||||
|
|
@ -269,7 +269,7 @@ 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.
|
||||
:param path: The path name to resolve.
|
||||
:type path: str
|
||||
:return: The resolved path.
|
||||
:rtype: str
|
||||
|
|
@ -334,12 +334,12 @@ 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.
|
||||
:param filepath: The file path.
|
||||
:type filepath: str
|
||||
:arg ext: The extension to check for, can be a compound extension. Should
|
||||
:param ext: The extension to check for, can be a compound extension. Should
|
||||
start with a dot, such as ``.blend`` or ``.tar.gz``.
|
||||
:type ext: str
|
||||
:arg case_sensitive: Check for matching case when comparing extensions.
|
||||
:param case_sensitive: Check for matching case when comparing extensions.
|
||||
:type case_sensitive: bool
|
||||
:return: The file path with the given extension.
|
||||
:rtype: str
|
||||
|
|
@ -359,11 +359,11 @@ def module_names(path, *, recursive=False, package=""):
|
|||
"""
|
||||
Return a list of modules which can be imported from *path*.
|
||||
|
||||
:arg path: a directory to scan.
|
||||
:param path: a directory to scan.
|
||||
:type path: str
|
||||
:arg recursive: Also return submodule names for packages.
|
||||
:param recursive: Also return submodule names for packages.
|
||||
:type recursive: bool
|
||||
:arg package: Optional string, used as the prefix for module names (without the trailing ".").
|
||||
:param package: Optional string, used as the prefix for module names (without the trailing ".").
|
||||
:type package: str
|
||||
:return: a list of string pairs (module_name, module_file).
|
||||
:rtype: list[tuple[str, str]]
|
||||
|
|
@ -413,7 +413,7 @@ def native_pathsep(path):
|
|||
"""
|
||||
Replace the path separator with the systems native ``os.sep``.
|
||||
|
||||
:arg path: The path to replace.
|
||||
:param path: The path to replace.
|
||||
:type path: str
|
||||
:return: The path with system native separators.
|
||||
:rtype: str
|
||||
|
|
@ -442,7 +442,7 @@ def reduce_dirs(dirs):
|
|||
any directories nested in one of the other paths.
|
||||
(Useful for recursive path searching).
|
||||
|
||||
:arg dirs: Sequence of directory paths.
|
||||
:param dirs: Sequence of directory paths.
|
||||
:type dirs: Sequence[str]
|
||||
:return: A unique list of paths.
|
||||
:rtype: list[str]
|
||||
|
|
|
|||
|
|
@ -92,9 +92,9 @@ def execfile(filepath, *, mod=None):
|
|||
"""
|
||||
Execute a file path as a Python script.
|
||||
|
||||
:arg filepath: Path of the script to execute.
|
||||
:param filepath: Path of the script to execute.
|
||||
:type filepath: str
|
||||
:arg mod: Optional cached module, the result of a previous execution.
|
||||
:param mod: Optional cached module, the result of a previous execution.
|
||||
:type mod: ModuleType | None
|
||||
:return: The module which can be passed back in as ``mod``.
|
||||
:rtype: ModuleType
|
||||
|
|
@ -178,9 +178,9 @@ def modules_from_path(path, loaded_modules):
|
|||
"""
|
||||
Load all modules in a path and return them as a list.
|
||||
|
||||
:arg path: this path is scanned for scripts and packages.
|
||||
:param path: this path is scanned for scripts and packages.
|
||||
:type path: str
|
||||
:arg loaded_modules: already loaded module names, files matching these
|
||||
:param loaded_modules: already loaded module names, files matching these
|
||||
names will be ignored.
|
||||
:type loaded_modules: set[ModuleType]
|
||||
:return: all loaded modules.
|
||||
|
|
@ -232,13 +232,13 @@ def load_scripts(*, reload_scripts=False, refresh_scripts=False, extensions=True
|
|||
"""
|
||||
Load scripts and run each modules register function.
|
||||
|
||||
:arg reload_scripts: Causes all scripts to have their unregister method
|
||||
:param reload_scripts: Causes all scripts to have their unregister method
|
||||
called before loading.
|
||||
:type reload_scripts: bool
|
||||
:arg refresh_scripts: only load scripts which are not already loaded
|
||||
:param refresh_scripts: only load scripts which are not already loaded
|
||||
as modules.
|
||||
:type refresh_scripts: bool
|
||||
:arg extensions: Loads additional scripts (add-ons & app-templates).
|
||||
:param extensions: Loads additional scripts (add-ons & app-templates).
|
||||
:type extensions: bool
|
||||
"""
|
||||
use_time = use_class_register_check = _bpy.app.debug_python
|
||||
|
|
@ -380,7 +380,7 @@ def load_scripts_extensions(*, reload_scripts=False):
|
|||
"""
|
||||
Load extensions scripts (add-ons and app-templates)
|
||||
|
||||
:arg reload_scripts: Causes all scripts to have their unregister method
|
||||
:param reload_scripts: Causes all scripts to have their unregister method
|
||||
called before loading.
|
||||
:type reload_scripts: bool
|
||||
"""
|
||||
|
|
@ -428,15 +428,15 @@ def script_paths(*, subdir=None, user_pref=True, check_all=False, use_user=True,
|
|||
"""
|
||||
Returns a list of valid script paths.
|
||||
|
||||
:arg subdir: Optional subdir.
|
||||
:param subdir: Optional subdir.
|
||||
:type subdir: str
|
||||
:arg user_pref: Include the user preference script paths.
|
||||
:param user_pref: Include the user preference script paths.
|
||||
:type user_pref: bool
|
||||
:arg check_all: Include local, user and system paths rather just the paths Blender uses.
|
||||
:param check_all: Include local, user and system paths rather just the paths Blender uses.
|
||||
:type check_all: bool
|
||||
:arg use_user: Include user paths
|
||||
:param use_user: Include user paths
|
||||
:type use_user: bool
|
||||
:arg use_system_environment: Include BLENDER_SYSTEM_SCRIPTS variable path
|
||||
:param use_system_environment: Include BLENDER_SYSTEM_SCRIPTS variable path
|
||||
:type use_system_environment: bool
|
||||
:return: script paths.
|
||||
:rtype: list[str]
|
||||
|
|
@ -519,7 +519,7 @@ def app_template_paths(*, path=None):
|
|||
"""
|
||||
Returns valid application template paths.
|
||||
|
||||
:arg path: Optional subdir.
|
||||
:param path: Optional subdir.
|
||||
:type path: str
|
||||
:return: App template paths.
|
||||
:rtype: Iterator[str]
|
||||
|
|
@ -547,7 +547,7 @@ def preset_paths(subdir):
|
|||
"""
|
||||
Returns a list of paths for a specific preset.
|
||||
|
||||
:arg subdir: preset subdirectory (must not be an absolute path).
|
||||
:param subdir: preset subdirectory (must not be an absolute path).
|
||||
:type subdir: str
|
||||
:return: Script paths.
|
||||
:rtype: list[str]
|
||||
|
|
@ -578,7 +578,7 @@ def register_preset_path(path):
|
|||
"""
|
||||
Register a preset search path.
|
||||
|
||||
:arg path: preset directory (must be an absolute path).
|
||||
:param path: preset directory (must be an absolute path).
|
||||
|
||||
This path must contain a "presets" subdirectory which will typically contain presets for add-ons.
|
||||
|
||||
|
|
@ -602,7 +602,7 @@ def unregister_preset_path(path):
|
|||
"""
|
||||
Unregister a preset search path.
|
||||
|
||||
:arg path: preset directory (must be an absolute path).
|
||||
:param path: preset directory (must be an absolute path).
|
||||
|
||||
This must match the registered path exactly.
|
||||
:type path: str
|
||||
|
|
@ -646,7 +646,7 @@ def is_path_builtin(path):
|
|||
"""
|
||||
Returns True if the path is one of the built-in paths used by Blender.
|
||||
|
||||
:arg path: Path you want to check if it is in the built-in settings directory
|
||||
:param path: Path you want to check if it is in the built-in settings directory
|
||||
:type path: str
|
||||
:rtype: bool
|
||||
"""
|
||||
|
|
@ -674,7 +674,7 @@ def is_path_extension(path):
|
|||
"""
|
||||
Returns True if the path is from an extensions repository.
|
||||
|
||||
:arg path: Path to check if it is within an extension repository.
|
||||
:param path: Path to check if it is within an extension repository.
|
||||
:type path: str
|
||||
:rtype: bool
|
||||
"""
|
||||
|
|
@ -696,7 +696,7 @@ def smpte_from_seconds(time, *, fps=None, fps_base=None):
|
|||
|
||||
If *fps* and *fps_base* are not given the current scene is used.
|
||||
|
||||
:arg time: time in seconds.
|
||||
:param time: time in seconds.
|
||||
:type time: int | float | datetime.timedelta
|
||||
:return: the frame string.
|
||||
:rtype: str
|
||||
|
|
@ -716,7 +716,7 @@ def smpte_from_frame(frame, *, fps=None, fps_base=None):
|
|||
|
||||
If *fps* and *fps_base* are not given the current scene is used.
|
||||
|
||||
:arg frame: frame number.
|
||||
:param frame: frame number.
|
||||
:type frame: int | float
|
||||
:return: the frame string.
|
||||
:rtype: str
|
||||
|
|
@ -749,7 +749,7 @@ def time_from_frame(frame, *, fps=None, fps_base=None):
|
|||
|
||||
If *fps* and *fps_base* are not given the current scene is used.
|
||||
|
||||
:arg frame: number.
|
||||
:param frame: number.
|
||||
:type frame: int | float
|
||||
:return: the time in seconds.
|
||||
:rtype: datetime.timedelta
|
||||
|
|
@ -775,7 +775,7 @@ def time_to_frame(time, *, fps=None, fps_base=None):
|
|||
|
||||
If *fps* and *fps_base* are not given the current scene is used.
|
||||
|
||||
:arg time: time in seconds.
|
||||
:param time: time in seconds.
|
||||
:type time: float | int | datetime.timedelta
|
||||
:return: The frame.
|
||||
:rtype: float | int | datetime.timedelta
|
||||
|
|
@ -878,11 +878,11 @@ def user_resource(resource_type, *, path="", create=False):
|
|||
"""
|
||||
Return a user resource path (normally from the users home directory).
|
||||
|
||||
:arg resource_type: Resource type in ['DATAFILES', 'CONFIG', 'SCRIPTS', 'EXTENSIONS'].
|
||||
:param resource_type: Resource type in ['DATAFILES', 'CONFIG', 'SCRIPTS', 'EXTENSIONS'].
|
||||
:type resource_type: str
|
||||
:arg path: Optional subdirectory.
|
||||
:param path: Optional subdirectory.
|
||||
:type path: str
|
||||
:arg create: Treat the path as a directory and create it if its not existing.
|
||||
:param create: Treat the path as a directory and create it if its not existing.
|
||||
:type create: bool
|
||||
:return: a path.
|
||||
:rtype: str
|
||||
|
|
@ -920,11 +920,11 @@ def extension_path_user(package, *, path="", create=False):
|
|||
because it is cleared each upgrade and the users may not have write permissions
|
||||
to the repository (typically "System" repositories).
|
||||
|
||||
:arg package: The ``__package__`` of the extension.
|
||||
:param package: The ``__package__`` of the extension.
|
||||
:type package: str
|
||||
:arg path: Optional subdirectory.
|
||||
:param path: Optional subdirectory.
|
||||
:type path: str
|
||||
:arg create: Treat the path as a directory and create it if its not existing.
|
||||
:param create: Treat the path as a directory and create it if its not existing.
|
||||
:type create: bool
|
||||
:return: a path.
|
||||
:rtype: str
|
||||
|
|
@ -962,7 +962,7 @@ def register_classes_factory(classes):
|
|||
Utility function to create register and unregister functions
|
||||
which simply registers and unregisters a sequence of classes.
|
||||
|
||||
:arg classes: Sequence of classes to register and unregister.
|
||||
:param classes: Sequence of classes to register and unregister.
|
||||
:type classes: Sequence[type]
|
||||
:return: register and unregister functions.
|
||||
:rtype: tuple[Callable[[], None], Callable[[], None]]
|
||||
|
|
@ -989,9 +989,9 @@ def register_submodule_factory(module_name, submodule_names):
|
|||
Modules are registered in the order given,
|
||||
unregistered in reverse order.
|
||||
|
||||
:arg module_name: The module name, typically ``__name__``.
|
||||
:param module_name: The module name, typically ``__name__``.
|
||||
:type module_name: str
|
||||
:arg submodule_names: List of submodule names to load and unload.
|
||||
:param submodule_names: List of submodule names to load and unload.
|
||||
:type submodule_names: list[str]
|
||||
:return: register and unregister functions.
|
||||
:rtype: tuple[Callable[[], None], Callable[[], None]]
|
||||
|
|
@ -1026,13 +1026,13 @@ def register_tool(tool_cls, *, after=None, separator=False, group=False):
|
|||
"""
|
||||
Register a tool in the toolbar.
|
||||
|
||||
:arg tool_cls: A tool subclass.
|
||||
:param tool_cls: A tool subclass.
|
||||
:type tool_cls: type[:class:`bpy.types.WorkSpaceTool`]
|
||||
:arg after: Optional identifiers this tool will be added after.
|
||||
:param after: Optional identifiers this tool will be added after.
|
||||
:type after: Sequence[str] | set[str] | None
|
||||
:arg separator: When true, add a separator before this tool.
|
||||
:param separator: When true, add a separator before this tool.
|
||||
:type separator: bool
|
||||
:arg group: When true, add a new nested group of tools.
|
||||
:param group: When true, add a new nested group of tools.
|
||||
:type group: bool
|
||||
"""
|
||||
space_type = tool_cls.bl_space_type
|
||||
|
|
@ -1341,11 +1341,11 @@ def make_rna_paths(struct_name, prop_name, enum_name):
|
|||
"""
|
||||
Create RNA "paths" from given names.
|
||||
|
||||
:arg struct_name: Name of a RNA struct (like e.g. "Scene").
|
||||
:param struct_name: Name of a RNA struct (like e.g. "Scene").
|
||||
:type struct_name: str
|
||||
:arg prop_name: Name of a RNA struct's property.
|
||||
:param prop_name: Name of a RNA struct's property.
|
||||
:type prop_name: str
|
||||
:arg enum_name: Name of a RNA enum identifier.
|
||||
:param enum_name: Name of a RNA enum identifier.
|
||||
:type enum_name: str
|
||||
:return: A triple of three "RNA paths"
|
||||
(most_complete_path, "struct.prop", "struct.prop:'enum'").
|
||||
|
|
|
|||
|
|
@ -118,7 +118,7 @@ def remove(pcoll):
|
|||
"""
|
||||
Remove the specified previews collection.
|
||||
|
||||
:arg pcoll: Preview collection to close.
|
||||
:param pcoll: Preview collection to close.
|
||||
:type pcoll: :class:`ImagePreviewCollection`
|
||||
"""
|
||||
pcoll.close()
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue