Macro operator doc-strings didn't properly document the parameters
for the other operators that can be passed in.
Expose them as a dictionary since internally dictionaries are
coerced into OperatorProperties.
Array properties that don't map to a mathutils type (Vector, Matrix,
etc.) incorrectly used their element type (e.g. `float` / `int`).
- For function arguments use `Sequence[...]` since it will coerce
accepts any sequence type.
- Struct properties use `bpy_prop_array`, because they're a
Blender specific type which is mutable.
Move context member documentation into bpy.types.Context using rubric
headings to group by context area (Buttons, Screen, etc.).
Make bpy.context.rst a simple placeholder linking to bpy.types.Context,
matching the pattern used by bpy.data.rst.
Classmethod descriptors were not handled, causing methods in
bpy_extras.anim_utils and bpy_extras.asset_utils to be excluded
from documentation entirely.
- Rename "FAKE" to "PYCAPI" for non-RNA type constants, since these
are real C-API defined Python types, not "fake".
- Add USE_PYCAPI_TYPES flag, see code comments for details on the
two separate type hierarchies (`bpy_struct` & `bpy_prop`).
- Fix `bpy_prop` base class (was incorrectly set to `bpy_struct`).
- Collection wrapper structs (e.g. BlendDataObjects) now correctly
inherit from `bpy_prop_collection` instead of `bpy_struct`.
- Add bpy_prop as a documented fake class between bpy_struct and
bpy_prop_collection, matching the actual C type hierarchy.
- Show the base class in fake class signatures (e.g.
bpy_prop_collection(bpy_prop)) instead of only in the
"base classes" text.
Module-level GetSetDescriptorType entries (e.g. bpy.app.debug,
bpy.app.translations.locale) were incorrectly using '.. attribute::'
which is meant for class members. Use '.. data::' instead, matching
the Sphinx convention for module-level data.
sphinx_doc_gen.py:
- Add _PRIVATE_ATTR_INCLUDE so underscore-prefixed types can be
selectively included in API docs (needed to reference return values).
- Add :return:/:rtype: for operators.
- Fix context type entries (AnnotationLayer, FluidModifier, Curves).
bpy.props:
- Add :return:/:rtype: for property declaration functions.
gpu:
- Expose MatrixStackContext and OffScreenStackContext as documented
gpu.types so :rtype: references resolve.
bmesh.ops:
- Use Sequence[float] for vector input params.
- Add default_value for single-element BMO_OP_SLOT_ELEMENT_BUF slots.
bpy.types:
- Convert `tuple of X` to `tuple[X, ...]` and `list of X` to `list[X]`.
- Add :return:/:rtype: to Context.path_resolve and Operator.as_keywords.
- Fix Menu example link reference.
bpy_extras:
- Convert Python type annotations to :param:/:type:/:rtype:,
add missing doc-strings.
bpy.app.handlers:
- Add :type: with callable signatures.
- Fix depsgraph_update handler description
(the second argument is optional).
- Fix missing argument descriptions for render and undo/redo handlers.
bpy.context
- Use type hints for for property listing.
mathutils.kdtree:
- Fix doc-string syntax.
- Clarify that the size is an upper limit.
Various minor corrections to other modules.
Examples were supported with/without number suffix,
this caused problems using mypy for type checking because it attempted
to resolve imports such as `mathutils` to the example file.
Having only some examples numbered already complicated documentation
for conventions with examples - simplify extraction and number all.
Add a contribution guide for Blender's Python API documentation,
similar to the User Manual contribution guide.
Some parts of this process weren't so clear,
especially the example auto-discovery.
Cover:
- Setting up the build environment.
- Modifying API documentation.
- Adding example code snippets.
- File naming conventions and auto-discovery.
- Best practices and style guidelines.
PR !151750
Co-authored-by: Campbell Barton <campbell@blender.org>
Add an example with some notes on keymap usage, targeted at add-on
developers.
- Avoid pitfalls, add-on developers sometimes incorrectly modify user
keymaps directly, which persists after the add-on is disabled and
interferes with user preferences.
- Documents subtle/non-obvious requirements.
- Mention edge case regarding modal operator key-maps.
Ref !153111
Add hide_missing keyword argument to temp_override.logging_set().
This reduces noise from members that aren't available in the current
context while still showing members that exist but are empty.
- Add CTX_LogFlag enum with Access and HideMissing flags to control
context member logging behavior during temporary overrides.
- Store & restore original logging with a temporary context so each
context override properly stores & restores the logging options.
Ref !148760
Changes to example code introduced with db88381e75 contains a typo,
using `data block` instead of the standard `data-block`.
This changes ensures consistency with the spelling of `data-block` with
other API example files.
Pull Request: https://projects.blender.org/blender/blender/pulls/151850
- Mainly avoiding the `ui::UI_*` repetition, removing naming redundancy
- I skipped the "uiDefBut" style functions, those can be handled later
- "uiTemplate" functions are moved to snake case
- "GetThemeColor" functions are still not snake case, that's a next step
- I renamed "but" to "button" for one group of functions
Pull Request: https://projects.blender.org/blender/blender/pulls/151193
This patch standardizes ellipses on labels that require further input
from the user before running the operator as per our
HIG.
- PR does not include buttons (e.g. "Purge" in Outliner) and only
modifies menu items.
- PR does not include operators that wait for input from the user during
modal operation (e.g. `view3d.select_box`, `paint.sample_color`).
- Some usage of ellipses were removed since they were only present to
indicate the start of the sentence (to be finished by submenu items).
E.g. "Make Local...", "Sort Elements...", "Move..." do not require extra
input from the user.
Pull Request: https://projects.blender.org/blender/blender/pulls/150950
Sphinx CSS "hides" the _On this page_ pane by setting its `position` to `fixed` and `right` to `-15em`—this assumes it has a fixed `width` of `15em`, which it doesn't if it is overridden to `auto`.
Fixes#148347; caused by [45fee7d851][0], which also affects the 4.5 LTS docs.
[0]: 45fee7d851
Pull Request: https://projects.blender.org/blender/blender/pulls/148603
644fb2b679 fixed a long standing issue
that offscreen example showed the wrong colors. However the fix assumes
that input texture color space is always sRGB.
This adds a shader variation that draws textures that are stored in scene referred
linear color space (like all of our Image data-block).
Co-authored-by: Clément Foucault <foucault.clem@gmail.com>
Pull Request: https://projects.blender.org/blender/blender/pulls/147788
