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
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
Rename modules in `./scripts/modules/` to use an underscore prefix to
make it clear they aren't intended to be part of public API's. This
also means there is no implication that these modules should be stable,
allowing us to change them based on Blender's internal usage.
The following modules have been marked as private:
- `animsys_refactor`
- `bl_console_utils`
- `bl_i18n_utils`
- `bl_previews_utils`
- `bl_rna_utils`
- `bl_text_utils`
- `bl_ui_utils`
- `bpy_restrict_state`
- `console_python`
- `console_shell`
- `graphviz_export`
- `keyingsets_utils`
- `rna_info`
- `rna_manual_reference`
- `rna_xml`
Note that we could further re-arrange these modules
(under `_bpy_internal` in some cases), this change is mainly to mark
them as private, further changes can be handed on a case-by-case basis.
Ref !147773
Add a new section to the `Context` page that includes an explanation
on how to invoke "on demand" logging for context member access.
Design task: #144746
Logging added in: !144810
Ref !146862
The grid layout for UI lists wasn't used in practice from all we can
tell. It was badly maintained for a long time (bugs went unnoticed). I
think it was added for an earlier version of the asset UI design.
This was planned for removal in 5.0, see blender/blender#110461.
Usages in bundled scripts were already removed in efa8d942b8.
Pull Request: https://projects.blender.org/blender/blender/pulls/146656
"Use Nodes" was removed in the compositor to simplify the compositing
workflow. This introduced a slight inconsistency with the Shader Node
Editor.
This PR removes "Use Nodes" for object materials.
For Line Style, no changes are planned (not sure how to preserve
compatibility yet).
This simplifies the state of objects; either they have a material or
they don't.
Backward compatibility:
- If Use Nodes is turned Off, new nodes are added to the node tree to
simulate the same material:
- DNA: Only `use_nodes` is marked deprecated
- Python API:
- `material.use_nodes` is marked deprecated and will be removed in
6.0. Reading it always returns `True` and setting it has no effect.
- `material.diffuse_color`, `material.specular` etc.. Are not used by
EEVEE anymore but are kept because they are used by Workbench.
Forward compatibility:
Always enable 'Use Nodes' when writing blend files.
Known Issues:
Some UI tests are failing on macOS
Pull Request: https://projects.blender.org/blender/blender/pulls/141278
This makes the shader node inlining from #141936 available to external renderers
which use the Python API. Existing external renderer add-ons need to be updated
to get the inlined node tree from a material like below instead of using the
original node tree of the material directly.
The main contribution are these three methods: `Material.inline_shader_nodes()`,
`Light.inline_shader_nodes()` and `World.inline_shader_nodes()`.
In theory, there could be an inlining API for node trees more generally, but
some aspects of the inlining are specific to shader nodes currently. For example
the detection of output nodes and implicit input handling. Furthermore, having
the method on e.g. `Material` instead of on the node tree might be more future
proof for the case when we want to store input properties of the material on the
`Material` which are then passed into the shader node tree.
Example from API docs:
```python
import bpy
# The materials should be retrieved from the evaluated object to make sure that
# e.g. edits of Geometry Nodes are applied.
depsgraph = bpy.context.view_layer.depsgraph
ob = bpy.context.active_object
ob_eval = depsgraph.id_eval_get(ob)
material_eval = ob_eval.material_slots[0].material
# Compute the inlined shader nodes.
# Important: Do not loose the reference to this object while accessing the inlined
# node tree. Otherwise there will be a crash due to a dangling pointer.
inline_shader_nodes = material_eval.inline_shader_nodes()
# Get the actual inlined `bpy.types.NodeTree`.
tree = inline_shader_nodes.node_tree
for node in tree.nodes:
print(node.name)
```
Pull Request: https://projects.blender.org/blender/blender/pulls/145811
Fix several documentation related typos.
Found via `codespell -S "*.desktop,*.diff,./intern,./extern,./locale,./AUTHORS,./source/blender/blenlib/tests/BLI_string_utf8_test.cc,./doc/license/bf-members.txt" -L accessort,abd,aci,alo,ans,ba,bording,childrens,clen,constructin,datas,dependees,domin,eary,ege,eiter,elemt,eles,endianess,enew,espace,finded,fiter,fpt,groupd,hist,implementating,indext,ine,infront,inout,inouts,inpt,ist,lene,listenter,lod,maks,masia,mata,mis,mke,nam,nd,ned,opose,ot,outlow,parm,parms,passt,pinter,pixelx,poin,pres,ptd,re-usable,re-use,re-used,re-uses,re-using,ridiculus,schem,soler,strack,suh,te,tesselate,tham,ue,vai,varius,wew`
Pull Request: https://projects.blender.org/blender/blender/pulls/145824
Methods for `bpy_struct` such as `get()` & `items()` noted that only
some types support custom-properties.
Since these docs were written many more types support custom properties.
Replace the inline list with a link to a generated list since there are
now too many to include inline.
Resolves#141450.
Deprecation meta-data support for RNA properties.
- Properties may have a deprecated note and version.
- Warnings shown when these are accessed from Python.
- A note is included in the generated documentation.
Support for marking functions as deprecated can be added in the future.
Ref !139487
While this was an intentional change in [0],
it seemed like an error to removing quoting (based on #141853).
Restore the quotes while keeping the string literals.
[0]: 0fb80f698a
