.gitignore

@@ -13,6 +13,7 @@ __pycache__/
 # Varius extensions
 *.log
 *.tmp
+*.DS_Store
 
 # Sphinx documentation
 build/

Makefile

@@ -7,7 +7,8 @@ Custom Targets
 
 Convenience targets provided for building docs.
 
-- livehtml (default)   to auto build on file changes on host on localhost.
+- html (default)       to build HTML documentation.
+- livehtml             to auto build HTML on file changes on host on localhost.
 - epubpdf              to convert an epub file to PDF.
 
 Translations

build_files/.htaccess

@@ -241,3 +241,28 @@ RedirectMatch "^/manual/{lang}/{version}/modeling/geometry_nodes/volume/volume_c
 RedirectMatch "^/manual/{lang}/{version}/editors/nla/editing.html" "^/manual/{lang}/{version}/editors/nla/editing/index.html"
 
 RedirectMatch "^/manual/{lang}/{version}/render/shader_nodes/shader/anisotropic.html" "^/manual/{lang}/{version}/render/shader_nodes/shader/glossy.html"
+
+RedirectMatch "^/manual/{lang}/{version}/files/import_export.html" "^/manual/{lang}/{version}/files/import_export/index.html"
+
+RedirectMatch "^/manual/{lang}/{version}/render/eevee/light_probes/introduction.html" "^/manual/{lang}/{version}/render/eevee/light_probes/index.html"
+RedirectMatch "^/manual/{lang}/{version}/movie_clip/introduction.html" "^/manual/{lang}/{version}/movie_clip/index.html"
+RedirectMatch "^/manual/{lang}/{version}/getting_started/about/introduction.html" "^/manual/{lang}/{version}/getting_started/about/index.html"
+RedirectMatch "^/manual/{lang}/{version}/animation/armatures/bones/properties/introduction.html" "^/manual/{lang}/{version}/animation/armatures/bones/properties/index.html"
+RedirectMatch "^/manual/{lang}/{version}/advanced/command_line/introduction.html" "^/manual/{lang}/{version}/advanced/command_line/index.html"
+
+RedirectMatch "^/manual/{lang}/{version}/modeling/geometry_nodes/utilities/rotation/align_euler_to_vector.html" "^/manual/{lang}/{version}/modeling/geometry_nodes/utilities/rotation/align_rotation_to_vector.html"
+
+RedirectMatch "^/manual/{lang}/{version}/modeling/modifiers/modify/normal_edit.html" "^/manual/{lang}/{version}/modeling/modifiers/normals/normal_edit.html"
+RedirectMatch "^/manual/{lang}/{version}/modeling/modifiers/modify/weighted_normal.html" "^/manual/{lang}/{version}/modeling/modifiers/normals/weighted_normal.html"
+
+RedirectMatch "^/manual/{lang}/{version}/sculpt_paint/brush/brush.html" "^/manual/{lang}/{version}/sculpt_paint/brush/introduction.html"
+RedirectMatch "^/manual/{lang}/{version}/sculpt_paint/sculpting/tools/rotate.html" "^/manual/{lang}/{version}/sculpt_paint/sculpting/brushes/twist.html"
+RedirectMatch "^/manual/{lang}/{version}/sculpt_paint/sculpting/tools/simplify.html" "^/manual/{lang}/{version}/sculpt_paint/sculpting/brushes/density.html"
+# Mesh sculpting tools converted to asset
+RedirectMatch "^/manual/{lang}/{version}/sculpt_paint/sculpting/tools/(blob|boundary|clay|clay_strips|clay_thumb|cloth|crease|draw|draw_facesets|draw_sharp|elastic_deform|fill|flatten|grab|inflate|layer|mask|multiplane_scrape|multires_displacement_eraser|multires_displacement_smear|nudge|paint|pinch|pose|scrape|slide_relax|smear|smooth|snake_hook|thumb).html" "^/manual/{lang}/{version}/sculpt_paint/sculpting/brushes/$1.html"
+# Curve sculpting tools converted to asset
+RedirectMatch "^/manual/{lang}/{version}/sculpt_paint/curves_sculpting/tools/(index|add_curves|comb_curves|delete_curves|density_curves|grow_shrink_curves|pinch_curves|puff_curves|selection_paint|slide_curves|smooth_curves|snake_hook_curves).html" "^/manual/{lang}/{version}/sculpt_paint/curves_sculpting/brushes/$1.html"
+# Grease pencil draw tools
+RedirectMatch "^/manual/{lang}/{version}/grease_pencil/modes/draw/tools/(draw|erase|fill|tint).html" "^/manual/{lang}/{version}/sculpt_paint/curves_sculpting/brushes/$1.html"
+# Texture paint tools converted to asset
+RedirectMatch "^/manual/{lang}/{version}/sculpt_paint/texture_paint/tools.html" "^/manual/{lang}/{version}/sculpt_paint/texture_paint/brushes.html"

build_files/theme/css/theme_overrides.css

@@ -13,6 +13,7 @@
 	--admonition-font-size: var(--font-size--normal);
 	--admonition-title-font-size: var(--font-size--normal);
 	--color-api-name: #e87d0d;
+	--color-brand-visited: var(--color-brand-content) !important;
 }
 
 h1,

manual/addons/index.rst

@@ -27,4 +27,5 @@ Add-ons Category Listings
    animation/index.rst
    import_export/index.rst
    node/index.rst
+   rigging/index.rst
    system/index.rst

manual/addons/rigging/index.rst

@@ -0,0 +1,11 @@
+
+###########
+  Rigging
+###########
+
+These add-ons relate to rigging and armatures.
+
+.. toctree::
+   :maxdepth: 1
+
+   rigify/index.rst

manual/addons/rigging/rigify/basics.rst

@@ -0,0 +1,276 @@
+
+***********
+Basic Usage
+***********
+
+.. _bpy.ops.pose.rigify_generate:
+
+Basic Rig Generation
+====================
+
+#. Add a meta-rig structure from the :menuselection:`Add --> Armature` menu.
+#. Edit the bone positions to match the character geometry.
+#. In the armature properties click on the *Generate Rig* button to generate the rig.
+
+
+Add a Predefined Meta-Rig
+-------------------------
+
+.. reference::
+
+   :Mode:      Object Mode
+   :Menu:      :menuselection:`Add --> Armature`
+   :Shortcut:  :kbd:`Shift-A`
+
+Rigify stores all the information required to generate complex rig controls and mechanism in
+more simple armatures called "meta-rigs".
+
+The predefined meta-rigs can be found in the *Add* menu.
+Currently available meta-rig types are:
+
+- Basic Human (doesn't include face and fingers)
+- Basic Quadruped
+- Human
+- Cat
+- Wolf
+- Horse
+- Shark
+
+
+Edit Bone Positions
+-------------------
+
+To correctly match your character, meta-rig bones must be moved to correct positions.
+This can be achieved in two different ways: Pose Mode or Edit Mode.
+
+.. note::
+
+   Rigify assumes that 1 unit corresponds to 1 meter. So a human is about 2 units tall.
+   If your character is in a different scale and you are more familiar with modeling rather than rigging,
+   it is suggested to scale it to Rigify dimensions before positioning the meta-rig bones.
+   If you want to scale the character's geometry, we suggest you to first scale up the character in Object Mode,
+   then apply the geometry scale with the *Apply Scale* tool.
+
+
+Rigify Human Alignment Tips
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+- Limbs: Keep the legs as straight as possible in the front view (Rigify human works better in predictable cases).
+  Give the knee and the elbow a slight bend angle (Rigify needs to know where your knee/elbow is pointing).
+- Torso: Keep the spine as straight as possible in the front view (Rigify human works better in predictable cases).
+  The last bone of the spine is the head. By default the next two bones (top to bottom)
+  are considered the neck bones. It is suggested to keep the neck bones as aligned as possible while editing.
+- Face: Positioning face bones can be tricky if you are not an expert in bone editing and
+  they are almost useless if you plan to make facial animation through shape keys.
+  Consider removing face features from your character if they aren't really needed.
+  If you don't need the face all the face bones can be deleted.
+  All the face bones are in the *Face* armature bone collection by default.
+  You can select them by displaying only that collection, selecting all of its content and
+  then deleting the bones in Edit Mode to correctly remove the face.
+
+  If you want to scale all the face bones at once, consider scaling the face master bone
+  in Pose Mode (see Pose Mode matching method).
+  The face master bone is placed in the same position of the head bone.
+  To select it easily, hide all other bone collections.
+
+  For more tips, see the :doc:`Positioning Guide </addons/rigging/rigify/bone_positioning>`.
+
+
+Pose Mode Matching (Basic)
+--------------------------
+
+Enter the meta-rig Pose Mode. Rotate, scale, and translate the bones in the correct position.
+When bones are in correct positions (always staying in Pose Mode)
+use :menuselection:`Apply --> Apply Pose As Rest Pose`.
+
+.. note::
+
+   Connected bones cannot be translated in Pose Mode.
+   You can scale the parent bones to match the general length and then refine child bones scale.
+   For more detailed information on armature modes please refer to
+   the :doc:`armatures section </animation/armatures/bones/editing/introduction>`.
+
+
+Edit Mode Matching (Advanced)
+-----------------------------
+
+Some basic armature display setup is suggested before entering bone Edit Mode.
+
+With the meta-rig selected, go in the Properties and click on the Object tab.
+Scroll down to the display panel and enable X-ray and under *Maximum Draw Type* selector select *Wire*.
+This way the bones will always be drawn in wireframe on top of your geometry.
+
+Then, always in the Properties click on the Armatures tab and under display check the *Axis* checkbox.
+This way you the bones rotation axes will be displayed during the edit process.
+
+For more detailed information on armature display modes please refer to
+the :doc:`Display panel page </animation/armatures/properties/display>`.
+
+
+Generating the Rig
+------------------
+
+With the bones in the correct positions, jump back in Object Mode, go to the Armature tab,
+scroll down to the bottom and click on the *Generate Rig* button to finalize the rig creation.
+The generation process will take from few seconds to one minute depending on
+rig complexity and hardware specifications of your machine.
+If the generated rig needs tweaking, you can modify the meta-rig accordingly and
+then click again on the generate button. If the rig already exists,
+Rigify will simply overwrite it retaining all your modifiers and constraints and -- where possible --
+all the previously generated features.
+
+For information about additional generation options, see the `Advanced Rig Generation`_ section.
+
+.. tip::
+
+   If the metarig uses the legacy :doc:`face rig <./rig_types/faces>`, you can use the
+   *Upgrade Face Rig* button that appears above *Generate Rig* to automatically upgrade
+   to the new modular face system.
+
+   The upgrade will preserve compatibility with existing skinning, but existing poses and
+   animations will likely not be compatible due to subtle changes in control behavior.
+
+.. note::
+
+   To make the rig overwriting work as expected, you need to have **both** the rig and
+   the meta-rig visible before generating again. Rigify will try to unhide them in simple
+   cases, but will abort generation if that fails.
+
+.. warning::
+
+   As with all Python add-ons, Blender interface cannot be updated until the Python script execution is over.
+   Wait until the rig appears to see the results.
+
+.. warning::
+   Rigify is designed assuming a workflow where the meta-rig is kept available to allow re-generating
+   the main rig whenever it is necessary to make changes to it. Removing the meta-rig after generating
+   the main rig, or significantly modifying the generated rig is not advised: it will make it impossible
+   to introduce features added in later versions of Rigify, or easily adapt it to breaking changes in later
+   Blender versions. In general, automatic version update scripts will be provided for meta-rigs when necessary,
+   but not generated rigs.
+
+
+Binding the Geometry to the Rig
+-------------------------------
+
+To bind the geometry to the rig you can use your preferred tools. Just few things you have to know:
+
+- All the deforming bones are in the *DEF* bone collection.
+- Eyes and Teeth bones of the legacy face are not deforming. You are supposed to bind the eyes and
+  teeth geometry through Child Of constraints.
+- Usually armature deform with automatic weights do a really good job out of the box
+  if you correctly place your bones (and there is enough topology to work with!).
+
+For more detailed information on bone collections, Armature modifier and weight painting refer to the Blender manual.
+
+
+.. _bpy.types.Armature.rigify:
+
+Advanced Rig Generation
+=======================
+
+Advanced Options Features
+-------------------------
+
+By using options in the Advanced sub-panel, it is possible to:
+
+- Generate more than one rig per scene.
+- Update/Override a specific rig.
+- Force previously generated widget objects to be overwritten.
+- Choose whether to use linked duplicates for left and right side widgets.
+- Execute a script data-block after generation.
+
+Advanced Options Sub-Panel
+--------------------------
+
+.. figure:: /images/addons_rigging_rigify_basics_advanced-panel.png
+   :align: right
+   :width: 300px
+
+Advanced rig generation options are by default hidden in a sub-panel. Click on the *Advanced* line to open it.
+
+Some of the options will be automatically set by Rigify if they have no value when a rig is generated,
+while others are fully controlled by the user.
+
+Rig Name
+   When a brand new rig is generated, as opposed to overwriting an existing one, the value of this option
+   is used to name it.
+
+   If this field is empty, the new object will be named based on the name of the metarig according
+   to the following rules:
+
+   * If the name contains ``META``, it is replaced with ``RIG``.
+   * If the name contains ``metarig``, it is replaced with ``rig``.
+   * Otherwise, ``RIG-`` is prepended to the name.
+
+   When overwriting an existing rig object specified by the *Target Rig* option, its name is not changed,
+   allowing it to be freely renamed without having to keep the value of this option in sync.
+
+Target Rig :guilabel:`auto`
+   This option specifies the generated rig to overwrite when re-generating from this metarig.
+
+   If the option is not set, Rigify will generate a new rig object and store it in this option.
+
+   .. note::
+
+      When the option isn't set, Rigify will create a brand new rig object even if an object
+      with a matching name already exists.
+
+Rig UI Script :guilabel:`auto`
+   This option specifies the generated script datablock to overwrite when re-generating, and
+   works in the same manner as *Target Rig*.
+
+   The script controls the UI in the 3D Viewport that allows conveniently switching visible
+   bone collections, changing custom properties, converting between IK and FK and so on.
+
+Widgets Collection :guilabel:`auto`
+   This reference specifies the collection containing generated widgets, and
+   works in the same manner as *Target Rig*.
+
+Overwrite Widget Meshes
+   If enabled, Rigify will generate new widgets every time the rig is re-generated. By default,
+   it tries to reuse the already generated widget objects that exist in the widget collection,
+   allowing them to be manually edited to fit the character better.
+
+Mirror Widgets
+   When enabled, Rigify generates widgets for left and right side bones as
+   linked duplicates, using negative X scale to flip the right side version.
+   This enforces symmetry and reduces the number of meshes to adjust to
+   fit the character.
+
+   When reusing an already generated widget, Rigify detects if it was originally generated mirrored
+   by checking object scale to avoid flipping existing controls. Therefore switching to mirrored
+   widgets for an existing character requires deleting the right side widgets, or *Force Widget Update*.
+
+Run Script
+   It is possible to configure Rigify to execute a Python script contained in a text data-block
+   after generation in order to apply user-defined customizations. The script is executed with
+   the generated rig active and selected in Object Mode.
+
+   The simplest use of this may be adjusting properties of generated constraints when Rigify rig types
+   don't have any relevant meta-rig settings. That can be done by using the *Copy Full Data Path*
+   context menu option on the property, pasting it into the script and making an assignment, e.g.::
+
+      import bpy
+
+      bpy.data.objects["rig"].pose.bones["MCH-spine.003"].constraints[0].influence = 0.6
+
+   Doing such changes via a script ensures they aren't lost if the rig is re-generated.
+
+   Users familiar with `Rigify scripting <https://developer.blender.org/docs/features/animation/rigify/>`__
+   can import Rigify utility modules, and access the generator instance through ``rigify.get_generator()``.
+   Yet note that, since generation is already finished, the only use of that is reading data created
+   in the generation process.
+
+
+Library Linking
+===============
+
+When linking a rig into another file, you generally want to create a collection that includes
+the generated rig and the character mesh. You do not need to include the meta-rig or the widget
+object collection. You then link in the collection and run
+:ref:`Make Library Override <bpy.ops.object.make_override_library>`.
+
+The ``rig_ui_template.py`` text data-block responsible for the rig UI
+will be automatically linked along with the rig, you don't need to link it separately.
+However, the script will not run until you run it manually from the Text editor or save and restart Blender.

manual/addons/rigging/rigify/bone_positioning.rst

@@ -0,0 +1,220 @@
+
+**********************
+Bone Positioning Guide
+**********************
+
+Face Bones
+==========
+
+Start by identifying basic face landmarks to follow as guide for bones placement.
+
+.. figure:: /images/addons_rigging_rigify_bone-positioning_face-landmarks.png
+   :align: center
+
+   Basic Face Landmarks.
+
+- Orange lines represent bones that should be placed in closed loops.
+- Yellow lines represent bones whose position depends on surrounding bone loops.
+- Red lines represent outer edge bones.
+- Purple lines represent bridging bones used to cover deforming flesh.
+
+.. figure:: /images/addons_rigging_rigify_bone-positioning_face-eyes-nose-landmarks.png
+   :align: center
+
+   Eyes-Nose Landmarks.
+
+The eyes-nose loop area is split in different parts identified by bone names. Follow the image to place the bones.
+
+.. figure:: /images/addons_rigging_rigify_bone-positioning_face-eyes-nose-bones.png
+   :align: center
+
+   Eyes-Nose Bone Positions.
+
+.. tip:: Brow Placement
+
+   Keeping aligned the mid bones in "brow", "brow.b", "lid.t", "lid.t" and
+   cheek will give better results after rig generation.
+
+.. figure:: /images/addons_rigging_rigify_bone-positioning_face-jaw-ear-bones.png
+   :align: center
+
+   Jaw-Ear Bone Positions.
+
+Also the jaw-ear area is split in different parts identified by bone names. Follow the image to place the bones.
+
+.. tip:: Jaw Placement
+
+   Try to place "ear.L" bone covering the part of the ear attached to the mandible (lower jaw).
+   Do the same with temple bone trying to cover the part you don't want to move with the jaw,
+   this way you will also determine the jaw pivot position.
+
+.. figure:: /images/addons_rigging_rigify_bone-positioning_face-lips-merge-point.png
+   :align: center
+
+   Lips Merge Point.
+
+.. warning::
+
+   While moving the face bones it is necessary to preserve merge points, i.e. whenever heads
+   or tails of two or more bones overlap at the same point, they should still do so after
+   repositioning. Tearing a merge point apart may result in multiple controls being created
+   instead of one, or even the generation of errors.
+
+.. figure:: /images/addons_rigging_rigify_bone-positioning_face-stretcher-bones.png
+   :align: center
+
+   Face Stretcher Bones.
+
+After the main face bones are placed use the cheek bone to connect the eye-nose area to the jaw mouth area.
+Then do the same with the brow area. This process will automatically define face muscles compression areas.
+
+Position the eye bones in the eye pivot point facing right **toward** the face on the Y axis.
+The length of the eye bones should correspond to the radius of the eye.
+
+.. figure:: /images/addons_rigging_rigify_bone-positioning_face-eyes-pivot-position.png
+   :align: center
+
+   Eyes Pivot Position.
+
+.. tip:: Eye Pivot
+
+   If your eye has a spherical shape you can define its pivot by entering Edit Mode.
+   Select two opposite vertices on the center meridian -- or the opposite poles -- and
+   snapping the cursor to selection by pressing :menuselection:`Snap --> Cursor To Selected`.
+   If your eye is a complete sphere and its location it's not applied, then you can just use its center of mass.
+
+Finally position the teeth bones on your teeth geometry and the tongue bone chain as described in the figure.
+
+.. figure:: /images/addons_rigging_rigify_bone-positioning_face-mouth-teeth-positions.png
+   :align: center
+
+   Mouth and Teeth Positions.
+
+.. tip:: Tongue
+
+   The tongue will work better if the bones are aligned at the symmetry line.
+
+Before generating the rig ensure the face master bone is facing upward.
+
+
+Torso Bones
+===========
+
+Start by identifying on your character basic torso zones to follow as guide for bones placement.
+
+Head, chest and pelvis are rigid zones, so they require less bones.
+Having a good edge loop placement around zone boundaries on your model
+will help in having correct deformation after armature binding.
+
+.. figure:: /images/addons_rigging_rigify_bone-positioning_torso-landmarks.png
+   :align: center
+
+   Torso Landmarks.
+
+Starting from the side view, place the main spine bones trying to use
+one bone for the rigid areas and two for the flexible ones.
+In addition to the main spine, the torso is provided with additional pelvis bones (to oppose the leg bending),
+two breast controls and two shoulder bones.
+
+Even if the pelvis bones will not appear in the final rig as controls, they will contribute to deformation.
+
+.. figure:: /images/addons_rigging_rigify_bone-positioning_torso-bones.png
+   :align: center
+
+   Torso Bones Positioning.
+
+.. tip:: Bone Placement
+
+   Try to keep the spine as centered as possible inside the mesh bounding volume,
+   just apply a slight offset toward the back. In a similar way, consider the shoulder bones as general deformers;
+   placing it too forward -- where the collar bone should be -- could cause undesired deformations.
+
+
+Limbs Bones
+===========
+
+While placing the arm bones try to start having a straight line that goes from
+the shoulder to the hand in both front and top view. After this is done just add a slight bend to the elbow.
+This can be easily done by going in the top view, entering armature Edit Mode and
+sliding the bone junction between forearm and upper_arm slightly toward the world's Y axis.
+
+.. figure:: /images/addons_rigging_rigify_bone-positioning_limbs-arm-bones.png
+   :align: center
+
+   Arm Bones Positioning.
+
+For the leg you can follow a similar process. Start by aligning the leg bones creating a straight line from
+the hips to the ankle, then place the foot and the toe accordingly.
+Remember to add a slight bend to the knee. This can be easily done by going in the side view,
+entering armature Edit Mode and sliding the bone junction between thigh and shin slightly toward the world's Y axis.
+
+.. figure:: /images/addons_rigging_rigify_bone-positioning_limbs-leg-bones.png
+   :align: center
+
+   Leg Bones Positioning.
+
+Finally align the heel bone by going in the front view and placing the head and tail to
+fill the foot size from side to side. Then, in the side view,
+align the bone at the point where the heel just touches the ground floor.
+
+.. note::
+
+   From version 0.5 and above there is no more need of manual bone rolls alignment.
+   The generate function will take care of that for you by evaluating it from bend axis;
+   just insert a slight bend in your limb and it's done!
+   If you need more control on the orientation, follow the guidelines described in Advanced Usage.
+
+
+Fingers Bones
+=============
+
+Start by placing, finger by finger, all the knuckles in place.
+
+.. tip:: Fingers Placement
+
+   An easy and effective method to do this operation is to select on the mesh
+   the corresponding edge loop in Edit Mode and use the *Cursor to Selection* snap.
+   Then you can snap the bone to the corresponding loop using the *Selection to Cursor* snap.
+
+.. figure:: /images/addons_rigging_rigify_bone-positioning_fingers-edge-loops.png
+   :align: center
+
+   Knuckles Edge Loops and Cursor Snapping.
+
+Finalize the positioning by taking care of bone rolls (the X axis is set as bend axis).
+
+.. tip:: Bone Roll
+
+   Finger axis alignment can be easily be made consistent by selecting all the finger bones
+   and recalculating the bone rolls :menuselection:`Recalculate Roll --> Global -Z Axis`.
+
+   Thumb may require more tweaking depending on your character's mesh topology,
+   usually :menuselection:`Recalculate Roll --> Global +Y Axis` is a good starting point.
+
+   Once your bone rolls are consistent, try generating the rig and scaling the finger master controls.
+   This should cause the fingers to curl. If they are rotating on the wrong axis,
+   change the Bend Rotation Axis parameter on the first finger's parameters under Rigify Type.
+
+.. figure:: /images/addons_rigging_rigify_bone-positioning_fingers-bend-axis.png
+   :align: center
+
+   Fingers Bend Axis.
+
+When the fingers are in place proceed placing the palm bones.
+
+.. figure:: /images/addons_rigging_rigify_bone-positioning_fingers-palm-alignment.png
+   :align: center
+
+   Palm Alignment.
+
+.. tip:: Palm Placement
+
+   Try to keep palm bones' heads at a little distance between each other.
+   This distance is required for Rigify to define the palm controls hierarchy.
+   Palm axis alignment can be easily done by selecting all the palm bones and
+   recalculating the bone rolls :menuselection:`Recalculate Roll --> Global -Z Axis`.
+
+.. seealso::
+
+   For more detailed information on bones and rolls refer to
+   the :doc:`Bone Structure </animation/armatures/bones/structure>` and :ref:`armature-bone-roll`.

manual/addons/rigging/rigify/feature_sets.rst

@@ -0,0 +1,26 @@
+
+************
+Feature Sets
+************
+
+Rigify allows third party developers to implement sub-addons, called *Feature Sets*,
+which can provide new :doc:`Meta-Rigs </addons/rigging/rigify/metarigs>` and
+:doc:`Rig Types </addons/rigging/rigify/rig_types/index>`. Similar to regular add-ons,
+they can be installed from zip-files through Rigify settings.
+
+These are some examples of *Feature Sets* currently provided by past and current Rigify developers:
+
+`Cessen's Rigify Extensions <https://github.com/cessen/cessen_rigify_ext>`__
+   This feature set provides the original Rigify rigs by Nathan Vegdahl, minimally ported
+   and repackaged to work without switching Rigify to legacy mode. Note that their names
+   were changed, so meta-rigs designed for legacy mode aren't directly compatible.
+
+`Experimental Rigs by Alexander Gavrilov <https://github.com/angavrilov/angavrilov-rigs>`__
+   Rig experiments, some of which might be included in Rigify in the future. Examples include
+   limbs with an extra IK system based at knee/elbow, a spline based tentacle, and more.
+
+You can install these packages by clicking :menuselection:`Clone --> Download ZIP`,
+and then install the downloaded file through Rigify settings.
+
+Developer documentation is available on the `Blender Developer Documentation
+<https://developer.blender.org/docs/features/animation/rigify/>`__.

manual/addons/rigging/rigify/index.rst

@@ -0,0 +1,53 @@
+
+##########
+  Rigify
+##########
+
+Basics
+======
+
+.. toctree::
+   :maxdepth: 2
+
+   introduction.rst
+   basics.rst
+   bone_positioning.rst
+   rig_features.rst
+
+
+Customization
+=============
+
+.. toctree::
+   :maxdepth: 1
+
+   metarigs.rst
+   rig_types/index.rst
+
+
+Extensions
+==========
+
+.. toctree::
+   :maxdepth: 1
+
+   feature_sets.rst
+
+
+Development
+===========
+
+Developer documentation is available on
+the `Blender Developer Documentation <https://developer.blender.org/docs/features/animation/rigify/>`__.
+
+
+.. reference::
+
+   :Category: Rigging
+   :Description: Automatic rigging from building-block components.
+   :Location: :menuselection:`Properties --> Armature, Bone`, :menuselection:`3D Viewport --> Tools panel`,
+              :menuselection:`3D Viewport --> Add menu --> Armature`
+   :File: rigify folder
+   :Author: Nathan Vegdahl, Lucio Rossi, Ivan Cappiello, Alexander Gavrilov
+   :License: GPL
+   :Note: This add-on is bundled with Blender.

manual/addons/rigging/rigify/introduction.rst

@@ -0,0 +1,56 @@
+
+************
+Introduction
+************
+
+Rigify helps automate the creation of character rigs. It is based around a building-block approach,
+where you build complete rigs out of smaller rig parts (e.g. arms, legs, spines, fingers...).
+The rig parts are currently few in number, but as more rig parts are added to
+Rigify it should become more and more capable of rigging a large variety of characters and creatures.
+
+Rigify also operates on the principle that once a rig is created, that rig should no longer need Rigify.
+This means you can always distribute rigs created with Rigify to people
+who do not have it and the rigs will still function completely.
+
+It is important to note that Rigify only automates the creation of the rig controls and bones.
+It does not attach the rig to a mesh, so you still have to do skinning etc. yourself.
+
+
+Main Features
+=============
+
+Modular rigging
+   Rigify build blocks can be mixed together to rig any character you want.
+   If you need to build a character with five arms and one leg,
+   Rigify can handle it for you creating all the required complex controls system
+   (FK, IK, and all the relative snapping tools and the UI) in few seconds.
+
+Nondisruptive re-rig
+   If the generated rig doesn't fit all the features you need or, for example,
+   you decide to add something more to your character (like a sixth arm or a tail),
+   you can re-generate your rig without losing your previously generated features and your animation data.
+
+Advanced and flexible feature set for character animation
+   The included rig samples (limbs, spines, tails, fingers, faces...) adds to all the stretchy FK/IK features
+   a direct deformation secondary layer that lets you flex, bend and deform the character as you like
+   through interactive Bendy Bones controls.
+
+Shareable animation through all Rigify rigs
+   Since the control system is generated by Rigify, if you share a meta-rig through different characters
+   you will be able to share data between them even if they have different proportions.
+
+Extendable feature set
+   You can save and encode your meta-rigs to a button to have them available at any time
+   without recreating it by hand or share your meta-rigs with other people.
+   Through Python scripting you can also extend Rigify with new Rigify-types or new rig samples
+   by implementing your own :doc:`feature set <./feature_sets>` package.
+
+Ready to go
+   Once you generate your rig you won't need Rigify or any other add-on to use it.
+
+
+Activation
+==========
+
+- Open Blender and go to Preferences then the Add-ons tab.
+- Click Rigging then Rigify to enable the script.

manual/addons/rigging/rigify/metarigs.rst

@@ -0,0 +1,397 @@
+
+******************
+Creating Meta-rigs
+******************
+
+#. Add a single bone from the :menuselection:`Add --> Armature` menu.
+#. Go in armature Edit Mode and build the meta rig by samples or Rigify-types.
+#. Define the :ref:`Rigify bone collection UI <bpy.types.BoneCollection.rigify_ui_row>`,
+   :ref:`color sets <bpy.types.Armature.rigify_colors>`, and selection sets.
+#. In the armature properties click on the *Generate* button to generate the rig.
+
+
+How Rigify Works
+================
+
+Rigify Meta-Rigs are split in multiple Sub-Rigs
+   A meta-rig is an assembly of bone chains. A bone chain is identified by the *Connected* attribute.
+   Bone chains can be further connected together by parenting them without using the *Connected* attribute
+   (i.e. using the *Keep Offset* option while parenting).
+
+A custom attribute is set on the first bone of the sub-rig chain
+   Each first bone of a bone chain has a custom attribute on it which is a Rigify custom property
+   that identifies the sub-rig type. At rig generation time Rigify will determine which controls and
+   deform bones will be created processing the meta-rig from the first bone to the last of each chain.
+
+   .. figure:: /images/addons_rigging_rigify_metarigs_split-samples.png
+
+      Human meta-rig split by samples.
+
+New meta-rigs are created assembling sub-rigs samples
+   Since a meta-rig is just a collection of sub-rigs,
+   new meta-rigs can be built assembling sub-rigs in different ways.
+   This way an infinite number of meta-rigs can be built from the same rigging blocks.
+
+   .. figure:: /images/addons_rigging_rigify_metarigs_built-samples.png
+
+      Cat meta-rig built by samples.
+
+All the mechanics, deformation bones and widget are created on a single click
+   The meta-rig contains more information than the visualized bones.
+   In fact at generation time Rigify will identify each sub-rig type and depending on
+   the selected options will create all the sophisticated controls, switches, and
+   deforming bones with a single click.
+
+
+Creating a new Meta-rig
+=======================
+
+Add a new Armature Object
+-------------------------
+
+.. reference::
+
+   :Mode:      Object Mode
+   :Menu:      :menuselection:`Add --> Armature --> Single Bone`
+   :Shortcut:  :kbd:`Shift-A`
+
+Building your own meta-rig from scratch requires an armature object to work with.
+Just add a single bone from the *Add* menu.
+
+.. tip::
+
+   At this stage naming the newly added armature ``metarig`` is a good idea.
+   You can do it at any time (or not at all) but it's suggested to do it before going on
+   so it will always be clear on which armature you have to work when editing the meta-rig structure.
+
+
+Editing the Armature
+--------------------
+
+Now that there is an armature object to work -- with the armature selected -- enter armature Edit Mode.
+Building a meta-rig from scratch in Edit Mode can be done in two ways:
+
+#. Adding rig samples.
+#. Creating bone chains.
+
+
+Adding Samples (Basic)
+^^^^^^^^^^^^^^^^^^^^^^
+
+Adding pre-defined samples in Edit Mode is a good way to start building a meta-rig.
+This way you can become familiar with the available building blocks and how they are meant to be used.
+To add a rig sample:
+
+#. Go in the armature tab.
+#. Scroll down to Rigify panel.
+#. Select a sample from the list.
+#. Click on the *Add sample* button.
+#. Edit the bone positions to match your character.
+
+For the list of available samples, see the :doc:`Rig Types </addons/rigging/rigify/rig_types/index>` page.
+
+
+.. _bpy.types.PoseBone.rigify_type:
+.. _bpy.types.RigifyParameters:
+
+Using Rig Types (Advanced)
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. figure:: /images/addons_rigging_rigify_metarigs_rigify-type-panel.png
+   :align: right
+   :width: 300px
+
+For full control, you can use the Rigify Type panel of bone properties in Pose Mode to assign
+any Rigify sub-rig type to any bone, as well as change its options.
+
+For the list of available sub-rig types and their options, see the
+:doc:`Rig Types </addons/rigging/rigify/rig_types/index>` page.
+
+At the top of the panel you can find a field specifying the rig type for the active bone. The drop-down list
+can be optionally filtered by the :doc:`Feature Set </addons/rigging/rigify/feature_sets>` it belongs to.
+
+Below that you can change options relevant to the selected rig type, if it has any.
+
+Bone Collection References
+""""""""""""""""""""""""""
+
+Some rig types that generate many control bones have options that reference
+:ref:`Bone Collections <bpy.types.BoneCollection.rigify_ui_row>`. These reference lists have a standard UI with
+the following features:
+
+* A checkbox controlling whether the reference should be used.
+* A button to copy the reference list contents from the active to all selected bones.
+* A plus button to add a new reference to the list.
+* A list of references, each entry with a field to specify the target collection,
+  and a button to remove the entry from the list.
+
+.. note::
+
+   Each sub rig has a required number of bones as input. If you are unsure on how to use rig-types properties,
+   add a rig sample to your armature to see how it is supposed to be used.
+
+
+Preserved Bone Properties
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Certain properties of the metarig bones are often copied to the generated rig control, deform and mechanism bones.
+
+The exact set depends on the sub-rig and the specific generated bone, and the sub-rig may override some properties
+even when it preserves others from the same subset, but there are certain common patterns:
+
+Parenting Settings
+   This subset consists of the parent ORG bone, Use Connect, Use Inherit Rotation, Use Local Location, and Inherit
+   Scale.
+
+   It is usually copied to deform bones, FK controls, and in other cases where the sub-rig doesn't have a reason
+   to completely override them.
+Bendy Bone Settings (Edit Mode)
+   Consist of the segment count, Vertex Mapping Mode, Ease In/Out, Roll In/Out, Curve In/Out and Scale In/Out.
+
+   The segment count is often overridden via a sub-rig option, but other settings are usually copied to deform
+   bones as is.
+Transformation Settings
+   Consist of the rotation mode, pose mode rotation values, and channel locks.
+
+   These settings are usually copied to FK controls.
+Custom Properties
+   Usually copied to one of the controls generated based on the metarig bone (mainly FK). Intra-armature drivers
+   that access the property are retargeted to the copied instance.
+Custom Widget
+   Usually copied to one of the controls generated based on the metarig bone (mainly FK), and suppresses automatic
+   generation of a widget for the bone if specified.
+
+
+Custom Root Bone
+^^^^^^^^^^^^^^^^
+
+If the meta-rig contains a bone called ``root``, it is used as the root control bone instead of creating a new one.
+This allows changing the rest position of the root bone, assigning a custom widget,
+or adding custom properties to the bone.
+
+The custom root bone must have no parent, and use the :ref:`basic.raw_copy <rigify.rigs.basic.raw_copy>` sub-rig
+type or none.
+
+
+.. _bpy.ops.Armature.rigify_apply_selection_colors:
+.. _bpy.ops.Armature.rigify_add_bone_groups:
+.. _bpy.types.Armature.rigify_colors:
+.. _bpy.types.Armature.rigify_colors_lock:
+.. _bpy.types.Armature.rigify_theme_to_add:
+.. _bpy.types.Armature.rigify_colors_index:
+.. _bpy.types.RigifySelectionColors:
+.. _bpy.types.RigifyArmatureLayer:
+
+Color Sets
+==========
+
+.. figure:: /images/addons_rigging_rigify_metarigs_color-sets-panel.png
+   :align: right
+   :width: 300px
+
+The Color Sets panel is used to define the bone color scheme for the final rig. The colors from the list
+can be associated with bone collections from the relevant panel.
+
+The top two rows of the Color Sets panel are used to define the general behavior of the bone colors.
+Usually color themes use a gradient of colors to define the different bone states: default, selected and active.
+When multiple color themes are used in the same rig, identifying which bone is selected or
+active can be tricky since each color will have its corresponding state.
+
+To override this behavior Rigify unifies the active and selected states using the same color.
+This is defined by two values:
+
+Unified Selected/Active Colors
+   When this option is active adding a bone group in the list will always keep the colors consistent.
+   When a color scheme is added from a theme, the color scheme is loaded as is.
+   Click on the *Apply* button to force the system to unify selected and active colors.
+
+Selected/Active Colors
+   This two color fields define respectively the *Selected* and *Active* colors.
+   By default Rigify reads these colors from the theme defined by the user in the Blender preferences.
+   This way the *Selected*/*Active* colors can always have a predictable and consistent behavior in the UI.
+   The colors can be customized by clicking on the relevant color field.
+   To reset them to the Blender current theme value just click on the button with the update icon.
+
+Color Sets can be added and deleted by clicking on the ``+`` or ``-`` buttons.
+All color sets can be deleted at once by clicking on the Specials menu.
+
+To add the colors from the predefined Rigify default color scheme (as shown in the image) to the list click
+the *Add Standard* button.
+
+To add a specific theme with its own color scheme, select it from the list and click on the *Add From Theme* button.
+
+
+.. _bpy.types.BoneCollection.rigify_ui_row:
+
+Bone Collections UI
+===================
+
+.. figure:: /images/addons_rigging_rigify_metarigs_bone-collections-panel.png
+   :align: right
+   :width: 300px
+
+:doc:`Bone Collections </animation/armatures/bones/bone_collections>` are used to group related bones together
+so that they can be hidden or revealed together.
+
+Rigify can take advantage of collections to generate extra features and the user interface for the final rig.
+A panel named :ref:`Rig Layers <rigify.rig_ui_template.RigLayers>` is generated with buttons for hiding the
+collections, arranged in an intuitive layout.
+
+The Bone Collections UI panel allows configuring the layout of that generated panel, as well as specifying some
+other settings for bone collections, such as the color set to use.
+
+The top of the panel is occupied by a list that duplicates the main bone collection list, but displays additional
+properties, such as the color set, whether the collection has a button, or whether it generates a selection set.
+
+Validate Collection References
+  Some sub-rig types have :ref:`references <bpy.types.RigifyParameters>` to bone collections in their properties.
+  Rigify uses a referencing scheme that is robust to collection renames, but deleting collections or joining armatures
+  can still lead to broken references.
+
+  This button runs a scan that validates and normalizes all collection references, reporting any errors, and
+  reducing the chance of breakage being caused by subsequent user actions.
+
+  This scan is also performed automatically every time the rig is generated.
+
+  .. warning::
+    To avoid breakage this operation should be used both immediately before and after joining two metarig armatures.
+    More specifically, it must be always done between the actions of renaming any collections and joining.
+
+Color Set
+  Specifies the :ref:`color set <bpy.types.Armature.rigify_colors>` to use for bones in this collection. If a bone
+  belongs to multiple collections, in general the collection located earlier in the list has priority.
+
+Add Selection Set
+  Specifies whether a selection set should be generated for this collection.
+
+UI Row
+  If nonzero, specifies which row of the :ref:`Rig Layers <rigify.rig_ui_template.RigLayers>` panel should contain the
+  button controlling the visibility of this collection. When zero, no button is generated, and the collection is
+  hidden.
+
+UI Title
+  This field can be used to override the title used on the UI button to be distinct from the true collection name.
+  Unlike collection names, titles are not required to be unique, so this can be used to reduce clutter by relying
+  on contextual cues within the panel.
+
+UI Layout sub-panel
+-------------------
+
+.. figure:: /images/addons_rigging_rigify_metarigs_bone-collections-layout-panel.png
+   :align: right
+   :width: 300px
+
+The UI Layout sub-panel provides a WYSIWYG editor for the layout of the generated UI panel
+(as defined by the UI Row and UI Title settings above).
+
+Each row contains three buttons at the end:
+
+Arrow
+   Moves the active collection button to this row.
+Plus
+   Inserts a new row before the current one.
+Minus
+   Removes the current row and shifts all buttons up.
+
+To the left of the editing control buttons, rows display buttons corresponding to the collections, same as the final
+UI, except that rather than hiding or unhiding, clicking these buttons selects the collection.
+
+For the active collection the selection button is replaced with an input field for editing the UI Title, and an **X**
+button to unassign the collection from the UI.
+
+For any collections not assigned to the UI, their select buttons are displayed in a separate section at the bottom
+of the sub-panel.
+
+The ``Root`` collection will be added and/or assigned a UI button automatically if necessary when the rig is
+generated. If desired, it is possible to manually assign UI buttons to the internal ``ORG``, ``DEF`` and ``MCH``
+collections.
+
+.. tip::
+   Blank rows appear much thinner in the final interface, since they don't have to contain editing buttons, and can be
+   used as logical separators.
+
+Actions
+=======
+
+.. figure:: /images/addons_rigging_rigify_metarigs_actions-list-panel.png
+   :align: right
+   :width: 300px
+
+The :doc:`Action </animation/constraints/relationship/action>` constraint allows applying poses defined
+by an action to bones based on the transformation of another bone. This requires adding the constraint to every
+bone affected by the action, which is very tedious. For this reason, Rigify includes a system to do this
+automatically through the Actions panel.
+
+The panel defines a list of actions to be applied to the generated rig bones. Each action must be listed only once.
+
+The list entries show the name of the action, the trigger (a bone or a corrective action driven by two others), and
+a checkbox that can be used to temporarily disable applying this action to the rig. The icon at the start of the entry
+is changed from an action icon to a link icon to highlight corrective actions that depend on the active normal one,
+or normal actions used by the active corrective action.
+
+.. note::
+   The Action constraints are added to the bones in such an order as to exactly reproduce the intended deformation,
+   assuming the actions were created (posed and keyframed) in the order listed.
+
+Normal Actions
+--------------
+
+.. figure:: /images/addons_rigging_rigify_metarigs_actions-normal-panel.png
+   :align: right
+   :width: 300px
+
+Normal actions are applied based on the transformation of a specific control bone from the generated rig.
+They have the following properties:
+
+Control Bone
+   Specifies the bone that drives the action.
+Symmetrical
+   If the control bone has a suffix that specifies that it belongs to the left or right side, this option can
+   be enabled to automatically apply symmetry.
+
+   When enabled, left-side bones keyframed in the action will be controlled by the left-side control, and right-side
+   bones by the right side control. Bones that don't have a a side suffix are assumed to belong to the center of the
+   character. They are rigged with two Action constraints with influence 0.5 that are controlled by each of the
+   control bones.
+Frame Start & End
+   Specifies the frame range of the action that will be used by the created constraints.
+Target Space, Transform Channel
+   Specifies the coordinate space and transformation channel of the target bone that should be used.
+Min, Max
+   Specifies the range of the transformation channel values that is mapped to the specified action frame range.
+Default Frame
+   Shows the frame within the action that maps to the neutral value (1 for scale and 0 otherwise)
+   of the transformation channel, as computed from the specified range values.
+
+Corrective Actions
+------------------
+
+.. figure:: /images/addons_rigging_rigify_metarigs_actions-corrective-panel.png
+   :align: right
+   :width: 300px
+
+Corrective actions are applied based on the progress of two other actions from the list, and are used to improve
+the pose when they are used together.
+
+Frame Start & End
+   Specifies the frame range of the action that will be used by the created constraints.
+Trigger A & B
+   Specifies the two actions that control the correction. The interface rows contain buttons to show the settings
+   for that action, or jump to it in the list.
+
+The progress of the corrective action from the start to the end frame is calculated as the product of the progress
+values of the two trigger actions. Thus, the start frame is applied when either of the triggers is at the start frame,
+and the end frame is used when both are at their end frame.
+
+Corrective actions must be below their triggers in the list, which is enforced via an implicit reorder even if
+violated.
+
+.. tip::
+   Corrective actions behave in the most intuitive way when both triggers have the Default Frame equal to Start Frame.
+   To create a corrective action in such case:
+
+   * Create the two trigger actions, add them to the panel and generate the rig.
+   * Pose your controls so that both trigger actions are fully activated to the end frame.
+   * Pose and keyframe the necessary corrections in the end frame of the new action, while keying the start
+     frame to the neutral values.
+   * Add the newly created action to the end of the list in the panel and configure its settings.

manual/addons/rigging/rigify/rig_features.rst

@@ -0,0 +1,552 @@
+
+**********************
+Generated Rig Features
+**********************
+
+After human rig generation a new armature named ``rig`` will be added to your scene.
+This is the character rig you have generated from the human meta-rig and will contain all the features.
+
+
+Common Features
+===============
+
+.. _rigify.rig_ui_template.RigBakeSettings:
+.. _rigify.rig_ui_template.RigUI:
+.. _rigify.rig_ui_template.RigLayers:
+
+Rig UI Panels
+-------------
+
+.. figure:: /images/addons_rigging_rigify_rig-features_rig-ui-panels.png
+   :align: right
+   :width: 200px
+
+The generated rig is accompanied by a script that implements a set of panels that appear in the Item
+tab of the 3D view sidebar when a bone belonging to the generated rig is active.
+
+Rig Bake Settings
+^^^^^^^^^^^^^^^^^
+
+This panel is displayed if the armature has an active :doc:`Action </animation/actions>`, and
+is used by operators that apply an operation to multiple keyframes.
+
+Bake All Keyed Frames
+   When enabled, the operator computes and keyframes its result on every frame that has a key for any of the
+   bones, as opposed to just relevant ones.
+Limit Frame Range
+   When enabled, the operator is limited to a certain frame range.
+
+   Start, End
+      Specify the frame range to process.
+   Get Frame Range
+      Sets the baking frame range from the scene frame range.
+
+Rig Main Properties
+^^^^^^^^^^^^^^^^^^^
+
+This panel shows properties and operators that are relevant to the selected bones.
+
+Rig Layers
+^^^^^^^^^^
+
+This panel contains buttons for toggling visibility of bone collections.
+
+The layout and labels of the buttons are defined in the metarig
+:ref:`Bone Collection UI <bpy.types.BoneCollection.rigify_ui_row>` panel.
+
+
+Common Controls
+---------------
+
+Rigify rigs are built from standardized components called sub-rigs, which are linked together in a parent-child
+hierarchy. Although the precise behavior of each sub-rig is determined by its implementation, there are certain
+conventions that are followed by many of them.
+
+Root Bone
+^^^^^^^^^
+
+Every Rigify rig has a bone called `root`, which serves as a parent for all bones of the rig.
+It is assigned to a bone collection called `Root`. Unless the metarig has a custom bone
+of that name, it is positioned at the origin of the rig object. Its widget looks like
+a circle with four arrow shaped protrusions.
+
+.. figure:: /images/addons_rigging_rigify_rig-features_arm-controls.png
+   :align: right
+   :width: 200px
+
+Limb Master
+^^^^^^^^^^^
+
+Many limb-like sub-rigs have a gear-shaped bone at their base.
+
+This bone can in some cases be used to transform the whole sub-rig as a rigid unit, and is also used as a container
+for its custom properties that are displayed in the *Rig Main Properties* panel. If you are looking in the Graph
+editor for the animated values of the properties, this is most likely the bone to look at.
+
+As an exception, if multiple controls of the sub-rig need their own copy of conceptually the same property,
+it may be placed on those controls directly instead.
+
+Tweak Controls
+^^^^^^^^^^^^^^
+
+These controls look like blue spheres in the default color scheme, and are the final control layer above the
+deformation bones themselves.
+
+Tweaks are subordinate to the general IK or FK limb position but can be moved apart, twisted and scaled freely,
+even reaching virtually impossible limb shapes.
+
+Rubber Tweak
+   .. figure:: /images/addons_rigging_rigify_rig-features_rubber-tweak.png
+      :align: right
+      :width: 200px
+
+   Some sub-rigs provide a slider in their *Rig Main Properties* when tweaks are selected, which controls
+   the smoothness of the Bendy Bone joint at that position. When zero, the joint deforms with a sharp bend,
+   while setting it to 1 makes the transition smooth for a more rubber hose cartoon like appearance.
+
+Custom Pivots
+^^^^^^^^^^^^^
+
+Some bones that can be freely moved in space (like IK controls) can be optionally accompanied by a custom pivot
+control. These controls usually look like a plain axes empty with the axis lines capped with squares or crosses,
+like the one in the image above. The control can be freely moved to change the location of the pivot, and then
+rotated or scaled to transform the target bone around the pivot.
+
+IK and FK Switching
+^^^^^^^^^^^^^^^^^^^
+
+.. figure:: /images/addons_rigging_rigify_rig-features_ik-fk-switch.png
+   :align: right
+   :width: 200px
+
+A number of rig types provides both IK and FK controls (red for IK and green for FK in the image above),
+with an ability to switch and snap between them.
+
+Switching is controlled by a slider in *Rig Main Properties*, usually blending between full IK at 0 and full FK at 1.
+
+Snapping one type of controls to the shape of the other is done via buttons, which form a group of three
+in their complete set:
+
+* The main button will snap on the current frame, and auto-key the result if enabled.
+* The *Action* button will bake the change on multiple keyframes, according to *Rig Bake Settings*.
+* The *Clear* button will delete keyframes on the corresponding controls within the bake interval.
+
+Parent Switching
+^^^^^^^^^^^^^^^^
+
+.. figure:: /images/addons_rigging_rigify_rig-features_parent-switch.png
+   :align: right
+   :width: 200px
+
+Some freely movable controls, e.g. usually the IK controls, can have a mechanism to switch their parent bone
+between a set of choices, including the root bone, or none at all.
+
+This mechanism is exposed in the *Rig Main Properties* panel through a row with three controls:
+
+* A button that presents a dropdown menu, which allows switching the parent on the current frame while
+  preserving the bone position and orientation in the world space.
+* A dropdown input field that directly exposes the switch property for keyframing and direct manipulation.
+  Changing the value can cause the bone position to jump.
+* A button to apply the position preserving parent switch over the bake range of keyframes.
+
+.. note::
+   When manually placing a Child Of constraint on the control bone, the built-in parent should be switched to none.
+
+Limbs
+=====
+
+Limbs have a master bone and tweaks. Depending on the user defined meta-rig options,
+multiple deform bone segments with tweaks will be created.
+
+The IK control may have an optional custom pivot, as well as additional predefined pivots.
+
+Rigify's limbs have the following controls in the Sidebar panel:
+
+.. figure:: /images/addons_rigging_rigify_rig-features_limb-properties.png
+   :align: right
+   :width: 200px
+
+FK Limb Follow :guilabel:`Slider`
+   When set to 1 the FK limb will not rotate with the torso and will retain is rotation
+   relative to the root bone instead.
+
+IK-FK :guilabel:`Slider`
+   Controls whether the limb follows IK or FK controls, blending between full IK at 0 and full FK at 1.
+
+IK<->FK Snapping :guilabel:`Buttons`
+   Snaps one type of controls to another.
+
+IK Stretch :guilabel:`Slider`
+   Blends between the limb stretching freely at 1, or having its maximum length constrained at 0.
+
+Toggle Pole :guilabel:`Switch`
+   When the toggle is Off, the IK limb will use the rotational pole vector (the arrow at the base of the limb).
+   Rotating/translating/scaling the arrow will control the IK limb base.
+
+   When the toggle is On, the classic pole vector will be displayed and used to orient the IK limb.
+   The arrow will continue to handle the scale and the location of the IK limb base.
+
+   Similar to *Parent Switching*, the row includes buttons to convert the current pose between types,
+   or bake the whole action.
+
+IK Parent :guilabel:`Switch`
+   Switches the effective parent of the main IK control.
+
+Pole Parent :guilabel:`Switch`
+   Switches the effective parent of the classic IK Pole control.
+
+Arms
+----
+
+.. figure:: /images/addons_rigging_rigify_rig-features_hand-controls.png
+   :align: right
+   :width: 200px
+
+:ref:`Arms <rigify.rigs.limbs.arm>` have the simplest control structure: the IK controls consist of the main IK
+control, the optional custom pivot control, and the optional wrist control (the bent circle), which pivots around
+the tail rather than the head of the hand bone.
+
+There are no additional controls in the *Rig Main Properties* panel.
+
+Legs
+----
+
+:ref:`Legs <rigify.rigs.limbs.leg>` have a more complicated setup, which has:
+
+.. figure:: /images/addons_rigging_rigify_rig-features_foot-controls.png
+   :align: right
+   :width: 200px
+
+IK & FK Toe :guilabel:`Optional`
+   Two separate IK and FK controls for the toe (this is  on by default in the bundled metarigs,
+   and is recommended for stable IK<->FK snapping).
+IK Heel
+   A heel control which can be rotated to command forward or backward roll, sideways rock, or yaw of the heel.
+Toe Pivot :guilabel:`Optional`
+   An extra pivot control rotating around the base of the toe.
+Custom Pivot :guilabel:`Optional`
+   A custom pivot control.
+
+The properties panel has two additional features:
+
+.. figure:: /images/addons_rigging_rigify_rig-features_foot-properties.png
+   :align: right
+   :width: 200px
+
+IK->FK Snap With Roll :guilabel:`Buttons`
+   Standard IK to FK snapping resets the transformations of all IK controls other than the main one. This is
+   not convenient to use in an animation that involves the use of the heel control, because roll and rock would
+   be folded into the transformation of the main control.
+
+   This alternative snapping operator tries to deduce the rotation of the heel control so as to keep the main
+   IK control parallel to the ground plane inferred from the *current* orientation of the IK control. The operator
+   has options to specify which rotational axes to use for the heel control rotation.
+
+Roll On Toe :guilabel:`Slider` :guilabel:`Optional`
+   If enabled in the sub-rig settings, this slider can be used to control whether the heel rotation (excluding
+   backward roll) is applied at the base or the tip of the toe.
+
+Fingers & Tentacles
+===================
+
+Simple Tentacle
+---------------
+
+.. figure:: /images/addons_rigging_rigify_rig-features_simple-controls.png
+
+The simplest type of rig for a finger or appendage in general is the
+:ref:`simple tentacle <rigify.rigs.limbs.simple_tentacle>` sub-rig. It has only basic FK controls and tweaks,
+with the only automation being the ability to copy certain axes of the local rotation of a FK control to the next one.
+
+Advanced Finger
+---------------
+
+.. figure:: /images/addons_rigging_rigify_rig-features_finger-controls.png
+
+For fingers specifically, Rigify has a dedicated :ref:`finger <rigify.rigs.limbs.super_finger>` sub-rig type,
+which provides:
+
+Master
+   A master control (orange), which can be used to rotate the finger as a whole, as well as to bend it via Y scaling.
+FK Chain
+   FK control chain (green) that can also operate as semi-tweaks through allowing translation.
+IK Control :guilabel:`Optional`
+   IK control for the tip (red).
+
+.. note::
+   IK in this sub-rig is rudimentary and operates as an adjustment for FK. The intended way of use is to pose
+   the finger in FK, and then enable IK after using IK->FK snap if it is necessary to pin the tip of the finger
+   in place.
+
+The properties panel has the following features:
+
+.. figure:: /images/addons_rigging_rigify_rig-features_finger-properties.png
+   :align: right
+   :width: 200px
+
+Finger IK :guilabel:`Slider` :guilabel:`Optional`
+   Slider controlling the influence of the IK.
+
+FK<->IK Snapping :guilabel:`Buttons` :guilabel:`Optional`
+   Snaps the IK control to the end of the finger, or adjusts the FK controls to the result of the IK correction.
+
+Curvature :guilabel:`Slider`
+   Has the same effect as *Rubber Tweak* on limbs, controlling the rubber hose cartoon effect.
+
+Spline Tentacle
+---------------
+
+.. figure:: /images/addons_rigging_rigify_rig-features_spline-controls.png
+
+   Spline Tentacle (Stretch To Fit, Manual Squash & Stretch)
+
+.. figure:: /images/addons_rigging_rigify_rig-features_spline-controls-tip.png
+
+   Spline Tentacle (Direct Tip Control)
+
+The :ref:`spline tentacle <rigify.rigs.limbs.spline_tentacle>` is an advanced rig for a flexible appendage (tentacle)
+based on the :doc:`Spline IK </animation/constraints/tracking/spline_ik>` constraint. The IK control bones manage
+control points of a Bezier spline curve, which in turn is followed by the IK chain.
+
+The tentacle can be generated in three major modes:
+
+Stretch To Fit
+   In this simplest mode all bones of the sub-rig deform chain follow the curve and squash & stretch to match
+   its length.
+Manual Squash & Stretch
+   This mode is almost the same, but the chain does not automatically scale to match the curve length.
+   Instead, it tries to cover as much as possible of the curve given its manually scaled length.
+   If the curve is too short, the chain will overhang it and straighten out, but this can result in jitter.
+Direct Tip Control
+   This mode is more similar to the behavior of IK limbs: the final bone of the chain is directly controlled by
+   the tip IK control, while the other bones of the chain stretch and follow the curve to bridge the gap.
+
+The tentacle sub-rig has the following control bones:
+
+Master
+   The tentacle has the same gear master control as other limbs (seen as a line in the images).
+IK Start
+   The IK control at the base of the tentacle, which can be used to control the base twist and sideways scale, and
+   is one of the potential switchable parents for other IK controls.
+
+   In the *Manual Squash & Stretch* mode it controls uniform scale of the tentacle in all directions.
+IK Start (Extra) :guilabel:`Optional`
+   Extra start controls, optional and hidden by default. Switchable parents default to the *IK Start* control.
+   The scale of the control may optionally affect the thickness of the chain via the radius of the curve point.
+IK Middle
+   Controls for the middle of the curve. The switchable parents default to *Master*, but may be set to
+   *IK Start* or *IK End* controls.
+   The scale of the control may optionally affect the thickness of the chain via the radius of the curve point.
+IK End (Extra) :guilabel:`Optional`
+   Extra end controls, optional and hidden by default. Switchable parents default to the *IK End* control.
+   The scale of the control may optionally affect the thickness of the chain via the radius of the curve point.
+
+   The *Direct Tip Control* mode adds one more extra end control next to the middle ones that cannot be hidden.
+IK End
+   Controls the last control point of the curve, and is one of the potential parents for the other chain controls.
+
+   In the *Direct Tip Control* mode also directly controls the last bone of the chain.
+IK End Twist :guilabel:`Optional`
+   This control is visually attached to the last bone of the chain, and must use Euler rotation.
+
+   * *Stretch To Fit*: it controls the twist of the tip of the tentacle, interpolated to nothing at the base.
+   * *Manual Squash & Stretch*: it also controls the scaling of the tip of the tentacle.
+   * *Direct Tip Control*: the control does not exist.
+FK Chain :guilabel:`Optional`
+   If enabled, the rig has an alternative fully FK control chain.
+
+The properties panel has the following features:
+
+.. figure:: /images/addons_rigging_rigify_rig-features_spline-properties.png
+   :align: right
+   :width: 200px
+
+Start/End Controls :guilabel:`Optional`
+   If extra controls exist, this property controls how many of them are visible and active.
+
+   When a control is disabled, it is snapped to a position extremely close to the corresponding end control point,
+   thus effectively neutralizing its effect. Thus, changing the setting during an animation can cause jumps.
+
+   The plus and minus buttons can help with maintaining a continuous transition in an animation by keyframing the
+   change in the property value with Constant interpolation, and also snapping and keyframing the control itself
+   to its 'hidden' position.
+
+End Twist Estimate :guilabel:`Optional`
+   In the *Direct Tip Control* mode the twist at the end of the tentacle is deduced from the free form orientation
+   of the tip control, rather than using a separate twist control with constrained Euler rotation. However, for
+   technical reasons, that can only give values within the 180 degrees range of neutral.
+
+   A long tentacle can accept more twist than 180 degrees, so a workaround is necessary. This property allows
+   specifying an approximate estimate of the twist value (effectively shifting the neutral position), and the
+   rig then applies the automatic correction within 180 degrees of this value.
+
+IK-FK, IK<->FK Snapping :guilabel:`Optional`
+   If the FK controls are enabled, these provide standard IK-FK switching and snapping.
+
+   However, unlike other limbs, for this rig automatic IK to FK snapping can only be approximate and requires
+   manual tuning. For this reason, buttons for baking the snapping over a range of keyframes are not provided.
+
+Parent Switch
+   Switches the parent of the selected IK control.
+
+
+Spine, Head & Tail
+==================
+
+.. figure:: /images/addons_rigging_rigify_rig-features_spine-controls.png
+   :align: right
+   :width: 200px
+
+Spine
+-----
+
+The :ref:`spine <rigify.rigs.spines.basic_spine>` sub-rig provides a cube shaped torso control with
+switchable parent, and bent circle shaped hip and chest controls subordinate to it. For low level deformation
+tweak controls are provided.
+
+The torso control can optionally be accompanied with a custom pivot control. The rig can also optionally
+provide a full set of FK controls that are subordinate to the normal simplified ones, but above tweaks.
+
+The rig properties panel for the spine controls usually includes options for the head and/or tail as well.
+
+
+.. figure:: /images/addons_rigging_rigify_rig-features_head-controls.png
+   :align: right
+   :width: 200px
+
+Head
+----
+
+The :ref:`head <rigify.rigs.spines.super_head>` sub-rig attaches to the end of the spine, and provides
+rotational controls for the head and neck, as well as tweaks for fine control of the neck.
+
+If the neck is three or more bones long, an additonal tweak-like translational
+neck bend control is provided (the widget looks like a circle with arrows).
+
+The properties panel contains the following options:
+
+Neck Follow :guilabel:`Slider`
+   .. figure:: /images/addons_rigging_rigify_rig-features_head-properties.png
+      :align: right
+      :width: 200px
+
+   This slider controls the rotations isolation for the neck bones.
+   The neck will follow the orientation of the Torso when set to 0, and the Chest when set to 1.
+
+Head Follow :guilabel:`Slider`
+   .. figure:: /images/addons_rigging_rigify_rig-features_tail-controls.png
+      :align: right
+      :width: 200px
+
+   This slider controls the rotations isolation for the head.
+   The head will follow the orientation of the Torso when set to 0, and the Chest when set to 1.
+
+Tail
+----
+
+The :ref:`tail <rigify.rigs.spines.basic_tail>` sub-rig attaches to the start of the spine, and provides
+FK controls for the tail, as well as a master control that replicates its local rotation around certain axes
+to all individual bones.
+
+The properties panel contains the following options:
+
+Tail Follow :guilabel:`Slider`
+   This slider controls the rotations isolation for the tail.
+   The tail will follow the orientation of the Torso when set to 0, and the Hips when set to 1.
+
+Face
+====
+
+.. note::
+   This describes the new-style modular face produced by the Upgrade Face operator button.
+
+Basic Concepts
+--------------
+
+Skin Bone Chains
+^^^^^^^^^^^^^^^^
+
+.. figure:: /images/addons_rigging_rigify_rig-features_face-chains.png
+   :align: right
+   :width: 300px
+
+The foundation of the Rigify face is a network of Bendy Bone :ref:`chains <rigify.rigs.skin.basic_chain>` with
+controls placed at every bone end. These controls affect all bones that meet at that specific point.
+
+When the controls are merely translated, the B-Bone chains retain the normal automatic bezier handle behavior.
+Local rotation and/or scaling of the controls are applied on top of that.
+
+In case of :ref:`certain chains <rigify.rigs.skin.stretchy_chain>`, the transformation of the end and/or middle
+controls is interpolated to other controls located between them. In such cases the controls often have different
+colors and/or shapes.
+
+Additionally, certain controls have :ref:`arbitrary constraints <rigify.rigs.skin.glue>` that partially copy
+transformation from nearby control points.
+
+Specialized Controllers
+^^^^^^^^^^^^^^^^^^^^^^^
+
+Certain areas of the face, like eyes or mouth, have additional specialized controllers that apply custom behavior
+on top of the chains and their controllers within the relevant area.
+
+Eyes
+----
+
+.. figure:: /images/addons_rigging_rigify_rig-features_eye-controls.png
+   :align: right
+   :width: 300px
+
+The :ref:`eyes <rigify.rigs.face.skin_eye>` have the following controls in addition to the eyelid chains:
+
+Master
+   This large circular control can be used to transform the whole eye as one unit.
+Common Target
+   This large control enveloping all individual eye targets has a switchable parent and can
+   be used to specify the point that the eyes should look at.
+Eye Target
+   These small circle controls within the common target control specify the point targeted by each
+   individual eye. Their local scale can also be used to affect the iris or pupil of the eye,
+   depending on how it was weight painted.
+
+The rig properties panel contains the following options:
+
+.. figure:: /images/addons_rigging_rigify_rig-features_eye-properties.png
+   :align: right
+   :width: 200px
+
+Eyelids Follow :guilabel:`Slider`
+   Controls how much the rotation of the eyeball affects the eyelids. Depending on the sub-rig generation
+   options, this slider can be split to separately control the horizontal and vertical directions.
+
+Eyelids Attached :guilabel:`Slider` :guilabel:`Optional`
+   If enabled in the sub-rig generation options, this slider can be used to disable the mechanism that
+   forces the eyelids to conform to the sphere of the eye.
+
+Parent :guilabel:`Parent Switch`
+   Selects the parent for the common target control.
+
+Mouth
+-----
+
+.. figure:: /images/addons_rigging_rigify_rig-features_mouth-controls.png
+   :align: right
+   :width: 300px
+
+The :ref:`mouth <rigify.rigs.face.skin_jaw>` has the following controls:
+
+Jaw Master
+   Controls rotation of the jaw, directly affecting the main jaw deform bone, as well
+   as chains fully belonging to the jaw. Chains forming the lip loop(s) are adjusted to
+   open the mouth as the jaw rotates or moves.
+Mouth Master
+   This control uniformly transforms the lips without moving the jaw.
+
+The rig properties panel contains the following options:
+
+.. figure:: /images/addons_rigging_rigify_rig-features_mouth-properties.png
+   :align: right
+   :width: 200px
+
+Mouth Lock :guilabel:`Slider`
+   This slider can be changed from 0 to 1 in order to suppress opening of the mouth
+   when the jaw rotates or moves.

manual/addons/rigging/rigify/rig_types/basic.rst

@@ -0,0 +1,125 @@
+
+*****
+Basic
+*****
+
+These rig types are used to generate simple single-bone features,
+and for custom rigging done directly in the meta-rig.
+
+The single-bone rig types must be applied separately to every bone even within a connected chain,
+and can have connected children controlled by a different rig type.
+This is unlike chain-based rig types that usually consume the whole connected chain.
+
+
+.. _rigify.rigs.basic.copy_chain:
+
+basic.copy_chain
+================
+
+Copies the bone chain keeping all the parent relations within the chain untouched.
+Useful as a utility rig type for custom rigs.
+
+Requirement: A chain of at least two connected bones.
+
+Control (Boolean)
+   When enabled control bones and widgets will be created.
+Deform (Boolean)
+   When enabled deform bones will be created.
+
+
+.. _rigify.rigs.basic.pivot:
+
+basic.pivot
+===========
+
+Single-bone rig type that creates a 'custom pivot' control for rotating and scaling its child sub-rigs.
+
+This type of control transforms its children when rotated or scaled, while moving it
+merely changes the pivot point used by rotation or scaling.
+
+Master Control
+   When enabled an extra parent control bone with a box widget is created to allow moving the rig.
+   It is also required by all other options besides *Deform Bone*.
+
+Widget Type
+   Allows selecting one of the predefined widgets to generate for the master control instead of the default cube.
+
+Switchable Parent
+   Generates a mechanism for switching the effective parent of the rig based on the value of a custom property.
+
+Register Parent
+   Registers the rig as a potential parent scope for its child sub-rigs' parent switches.
+
+   Tags
+      Specifies additional comma-separated tag keywords for the registered parent scope.
+      They can be used by other rigs to filter parent choices, or for selecting the default parent.
+
+      Some of the existing tags that are useful here:
+
+      ``injected`` (special)
+         The parent scope will be made available for all children of the *parent* sub-rig,
+         rather than just this rig's children.
+      ``held_object``
+         A control for the object held in the character's hand. Preferred by finger IK.
+
+         The ``injected,held_object`` combination is perfect for such a control.
+
+Pivot Control
+   Disabling this avoids generating the actual custom pivot control, effectively turning this rig type
+   into a version of `basic.super_copy`_ with parent switching support and a different widget.
+
+Deform Bone
+   When enabled a deform bone will be created.
+
+
+.. _rigify.rigs.basic.raw_copy:
+
+basic.raw_copy
+==============
+
+Single-bone rig type that copies the bone without the ``ORG-`` name prefix.
+
+Normally all bones copied from the meta-rig are prefixed with ``ORG-`` and placed on an invisible layer.
+This precludes their use as controls or deforming bones, which makes it difficult to transfer complex
+fully custom rigging verbatim from the meta-rig.
+
+This rig type does not add the automatic prefix, thus allowing an appropriate ``ORG-``, ``MCH-`` or ``DEF-``
+prefix to be manually included in the meta-rig bone name, or alternatively using no prefix to create
+a control bone.
+
+Relink Constraints
+   Allows retargeting constraints belonging to the bone to point at bones created in the process
+   of generating the rig, thus allowing custom rigging to integrate with generated bones.
+
+   To use this feature, add ``@`` and the intended target bone name to the constraint name, resulting
+   in the ``...@bone_name`` syntax. After all bones of the rig are generated, the constraint target
+   bone will be replaced. If the new bone name is just ``CTRL``, ``MCH`` or ``DEF``, this will just
+   replace the ``ORG`` prefix in the existing target bone name. For the Armature constraint you can add
+   a ``@`` suffix for each target, or just one ``@CTRL``, ``@MCH`` or ``@DEF`` suffix to update all.
+
+   Parent
+      If the field is not empty, applies the same name substitution logic to the parent of the bone.
+
+   When this feature is enabled, the bone will not be automatically parented to the root bone even
+   if it has no parent; enter ``root`` in the *Parent* field if that is necessary.
+
+
+.. _rigify.rigs.basic.super_copy:
+
+basic.super_copy
+================
+
+Single-bone rig type that simply copies the bone. Useful as utility rig type for
+adding custom features or specific deform bones to your rigs.
+
+Control (Boolean)
+   When enabled a control bone and widget will be created.
+Widget (Boolean)
+   When enabled a widget will be created in replacement to the standard.
+Widget Type (String):
+   Allows selecting one of the predefined widget types to generate instead of the default circle.
+Deform (Boolean)
+   When enabled a deform bone will be created.
+Relink Constraints
+   Works the same as in the `basic.raw_copy`_ rig. In addition, when enabled any constraints that have
+   names prefixed with ``CTRL:`` are moved to the control, and with ``DEF:`` to the deform bone.

manual/addons/rigging/rigify/rig_types/face.rst

@@ -0,0 +1,71 @@
+
+****
+Face
+****
+
+These rig types implement components of a modular face.
+
+
+.. _rigify.rigs.face.basic_tongue:
+
+face.basic_tongue
+=================
+
+Generates a simple tongue, extracted from the original PitchiPoy :ref:`super_face <rigify.rigs.faces.super_face>` rig.
+
+B-Bone Segments (integer)
+   Defines the number of b-bone segments each tweak control will be split into.
+Primary Control Layers
+   Optionally specifies bone collections for the main control.
+
+
+.. _rigify.rigs.face.skin_eye:
+
+face.skin_eye
+=============
+
+Implements a skin system :ref:`parent controller <rigify.rigs.skin.skin_parents>` that manages
+two skin chains for the top and bottom eyelids in addition to generating the eye rotation mechanism.
+
+The rig must have two child skin chains with names tagged with ``.T`` and ``.B`` symmetry
+to mark the top and bottom eyelid, which are connected at their ends forming eye corners.
+The chains are rigged to follow the surface of the eye and twist to its normal.
+
+In addition, it creates target controls for aiming the eye, including a master control shared by
+all eyes under the same parent rig. The eyelids are rigged to follow the movement of the eyeball
+with adjustable influence.
+
+Eyeball and Iris Deforms
+   Generates deform bones for the eyeball and the iris, the latter copying XZ scale from
+   the eye target control. The iris is located at the tail of the ORG bone.
+Eyelid Detach Option
+   Generates a slider to disable the mechanism that keeps eyelid controls stuck to the surface of the eye.
+Split Eyelid Follow Slider
+   Generates two separate sliders for controlling the influence of the eye rotation on X and Z eyelid motion.
+Eyelids Follow Default
+   Depending on *Split Eyelid Follow Slider*, specifies the default values for the split follow sliders,
+   or fixed factors to be multiplied with the single common follow influence slider value.
+
+
+.. _rigify.rigs.face.skin_jaw:
+
+face.skin_jaw
+=============
+
+Implements a skin system :ref:`parent controller <rigify.rigs.skin.skin_parents>` that manages
+one or more loops of mouth skin chains in response to the movement of jaw and mouth controls.
+
+The rig must have one or more child chain loops, each formed by four skin chains tagged
+with ``.T``/``.B`` and ``.L``/``.R`` symmetrical names.
+
+The lip loops are sorted into layers based on the distance from corners to the common
+center and rigged with blended influence of the jaw and the master mouth control.
+Other child rigs become children of the jaw.
+
+Bottom Lip Influence
+   Specifies the influence of the jaw on the inner bottom lip with mouth lock disabled.
+Locked Influence
+   Specifies the influence of the jaw on both lips of locked mouth.
+Secondary Influence Falloff
+   Specifies the factor by which influence fades away with each successive lip loop
+   (for bottom lip loops the blend moves away from inner bottom lip to full jaw influence).

manual/addons/rigging/rigify/rig_types/faces.rst

@@ -0,0 +1,19 @@
+
+*****
+Faces
+*****
+
+.. _rigify.rigs.faces.super_face:
+
+faces.super_face
+================
+
+Will create a face system based on the bones child to the parent that has the property set on it.
+
+Requirement: All the face bones bundled in the ``faces.super_face`` sample had to be present and
+child of the master bone that has the Rigify-type *face* property set.
+
+.. note::
+
+   This rig type is being deprecated in favor of a new modular
+   :doc:`skin <skin>` and :doc:`face <face>` rigging system.

manual/addons/rigging/rigify/rig_types/index.rst

@@ -0,0 +1,23 @@
+#############
+  Rig Types
+#############
+
+Rig types are components used by Rigify to process specific parts of the meta-rig when generating the armature.
+They represent common character features, like the spine, limbs, fingers etc.
+
+.. note::
+
+   The list of available rig types appears in the Bone properties tab when the bone is selected in Pose Mode.
+   Scroll down the Properties to find Rigify Type panel.
+
+This documents rig types that are bundled with Rigify.
+
+.. toctree::
+   :maxdepth: 2
+
+   basic.rst
+   spines.rst
+   limbs.rst
+   faces.rst
+   skin.rst
+   face.rst

manual/addons/rigging/rigify/rig_types/limbs.rst

@@ -0,0 +1,265 @@
+
+*****
+Limbs
+*****
+
+These rig types handle generation of different kind of limbs and their features, like fingers.
+
+
+.. _rigify.rigs.limbs.simple_tentacle:
+
+limbs.simple_tentacle
+=====================
+
+Will create a simple bendy and stretchy b-bones tentacle chain, which can optionally replicate local rotation
+from preceeding bones to the subsequent ones for use in cases like fingers.
+
+Requirement: A chain of at least two connected bones.
+
+Automation Axis (X, Y, Z, None)
+   Enables the automation on the selected axis. Multiple axis or none can be selected holding :kbd:`Shift-LMB`.
+   When enabled the subsequent control bones will copy the local rotations from the previous ones.
+   The option is accessible in the controls of the final rig as a Copy Rotation constraint and
+   can be disabled even after rig is generated, or at animation time.
+Assign Tweak Layers
+   If enabled, allows placing the Tweak controls in different bone collections from the main controls.
+
+
+.. _rigify.rigs.limbs.super_finger:
+
+limbs.super_finger
+==================
+
+Will create a bendy and stretchy finger chain with a master control bone that controls the rotation of
+all joints through its scale.
+
+Requirement: A chain of at least two connected bones.
+
+Bend Rotation Axis (Automatic, X, Y, Z, -X, -Y, -Z)
+   Defines the automatic rotation axis to be linked to the scale of the master bone.
+B-Bone Segments (integer)
+   Defines the number of b-bone segments each tweak control will be split into.
+IK Control
+   Generates a very simple IK mechanism with only one control.
+
+   IK starts its work with the shape of the finger defined by FK controls and adjusts it
+   to make the fingertip touch the IK control. It is designed as a tool to temporarily keep
+   the fingertip locked to a surface it touches, rather than a fully featured posing system.
+
+   To improve performance, the switchable parent for the IK control contains only one option beside None.
+   Thus it is advised to add a 'held object' control using the :ref:`basic.raw_copy <rigify.rigs.basic.pivot>`
+   rig to act as the common parent for the fingers with a fully functional parent switch.
+IK Local Location
+   Specifies the value of the Local Location option for IK controls, which decides if the location
+   channels are aligned to the local control orientation or world.
+Assign Tweak Layers
+   If enabled, allows placing the Tweak controls in different bone collections from the main controls.
+Assign Extra IK Layers
+   If enabled, allows placing the extra IK control in different bone collections from the main controls.
+
+.. note::
+
+   Rotation Axis (Bend Rotation Axis in the case of `limbs.super_finger`_)
+   affects the :doc:`roll </animation/armatures/bones/editing/bone_roll>` of the generated bones.
+   Automatic mode recalculates the generated bones roll while
+   any of the Manual modes copy the roll of the meta-rig bones.
+
+
+.. _rigify.rigs.limbs.super_limb:
+
+limbs.super_limb
+================
+
+A backwards compatibility wrapper around `limbs.arm`_, `limbs.leg`_ and `limbs.paw`_.
+
+
+.. _rigify.rigs.limbs.arm:
+
+limbs.arm
+=========
+
+Will create a fully featured bendy and stretchy arm depending on the user-defined options.
+
+Requirement: A chain of three connected bones (upper_arm, forearm, hand).
+
+.. figure:: /images/addons_rigging_rigify_rig-types_limbs_arm-required.png
+
+   Arm required bones.
+
+IK Wrist Pivot
+   Generates an extra child of the hand IK control that rotates around the tail of the hand bone.
+
+Rotation Axis (Automatic, X, Z)
+   Defines the bend axis for the IK chain. FK chains will have a totally free degree of rotation on all axes.
+Limb Segments (integer)
+   Defines the number of additional tweak controls each limb bone will have on the final rig.
+B-Bone Segments (integer)
+   Defines the number of b-bone segments each tweak control will be split into.
+Custom IK Pivot
+   Generates an extra control for the end of the IK limb that allows rotating it around an arbitrarily placed pivot.
+Assign FK Layers
+   If enabled, allows placing the FK chain in different bone collections from the IK bones.
+Assign Tweak Layers
+   If enabled, allows placing the Tweak controls in different bone collections from the IK bones.
+
+
+.. _rigify.rigs.limbs.leg:
+
+limbs.leg
+=========
+
+Will create a fully featured bendy and stretchy leg depending on the user-defined options.
+
+Requirement: A chain of four connected bones (thigh, shin, foot, toe) with one unconnected
+child of the foot to be used as the heel pivot.
+
+.. figure:: /images/addons_rigging_rigify_rig-types_limbs_leg-required.png
+
+   Leg required bones.
+
+Foot Pivot (Ankle, Toe, Ankle & Toe)
+   Specifies where to put the pivot location of the main IK control, or whether to generate an additional
+   pivot control at the base of the toe.
+
+Separate IK Toe
+   Specifies that two separate toe controls should be generated for IK and FK instead of sharing one bone.
+   This is necessary to get fully correct IK-FK snapping in all possible poses.
+
+Toe Tip Roll
+   Generates a slider to switch the heel control to pivot on the tip rather than the base of the toe
+   (for roll this obviously only applies on forward roll).
+
+Rotation Axis (Automatic, X, Z)
+   Defines the bend axis for the IK chain. FK chains will have a totally free degree of rotation on all axes.
+Limb Segments (integer)
+   Defines the number of additional tweak controls each limb bone will have on the final rig.
+B-Bone Segments (integer)
+   Defines the number of b-bone segments each tweak control will be split into.
+Custom IK Pivot
+   Generates an extra control for the end of the IK limb that allows rotating it around an arbitrarily placed pivot.
+Assign FK Layers
+   If enabled, allows placing the FK chain in different bone collections from the IK bones.
+Assign Tweak Layers
+   If enabled, allows placing the Tweak controls in different bone collections from the IK bones.
+
+
+.. _rigify.rigs.limbs.paw:
+
+limbs.paw
+=========
+
+Will create a fully featured bendy and stretchy paw depending on the user-defined options.
+
+Requirement: A chain of four or five connected bones (thigh, shin, paw, *optional* digit, toe).
+
+.. figure:: /images/addons_rigging_rigify_rig-types_limbs_paw-required.png
+
+   Front/Rear paw required bones.
+
+Rotation Axis (Automatic, X, Z)
+   Defines the bend axis for the IK chain. FK chains will have a totally free degree of rotation on all axes.
+Limb Segments (integer)
+   Defines the number of additional tweak controls each limb bone will have on the final rig.
+B-Bone Segments (integer)
+   Defines the number of b-bone segments each tweak control will be split into.
+Custom IK Pivot
+   Generates an extra control for the end of the IK limb that allows rotating it around an arbitrarily placed pivot.
+Assign FK Layers
+   If enabled, allows placing the FK chain in different bone collections from the IK bones.
+Assign Tweak Layers
+   If enabled, allows placing the Tweak controls in different bone collections from the IK bones.
+
+
+.. _rigify.rigs.limbs.front_paw:
+
+limbs.front_paw
+===============
+
+Derivative of `limbs.paw`_ with extended IK suitable for use in front paws.
+The additional IK limits the degree of change in the angle between shin and
+paw bones (2nd and 3rd) as the main IK control moves and rotates.
+
+For best results, the shin bone should not be parallel to either thigh or paw in rest pose,
+i.e. there should be some degree of bend in all joints of the paw.
+
+Heel IK Influence
+   Influence of the extended IK. At full rotating the main IK control or digit bone would
+   not affect the rotation of the paw bone, while lower values provide some blending.
+
+
+.. _rigify.rigs.limbs.rear_paw:
+
+limbs.rear_paw
+==============
+
+Derivative of `limbs.paw`_ with extended IK suitable for use in rear paws.
+The additional IK tries to maintain thigh and paw bones (1st and 3rd) in a nearly parallel orientation
+as the main IK control moves and rotates.
+
+For best results, thigh and paw bones should start nearly parallel in the rest pose.
+
+
+.. _rigify.rigs.limbs.super_palm:
+
+limbs.super_palm
+================
+
+Will create a palm system based on the distance between palm bones.
+
+Requirement: At least two bones child of the same parent.
+The property has to be set on the inner palm bones (think it as index's metacarpus),
+the rig control will appear on the last palm bone (think it as pinky's metacarpus).
+
+Both Sides
+   Generates controls on both sides of the palm, with influence on inner bones blended between them.
+
+Primary Rotation Axis (X, Z)
+   Defines the automatic rotation axis to be used on the palm bones.
+
+
+.. _rigify.rigs.limbs.spline_tentacle:
+
+limbs.spline_tentacle
+=====================
+
+This rig type implements a flexible tentacle with an IK system using the Spline IK constraint. The control bones
+define control points of a Bezier curve, and the bone chain follows the curve.
+
+The curve control points are sorted into three groups: start, middle and end. The middle controls are always
+visible and active, while the other two types can be shown and hidden dynamically using properties; when enabled
+they appear next to the corresponding permanent start/end control and can be moved from there.
+
+Extra Start Controls
+   Specifies the number of optional start controls to generate.
+Middle Controls
+   Specifies the number of middle controls to generate.
+Extra End Controls
+   Specifies the number of optional end controls to generate.
+Tip Control:
+   Specifies how the curve stretching and the final control bone work:
+
+   Stretch To Fit
+      Stretches the whole bone chain to fit the length of the curve defined by the controls.
+
+      An end twist control is generated to control the twist along the chain.
+   Direct Tip Control
+      Generates an IK end control, which directly controls the final bone of the chain similar to how
+      regular IK works for limbs, as well as controlling the end of the bezier curve. The middle bones of
+      the chain stretch to follow the curve and cover the gap.
+
+      The rig automatically deduces twist of up to 180 degrees based on the orientation of the end control.
+      Higher amounts of twist have to be dialled in through an End Twist Estimate slider to avoid flipping.
+   Manual Squash & Stretch
+      This mode allows full manual control over the chain scaling, while the chain covers as much of the curve
+      as it can given its current length.
+
+      The start control of the chain manages its uniform squash & stretch scale, while the end twist control
+      manages both the twist of the chain, as well as its scale at the tip (blended gradually along the length).
+Radius Scaling
+   Allows scaling the controls to control the thickness of the chain through the curve.
+Maximum Radius
+   Specifies the maximum scale allowed by the Radius Scaling feature.
+FK Controls
+   Generates an FK control chain and IK-FK snapping.
+Assign FK Layers
+   If enabled, allows placing the FK chain in different bone collections from the IK bones.

manual/addons/rigging/rigify/rig_types/skin.rst

@@ -0,0 +1,221 @@
+.. todo: make permanent 'new', development
+
+****
+Skin
+****
+
+These rigs implement a flexible system for rigging skin using multiple interacting B-Bone chains.
+This is developed as the base for a new modular Rigify face rig.
+These are the main ideas of the system:
+
+Generic B-Bone Chain
+   One core idea of the system is that most of the deformation should be implemented
+   using a standard powerful B-Bone chain rig. These chains support advanced behavior by
+   interacting with other rig components. This is in contrast to having multiple domain-specific rigs
+   that each generate their own deform chains.
+
+   The implementation provides two versions of the chain rig: `skin.basic_chain`_ merely
+   attaches B-Bones to the controls with no automation added to the controls themselves.
+   The `skin.stretchy_chain`_ rig in addition interpolates motion of the end (and an optional middle)
+   controls to the other controls of the chain.
+
+Automatic Control Merging
+   The deformation part of the system consists of chains of one or more B-Bones connecting
+   control points (nodes). Whenever controls for two chains would completely overlap,
+   they are automatically merged.
+
+   For each merged control, one of the chains is selected as the owner, based on heuristic factors
+   like parent depth from root, presence of ``.T``/``.B`` ``.L``/``.R`` symmetry markers,
+   and even alphabetical order as the last resort. This can be overridden by an explicit priority setting
+   in cases when it guesses wrong.
+
+   The owner and its parents determine additional automation that is placed on the control.
+   As a special case, if a control is merged with its ``.T``/``.B`` ``.L``/``.R`` symmetry counterparts
+   (detected purely by naming), the automation from all of the symmetry siblings
+   of the owner is averaged.
+
+.. _rigify.rigs.skin.skin_parents:
+
+Parent Controllers
+   Rather than simply using the parent meta-rig bone (ORG) as parent for controls and chain mechanisms,
+   the new system includes an interface for parent rigs. It explicitly provide parent bones and generate control
+   parent automation mechanisms for their child chain controls by inheriting from the appropriate base
+   and overriding methods.
+
+   This allows implementing rigs that integrate and manage their child chains in intelligent ways in order
+   to add extra automation specific to certain areas. The base skin system includes one simple example
+   `skin.transform.basic`_ rig, which translates its child control points according to
+   its control bone transformation.
+
+Custom Rigging
+   Finally, the new system provides ways to integrate with custom automation directly included in the meta-rig
+   via two extra rig components.
+
+   The `skin.anchor`_ rig generates a single control with inherited constraints etc., similar to
+   :ref:`basic.super_copy <rigify.rigs.basic.super_copy>`. However, it also integrates into the skin system
+   as a zero length chain with highest priority. This allows overriding the normal behavior by providing
+   a control point under full control of the user, which other chains would automatically attach to.
+
+   The `skin.glue`_ rig on the other hand will attach itself to the control that is generated at
+   its position (it is an error if there is none). It can be used to read the position of the control
+   from custom rigging in the meta-rig, or inject constraints into the control bone. It is possible to
+   also detect the control at the tail of the glue bone and use it as target in the constraints,
+   thus copying transformation between the controls.
+
+
+.. _rigify.rigs.skin.basic_chain:
+
+skin.basic_chain
+================
+
+This is the basic chain rig, which bridges controls with B-Bones but does not add
+any automation to the controls themselves.
+
+When controls are merely moved, the chains behave as if using standard
+automatic handles, but rotating and optionally scaling the controls will adjust the result.
+
+B-Bone Segments
+   Specifies the number of segments to use. Setting this to 1 disables
+   all advanced behavior and merely bridges the points with a Stretch To bone.
+Merge Parent Rotation and Scale
+   This can be enabled to let the chain respond to rotation and scale induced by parents of
+   controls owned by other chains that this chain's control merged into.
+Use Handle Scale
+   Enables using control scale to drive scale and/or easing of the B-Bone.
+Connect With Mirror
+   Specifies whether the ends of the chain should smoothly connect when merging controls
+   with its ``.T``/``.B`` ``.L``/``.R`` symmetry counterpart. The relevant option must be enabled
+   on both chains to work.
+Connect Matching Ends
+   Specifies whether the end of the chain should connect to the opposite end of a different chain
+   when merging controls. Thus forming a continuous smooth chain in the same direction.
+   The relevant options must be enabled on both chains.
+Sharpen Corner
+   Specifies whether the rig should generate a mechanism to form a sharp corner at
+   the relevant connected end, depending on the angle formed by adjacent control locations.
+   When the control angle becomes sharper than the specified value, ease starts reducing from 1 to 0.
+Orientation
+   Specifies that the controls should be oriented the same as the selected bone, rather than being
+   aligned to the chain.
+
+   Copy To Selected
+      Copy to selected rigs that have the same option. Thus allowing to indiscriminately selecting bones
+      without assigning unnecessary values.
+Chain Priority
+   Allows overriding the heuristic used to select the primary owner when merging controls.
+
+
+.. _rigify.rigs.skin.stretchy_chain:
+
+skin.stretchy_chain
+===================
+
+This rig extends the basic chain with automation that propagates movement of the start and end,
+and an optional middle control, to other controls. This results in stretching the whole chain
+when moving one of the ends, rather than just the immediately adjacent B-Bones.
+
+Middle Control Position
+   Specifies the position of the middle control within the chain; disabled when zero.
+Falloff
+   Specifies the influence falloff curves of the start, middle and end controls.
+   Zero results in linear falloff, increasing widens the influence, and -10 disables
+   the influence propagation from that control completely.
+Spherical Falloff
+   Toggle buttons to change the shape of the falloff curve from a power curve that at falloff 1 forms a parabola
+   :math:`1 - x^{2^f}` to a curve forming a circle :math:`(1 - x^{2^f})^{2^{-f}}`.
+Falloff Along Chain Curve
+   Computes the falloff curve along the length of the chain, instead of projecting on the straight
+   line connecting its start and end points.
+Propagate Twist
+   Specifies whether twist of the chain should be propagated to control points between main controls.
+Propagate Scale
+   Specifies whether perpendicular scaling of the chain should be propagated to control points between main controls.
+Propagate to Controls
+   Allows other chains to see propagated twist and scale via *Merge Parent Rotation and Scale* when their
+   controls are merged into this chain, instead of it being completely local to this chain.
+Primary Control Layers
+   Optionally specifies bone collections for the end controls.
+Secondary Control Layers
+   Optionally specifies bone collections for the middle control, falling back to *Primary Control Layers* if not set.
+
+The main controls with active falloff have the effect of *Merge Parent Rotation and Scale*
+automatically enabled just for them.
+
+
+.. _rigify.rigs.skin.anchor:
+
+skin.anchor
+===========
+
+This rig effectively acts as a zero-length chain with highest priority,
+ensuring that it becomes the owner when merging controls with other chains.
+And also allowing one to input custom automation influence into the skin system.
+
+All constraints on the meta-rig bone are moved to the created control.
+
+Generate Deform Bone
+   Creates a deformation bone parented to the control.
+Suppress Control
+   Makes the control a hidden mechanism bone to hide it from the user.
+Widget Type
+   Selects which widget to generate for the control.
+Relink Constraints
+   Operates the same as in :ref:`basic.raw_copy <rigify.rigs.basic.raw_copy>`,
+   except all constraints are moved from ORG to the control bone.
+Orientation
+   Specifies the bone used to orient the control, like for other chains.
+
+
+.. _rigify.rigs.skin.glue:
+
+skin.glue
+=========
+
+This rig is in concept similar to `skin.anchor`_, but instead of overriding controls,
+it is used to read or adjust the state of controls generated by other rigs.
+The head of the bone must overlap a control of another skin rig.
+
+The rig sets up its ORG bone to read the state of the control,
+while moving all constraints that were originally on the bone to the control.
+
+Glue Mode
+   Specifies how the ORG bone is connected to the skin control.
+
+   Child Of Control
+      Makes the ORG bone a child of the control bone.
+   Mirror Of Control
+      Makes the ORG bone a sibling of the control with a Copy Transforms constraint from the control.
+      The resulting local space transformation is the same as control's local space.
+   Mirror With Parents
+      Parents the ORG bone to the parent automation a control owned by
+      the glue rig would have had, while making it follow the actual control.
+      This includes both direct and parent-induced motion of the control into
+      the local space transformation of the bone.
+   Deformation Bridge
+      Other than adding glue constraints to the control, the rig acts as a one segment basic deform chain.
+      This is convenient when a pair of controls need to be bridged both with glue and a deform bone.
+
+Relink Constraints
+   Operates the same as in :ref:`basic.raw_copy <rigify.rigs.basic.raw_copy>`,
+   except all constraints are moved from ORG to the control bone.
+Use Tail Target
+   Relinks ``TARGET`` or any constraints with an empty target bone and no relink specification
+   to reference the control located at the tail of the glue bone.
+Target Local With Parents
+   Switches the tail target to operate similarly to *Mirror With Parents*.
+Add Constraint
+   Allows to add a typical glue constraints with specific *Influence*, as if it were at
+   the start of the ORG bone constraint stack.
+
+
+.. _rigify.rigs.skin.transform.basic:
+
+skin.transform.basic
+====================
+
+This rig provides a simplistic :ref:`parent controller <rigify.rigs.skin.skin_parents>`, which uses regular
+translation, rotation, or scale to modify locations but not orientations or scale of its child chain controls.
+
+Generate Control
+   Specifies whether to generate a visible control, or use the transformation of the ORG bone
+   as a part of more complex and specific rig setup.

manual/addons/rigging/rigify/rig_types/spines.rst

@@ -0,0 +1,92 @@
+
+******
+Spines
+******
+
+These rigs are used to generate spine structures, including the head and tail.
+
+
+.. _rigify.rigs.spines.super_spine:
+
+spines.super_spine
+==================
+
+Will create a complete bendy and stretchy b-bones spine system based on bone numbers of
+your bone chain and user defined options.
+
+This is a composite wrapper of `spines.basic_spine`_, `spines.super_head`_ and `spines.basic_tail`_.
+Note that for the tail, the direction of the bones is reversed compared to the separate rig.
+
+Requirement: A chain of at least three connected bones (base system).
+
+.. figure:: /images/addons_rigging_rigify_rig-types_spines-required.png
+
+   Spine required bones.
+
+Pivot Position (integer)
+   Defines the pivot position for torso and hips.
+Head (Boolean)
+   When checked neck and head systems will be added to your spine rig.
+
+   Neck Position (integer)
+      Defines the bone where the neck system starts. The last bone will always be the head system.
+      If neck position is the last bone of the chain, then only the head system will be created ignoring the neck.
+Tail (Boolean)
+   When checked tail system will be added to your spine rig.
+
+   Tail Position (integer)
+      Defines the bone where the tail system starts. The next bone will always be the hips system.
+X, Y, Z (Boolean)
+   When generating a tail, specifies which local axis rotations should be replicated along the chain.
+Assign Tweak Layers
+   If enabled, allows placing the Tweak controls in different bone collections from the IK bones.
+
+.. figure:: /images/addons_rigging_rigify_rig-types_spines-default.png
+
+   Spine default bones.
+
+.. figure:: /images/addons_rigging_rigify_rig-types_spines-example.png
+
+   Spine with tail bones.
+
+
+.. _rigify.rigs.spines.basic_spine:
+
+spines.basic_spine
+==================
+
+Defines a bendy and stretchy b-bones spine.
+
+Pivot Position (integer)
+   Defines the pivot position for torso and hips.
+Assign Tweak Layers
+   If enabled, allows placing the Tweak controls in different bone collections from the IK bones.
+FK Controls
+   Specifies whether to generate an FK control chain.
+Assign FK Layers
+   If enabled, allows placing the FK chain in different bone collections from the IK bones.
+
+
+.. _rigify.rigs.spines.basic_tail:
+
+spines.basic_tail
+=================
+
+Defines a bendy and stretchy b-bones tail.
+
+X, Y, Z (Boolean)
+   Specifies which local axis rotations should be replicated along the chain from each control
+   bone to the following one.
+Assign Tweak Layers
+   If enabled, allows placing the Tweak controls in different bone collections from the IK bones.
+
+
+.. _rigify.rigs.spines.super_head:
+
+spines.super_head
+=================
+
+Defines a head rig with follow torso controls.
+
+Assign Tweak Layers
+   If enabled, allows placing the Tweak controls in different bone collections from the IK bones.

manual/advanced/blender_directory_layout.rst

@@ -4,172 +4,211 @@
 Blender's Directory Layout
 **************************
 
-This page documents the different directories used by Blender
-*(which can be helpful for troubleshooting)*.
+This page documents the different directories used by Blender.
 
-There are three different directories Blender may use,
-their exact locations are platform dependent.
-
-:LOCAL:
-   Location of configuration and run-time data (for self-contained bundle).
-:USER:
-   Location of configuration files (typically in the user's home directory).
-:SYSTEM:
-   Location of run-time data for system wide installation (may be read-only).
-
-For system installations both **SYSTEM** and **USER** directories are needed.
-
-For locally extracted Blender distributions, the user configuration and run-time data are
-kept in the same subdirectory, allowing multiple Blender versions to run without conflict,
-ignoring the **USER** and **SYSTEM** files.
-This requires you to create a folder named ``config`` in the **LOCAL** directory.
+This can be helpful for troubleshooting, automation and customization.
 
 
-Platform Dependent Paths
-========================
-
-Here are the default locations for each system:
+User Directories
+================
 
+User directories store preferences, startup file, installed extensions,
+presets and more. By default these use the standard configuration folders
+for each operating system.
 
 Linux
 -----
 
-:LOCAL:
-   .. parsed-literal:: ./|BLENDER_VERSION|/
-:USER:
-   .. parsed-literal:: $HOME/.config/blender/|BLENDER_VERSION|/
-:SYSTEM:
-   .. parsed-literal:: /usr/share/blender/|BLENDER_VERSION|/
+.. parsed-literal:: $HOME/.config/blender/|BLENDER_VERSION|/
 
-.. note::
-
-   The path |INSTALLDIR| is relative to the Blender executable and
-   is used for self-contained bundles distributed by official blender.org builds.
-
-.. |INSTALLDIR| replace:: ./|BLENDER_VERSION|/
-
-.. note::
-
-   The **USER** path will use ``$XDG_CONFIG_HOME`` if it is set:
-
-   .. parsed-literal:: $XDG_CONFIG_HOME/blender/|BLENDER_VERSION|/
+If the ``$XDG_CONFIG_HOME`` environment variable is set:
 
+.. parsed-literal:: $XDG_CONFIG_HOME/blender/|BLENDER_VERSION|/
 
 macOS
 -----
 
-:LOCAL:
-   .. parsed-literal:: ./|BLENDER_VERSION|/
-:USER:
-   .. parsed-literal:: /Users/$USER/Library/Application Support/Blender/|BLENDER_VERSION|/
-:SYSTEM:
-   .. parsed-literal:: /Library/Application Support/Blender/|BLENDER_VERSION|/
-
-.. note::
-
-   macOS stores the Blender binary in ``./Blender.app/Contents/MacOS/Blender``.
-   The local path to data and config is:
-
-   .. parsed-literal:: ./Blender.app/Contents/Resources/|BLENDER_VERSION|/
-
+.. parsed-literal:: /Users/$USER/Library/Application Support/Blender/|BLENDER_VERSION|/
 
 Windows
 -------
 
-:LOCAL:
-   .. parsed-literal:: .\\\ |BLENDER_VERSION|\\
-:USER:
-   .. parsed-literal:: %USERPROFILE%\\AppData\\Roaming\\Blender Foundation\\Blender\\\ |BLENDER_VERSION|\\
-:SYSTEM:
-   .. parsed-literal:: %USERPROFILE%\\AppData\\Roaming\\Blender Foundation\\Blender\\\ |BLENDER_VERSION|\\
+.. parsed-literal:: %USERPROFILE%\\AppData\\Roaming\\Blender Foundation\\Blender\\\ |BLENDER_VERSION|\\
 
-.. note::
+.. _portable-installation:
 
-   For installations from the Window's Store, the ``USER`` and ``SYSTEM``
-   directories are inside a special folder resembling:
+Portable Installation
+---------------------
 
-   .. parsed-literal:: %ProgramFiles%\\WindowsApps\\BlenderFoundation.Blender<HASH>\\Blender\\\ |BLENDER_VERSION|\\
+When running Blender from a portable drive, it's possible to keep the configuration
+files on the same drive to take with you.
 
-   Where "HASH" is a string specific to each installation.
+To enable this, create a folder named ``portable`` at the following locations:
 
+* Windows: Next to the Blender executable, in the unzipped folder
+* Linux: Next to the Blender executable, in the unzipped folder
+* macOS: Inside the application bundle at ``Blender.app/Contents/Resources``
+
+This folder will then store preferences, startup file, installed extensions
+and presets.
+
+Environment Variables
+---------------------
+
+The ``BLENDER_USER_RESOURCES`` :ref:`environment variable <command-line-args-environment-variables>`
+can be set to a custom directory to replace the default user directory.
+
+System Directories
+==================
+
+System directories store files that come bundled with Blender and
+are required for it to function. This includes scripts, presets, essential
+assets and more.
+
+Linux
+-----
+
+Archive downloaded from blender.org:
+
+.. parsed-literal:: ./|BLENDER_VERSION|/
+
+Linux distribution packages:
+
+.. parsed-literal:: /usr/share/blender/|BLENDER_VERSION|/
+
+macOS
+-----
+
+.. parsed-literal:: ./Blender.app/Contents/Resources/|BLENDER_VERSION|/
+
+Windows
+-------
+
+Zip file downloaded from blender.org:
+
+.. parsed-literal:: ./|BLENDER_VERSION|/
+
+Installer downloaded from blender.org:
+
+.. parsed-literal:: %ProgramFiles%\\Blender Foundation\\Blender\\\ |BLENDER_VERSION|\\
+
+Microsoft Store installation:
+
+.. parsed-literal:: %ProgramFiles%\\WindowsApps\\BlenderFoundation.Blender<HASH>\\Blender\\\ |BLENDER_VERSION|\\
+
+
+Environment Variables
+---------------------
+
+``BLENDER_SYSTEM_SCRIPTS`` and ``BLENDER_SYSTEM_EXTENSIONS``
+:ref:`environment variables <command-line-args-environment-variables>`
+can be used to :ref:`bundle additional scripts and extensions <deploying-blender-bundling>`,
+that are not part of the regular Blender installation.
+
+Other ``BLENDER_SYSTEM`` environment variables can override other system paths,
+though are not commonly used in practice.
+
+.. _blender-directory-path-layout:
 
 Path Layout
 ===========
 
-This is the path layout which is used within the directories described above.
+``./autosave``
+  Autosave blend-file location. (Windows only, temp directory used for other systems.)
 
-Where ``./config/startup.blend`` could be ``~/.blender/|BLENDER_VERSION|/config/startup.blend`` for example.
+  Located in user directories.
 
-``./autosave/ ...``
-   Autosave blend-file location. (Windows only, temp directory used for other systems.)
+``./config``
+  User configuration and session info.
 
-   Search order: ``LOCAL, USER``.
+  Located in user directories.
 
-``./config/ ...``
-   Defaults & session info.
+  ``./config/startup.blend``
+    Blend file to load on startup.
 
-   Search order: ``LOCAL, USER``.
+  ``./config/userpref.blend``
+    User preferences.
 
-``./config/startup.blend``
-   Default file to load on startup.
+  ``./config/bookmarks.txt``
+    File Browser bookmarks.
 
-``./config/userpref.blend``
-   Default preferences to load on startup.
+  ``./config/recent-files.txt``
+    Recent file menu list.
 
-``./config/bookmarks.txt``
-   File Browser bookmarks.
+  ``./config/{APP_TEMPLATE_ID}/startup.blend``
+    Startup file for an application template.
 
-``./config/recent-files.txt``
-   Recent file menu list.
+  ``./config/{APP_TEMPLATE_ID}/userpref.blend``
+    User preferences file for an application template.
 
-``./datafiles/ ...``
-   Runtime files.
+``./datafiles``
+  Data files loaded at runtime.
 
-   Search order: ``LOCAL, USER, SYSTEM``.
+  Located in both user and system directories. User data files either override
+  or add to system data files.
 
-``./datafiles/locale/{language}/``
-   Static precompiled language files for UI translation.
+  ``./datafiles/colormanagement``
+    Default OpenColorIO configuration.
 
-``./scripts/ ...``
-   Python scripts for the user interface and tools.
+  ``./datafiles/fonts``
+    User interface fonts.
 
-   Search order: ``LOCAL, USER, SYSTEM``.
+  ``./datafiles/studiolights``
+    Studio light images for 3D viewport.
 
-``./scripts/addons/*.py``
-   Python add-ons which may be enabled in the Preferences include import/export format support,
-   render engine integration and many handy utilities.
+``./extensions``
+  Extension repositories.
 
-``./scripts/addons/modules/*.py``
-   Modules for add-ons to use
-   (added to Python's ``sys.path``).
+  Located in both user and system directories. Repositories are loaded from
+  both directories.
 
-``./scripts/addons_core/*.py``
-   The add-ons directory which is used for bundled add-ons.
+``./scripts``
+  Add-ons, presets, templates, user interface, startup scripts.
 
-``./scripts/addons_core/modules/*.py``
-   Modules for ``addons_core`` to use (added to Python's ``sys.path`` when it found).
+  Located in both user and system directories. Scripts are loaded from
+  both directories.
 
-``./scripts/modules/*.py``
-   Python modules containing our core API and utility functions for other scripts to import
-   (added to Python's ``sys.path``).
+  ``./scripts/addons/*.py``
+    Python add-ons which may be enabled in the Preferences include import/export format support,
+    render engine integration and many handy utilities.
 
-``./scripts/startup/*.py``
-   Scripts which are automatically imported on startup.
+  ``./scripts/addons/modules/*.py``
+    Modules for add-ons to use
+    (added to Python's ``sys.path``).
 
-``./scripts/presets/{preset}/*.py``
-   Presets used for storing user-defined settings for cloth, render formats, etc.
+  ``./scripts/addons_core/*.py``
+    The add-ons directory which is used for bundled add-ons.
 
-``./scripts/templates_py/*.py``
-   Example scripts which can be accessed from :menuselection:`Text Editor --> Templates --> Python`.
+  ``./scripts/addons_core/modules/*.py``
+    Modules for ``addons_core`` to use (added to Python's ``sys.path`` when it found).
 
-``./scripts/templates_osl/*.osl``
-   Example OSL shaders which can be accessed from
-   :menuselection:`Text Editor --> Templates --> Open Shading Language`.
+  ``./scripts/modules/*.py``
+    Python modules containing our core API and utility functions for other scripts to import
+    (added to Python's ``sys.path``).
 
-``./python/ ...``
-   Bundled Python distribution.
+  ``./scripts/startup/*.py``
+    Scripts which are automatically imported on startup.
 
-   Search order: ``LOCAL, SYSTEM``.
+    ``./scripts/startup/bl_app_templates_user/{APP_TEMPLATE_ID}``
+      Application templates installed in user directories.
+
+    ``./scripts/startup/bl_app_templates_system/{APP_TEMPLATE_ID}``
+       pplication templates automatically loaded from system directories.
+
+  ``./scripts/presets/{preset}/*.py``
+    Presets used for storing user-defined settings for cloth, render formats, etc.
+
+  ``./scripts/templates_py/*.py``
+    Example scripts which can be accessed from :menuselection:`Text Editor --> Templates --> Python`.
+
+  ``./scripts/templates_osl/*.osl``
+    Example OSL shaders which can be accessed from
+    :menuselection:`Text Editor --> Templates --> Open Shading Language`.
+
+``./python``
+  Bundled Python distribution.
+
+  Located in system directories.
 
 
 .. _local-cache-dir:
@@ -200,16 +239,3 @@ The temporary directory is selected based on the following priority:
 - User Preference (see :ref:`prefs-file-paths`).
 - Environment variables (``TEMP`` on Windows, ``TMP`` & ``TMP_DIR`` on other platforms).
 - The ``/tmp/`` directory.
-
-
-Overriding Default Directories
-==============================
-
-It's possible to override the default **USER** and **SYSTEM** directories using environment variables.
-
-While this shouldn't be needed for typical usage, some specialized use cases may take advantage of this, such as:
-
-- Using a shared network drives for specific paths.
-- Isolating an instance from the default user files to prevent automated tasks from accessing user configuration.
-
-See :ref:`command-line-args-environment-variables` for details.

manual/advanced/command_line/arguments.rst

@@ -371,6 +371,9 @@ GPU Options
 ``--gpu-backend``
    Force to use a specific GPU backend. Valid options: ``vulkan`` (experimental),  ``metal``,  ``opengl``.
 
+``--gpu-compilation-subprocesses``
+   Override the Max Compilation Subprocesses setting (OpenGL only).
+
 
 .. _command-line-args-misc-options:
 
@@ -396,6 +399,9 @@ Misc Options
 ``--env-system-scripts``
    Set the ``BLENDER_SYSTEM_SCRIPTS`` environment variable.
 
+``--env-system-extensions``
+   Set the ``BLENDER_SYSTEM_EXTENSIONS`` environment variable.
+
 ``--env-system-python``
    Set the ``BLENDER_SYSTEM_PYTHON`` environment variable.
 
@@ -484,18 +490,18 @@ Arguments are executed in the order they are given. eg:
 Environment Variables
 =====================
 
-:BLENDER_USER_RESOURCES:  Top level directory for user files.
-                         (other ``BLENDER_USER_*`` variables override when set).
+:BLENDER_USER_RESOURCES:  Replace default directory of all user files.
+                         Other ``BLENDER_USER_*`` variables override when set.
 :BLENDER_USER_CONFIG:     Directory for user configuration files.
 :BLENDER_USER_SCRIPTS:    Directory for user scripts.
 :BLENDER_USER_EXTENSIONS: Directory for user extensions.
 :BLENDER_USER_DATAFILES:  Directory for user data files (icons, translations, ..).
 
-:BLENDER_SYSTEM_RESOURCES:  Top level directory for system files.
-                           (other ``BLENDER_SYSTEM_*`` variables override when set).
-:BLENDER_SYSTEM_SCRIPTS:    Directory for system wide scripts.
-:BLENDER_SYSTEM_DATAFILES:  Directory for system wide data files.
-:BLENDER_SYSTEM_PYTHON:     Directory for system Python libraries.
+:BLENDER_SYSTEM_RESOURCES:  Replace default directory of all bundled resource files.
+:BLENDER_SYSTEM_SCRIPTS:    Directory to add more bundled scripts.
+:BLENDER_SYSTEM_EXTENSIONS: Directory for system extensions repository.
+:BLENDER_SYSTEM_DATAFILES:  Directory to replace bundled datafiles.
+:BLENDER_SYSTEM_PYTHON:     Directory to replace bundled Python libraries.
 :OCIO:                      Path to override the OpenColorIO configuration file.
 :TEMP:                      Store temporary files here (MS-Windows).
 :TMPDIR:                    Store temporary files here (UNIX Systems).

manual/advanced/command_line/extension_arguments.rst

@@ -119,7 +119,7 @@ usage::
        blender --command extension install-file [-h] -r REPO [-e] [--no-prefs]
                                                 FILE
 
-Install a package file into a local repository.
+Install a package file into a user repository.
 
 positional arguments:
   :FILE:                  The packages file.
@@ -179,8 +179,11 @@ usage::
 
        blender --command extension repo-add [-h] [--name NAME]
                                             [--directory DIRECTORY]
-                                            [--url URL] [--cache BOOLEAN]
-                                            [--clear-all] [--no-prefs]
+                                            [--url URL]
+                                            [--access-token ACCESS_TOKEN]
+                                            [--source SOURCE]
+                                            [--cache BOOLEAN] [--clear-all]
+                                            [--no-prefs]
                                             ID
 
 Add a new local or remote repository.
@@ -198,6 +201,10 @@ options:
                         When omitted the repository is considered "local"
                         as it is not connected to an external repository,
                         where packages may be installed by file or managed manually.
+  --access-token ACCESS_TOKEN
+                        The access token to use for remote repositories which require a token.
+  --source SOURCE       The type of source in ('USER', 'SYSTEM').
+                        System repositories are managed outside of Blender and are considered read-only.
   --cache BOOLEAN       Use package cache (default=1).
   --clear-all           Clear all repositories before adding, simplifies test setup.
   --no-prefs            Treat the user-preferences as read-only,
@@ -238,6 +245,8 @@ usage::
        blender --command extension build [-h] [--source-dir SOURCE_DIR]
                                          [--output-dir OUTPUT_DIR]
                                          [--output-filepath OUTPUT_FILEPATH]
+                                         [--valid-tags VALID_TAGS_JSON]
+                                         [--split-platforms] [--verbose]
 
 Build a package in the current directory.
 
@@ -254,7 +263,23 @@ options:
   --output-filepath OUTPUT_FILEPATH
                         The package output filepath (should include a ``.zip`` extension).
 
-                        Defaults to a name created using the ``id`` from the manifest.
+                        Defaults to ``{id}-{version}.zip`` using values from the manifest.
+  --valid-tags VALID_TAGS_JSON
+                        Reference a file path containing valid tags lists.
+
+                        If you wish to reference custom tags a ``.json`` file can be used.
+                        The contents must be a dictionary of lists where the ``key`` matches the extension type.
+
+                        For example:
+                           ``{"add-ons": ["Example", "Another"], "theme": ["Other", "Tags"]}``
+
+                        To disable validating tags, pass in an empty path ``--valid-tags=""``.
+  --split-platforms     Build a separate package for each platform.
+                        Adding the platform as a file name suffix (before the extension).
+
+                        This can be useful to reduce the upload size of packages that bundle large
+                        platform-specific modules (``*.whl`` files).
+  --verbose             Include verbose output.
 
 .. _command-line-args-extension-validate:
 
@@ -263,18 +288,30 @@ Subcommand: ``validate``
 
 usage::
 
-       blender --command extension validate [-h] [SOURCE_PATH]
+       blender --command extension validate [-h]
+                                            [--valid-tags VALID_TAGS_JSON]
+                                            [SOURCE_PATH]
 
 Validate the package meta-data in the current directory.
 
 positional arguments:
-  :SOURCE_PATH:  The package source path (either directory containing package files or the package archive).
-               This path must containing a ``blender_manifest.toml`` manifest.
+  :SOURCE_PATH:           The package source path (either directory containing package files or the package archive).
+                        This path must containing a ``blender_manifest.toml`` manifest.
 
-               Defaults to the current directory.
+                        Defaults to the current directory.
 
 options:
-  -h, --help   show this help message and exit
+  -h, --help            show this help message and exit
+  --valid-tags VALID_TAGS_JSON
+                        Reference a file path containing valid tags lists.
+
+                        If you wish to reference custom tags a ``.json`` file can be used.
+                        The contents must be a dictionary of lists where the ``key`` matches the extension type.
+
+                        For example:
+                           ``{"add-ons": ["Example", "Another"], "theme": ["Other", "Tags"]}``
+
+                        To disable validating tags, pass in an empty path ``--valid-tags=""``.
 
 .. _command-line-args-extension-server-generate:
 
@@ -284,10 +321,37 @@ Subcommand: ``server-generate``
 usage::
 
        blender --command extension server-generate [-h] --repo-dir REPO_DIR
+                                                   [--repo-config REPO_CONFIG]
+                                                   [--html]
+                                                   [--html-template HTML_TEMPLATE_FILE]
 
 Generate a listing of all packages stored in a directory.
 This can be used to host packages which only requires static-file hosting.
 
 options:
-  -h, --help           show this help message and exit
-  --repo-dir REPO_DIR  The remote repository directory.
+  -h, --help            show this help message and exit
+  --repo-dir REPO_DIR   The remote repository directory.
+  --repo-config REPO_CONFIG
+                        An optional server configuration to include information which can't be detected.
+                        Defaults to ``blender_repo.toml`` (in the repository directory).
+
+                        This can be used to defined blocked extensions, for example ::
+
+                           schema_version = "1.0.0"
+
+                           [[blocklist]]
+                           id = "my_example_package"
+                           reason = "Explanation for why this extension was blocked"
+                           [[blocklist]]
+                           id = "other_extenison"
+                           reason = "Another reason for why this is blocked"
+
+  --html                Create a HTML file (``index.html``) as well as the repository JSON
+                        to support browsing extensions online with static-hosting.
+  --html-template HTML_TEMPLATE_FILE
+                        An optional HTML file path to override the default HTML template with your own.
+
+                        The following keys will be replaced with generated contents:
+
+                        - ``${body}`` is replaced the extensions contents.
+                        - ``${date}`` is replaced the creation date.

manual/advanced/command_line/index.rst

@@ -1,13 +1,78 @@
+.. _command_line-index:
 
-################
-  Command Line
-################
+#######################################
+  Using Blender From The Command Line
+#######################################
+
+The *Console Window*, also called a *Terminal*, is an operating system text window that displays
+messages about Blender's operations, status, and internal errors.
+
+When Blender is manually started from a terminal,
+Blender output is shown in the *Console Window* it is started from.
+
+Use Cases:
+
+- For :ref:`rendering animation <command_line-render>`.
+- For automation and batch processing which require launching Blender
+  with different :ref:`arguments <command_line-args>`.
+- For Python development, to see the output of the ``print()`` function.
+- If Blender exits unexpectedly, the messages may indicate the cause or error.
+- When troubleshooting, to see the output of ``--debug`` messages.
+
+See: :ref:`command_line-launch-index`
+for specific instructions on launching Blender from the command line.
+
+.. tip:: Closing the Blender Console Window
+
+   Closing the *Console Window* will also close Blender, losing any unsaved work.
+
+
+Launching from the Command Line
+===============================
+
+.. toctree::
+   :hidden:
+
+   launch/index.rst
+
+- :doc:`launch/linux`
+- :doc:`launch/macos`
+- :doc:`launch/windows`
+
+
+Arguments
+=========
+
+.. toctree::
+   :hidden:
+
+   Arguments <arguments.rst>
+
+- :ref:`command-line-args-render-options`
+- :ref:`command-line-args-cycles-render-options`
+- :ref:`command-line-args-format-options`
+- :ref:`command-line-args-animation-playback-options`
+- :ref:`command-line-args-window-options`
+- :ref:`command-line-args-python-options`
+- :ref:`command-line-args-network-options`
+- :ref:`command-line-args-logging-options`
+- :ref:`command-line-args-debug-options`
+- :ref:`command-line-args-gpu-options`
+- :ref:`command-line-args-misc-options`
+
+
+Sub-Commands
+============
 
 .. toctree::
    :maxdepth: 2
-   :titlesonly:
 
-   introduction.rst
-   launch/index.rst
-   arguments.rst
+   extension_arguments.rst
+
+
+Workflows
+=========
+
+.. toctree::
+
    render.rst

manual/advanced/command_line/introduction.rst

@@ -1,26 +0,0 @@
-
-************
-Introduction
-************
-
-The *Console Window*, also called a *Terminal*, is an operating system text window that displays
-messages about Blender's operations, status, and internal errors.
-
-When Blender is manually started from a terminal,
-Blender output is shown in the *Console Window* it is started from.
-
-Use Cases:
-
-- For :ref:`rendering animation <command_line-render>`.
-- For automation and batch processing which require launching Blender
-  with different :doc:`arguments </advanced/command_line/arguments>`.
-- For Python development, to see the output of the ``print()`` function.
-- If Blender exits unexpectedly, the messages may indicate the cause or error.
-- When troubleshooting, to see the output of ``--debug`` messages.
-
-See: :ref:`command_line-launch-index`
-for specific instructions on launching Blender from the command line.
-
-.. tip:: Closing the Blender Console Window
-
-   Closing the *Console Window* will also close Blender, losing any unsaved work.

manual/advanced/command_line/launch/index.rst

@@ -5,7 +5,7 @@
 ###################################
 
 .. toctree::
-   :maxdepth: 1
+   :maxdepth: 2
 
    linux.rst
    macos.rst

manual/advanced/command_line/render.rst

@@ -1,8 +1,8 @@
 .. _command_line-render:
 
-**********************
-Command Line Rendering
-**********************
+*******************************
+Rendering From The Command Line
+*******************************
 
 In some situations we want to increase the render speed,
 access Blender remotely to render something or build scripts that use the command line.

manual/advanced/deploying_blender.rst

@@ -0,0 +1,165 @@
+.. _deploying-blender:
+
+*******************************
+Deploying Blender in Production
+*******************************
+
+This page contains tips for setting up Blender in environments
+such as animation studios and schools.
+
+These environments often have special requirements regarding
+security, automated deployment and customization.
+
+Installing Blender
+==================
+
+Blender downloads can be extracted to any directory on the system, as
+a self contained installation. Multiple Blender versions can
+co-exist on the same system, and deployment can be automated using
+standard file management tools.
+
+New Blender versions may add, remove or change functionality that
+affects the results of production files. For a given project, it is
+advisable to use a single :abbr:`LTS (Long-Term-Support)` version
+of Blender. LTS versions receive bug fixes for two years.
+
+
+Working Offline
+===============
+
+For security or other reasons, workstation may not have internet access.
+
+By default Blender does not access the internet, however this can be
+enabled in the System preferences with the
+:ref:`Online Access <bpy.types.PreferencesSystem.use_online_access>` option.
+
+Working offline can be enforced by running with the ``--offline-mode``
+:ref:`command line argument <command-line-args-network-options>`. Users
+will then be unable to enable online access in the preferences.
+
+.. note::
+
+    Add-ons that follow this setting will only connect to the internet if enabled.
+    However, Blender cannot prevent third-party add-ons from violating this rule.
+
+
+.. _deploying-blender-bundling:
+
+Bundling Extensions
+===================
+
+When working offline or in a more controlled environment, it may be useful
+to provide a set of extensions to all users. For this there is a default
+read-only System repository. This repository can for example be located
+on a read-only network drive or in a system directory.
+
+
+.. figure:: /images/advanced_deploying-blender_system-extensions.png
+
+   System repository
+
+The ``$BLENDER_SYSTEM_EXTENSIONS``
+:ref:`environment variable <command-line-args-environment-variables>`
+controls the default location. This should point to a directory, within
+which a ``system`` directory should exist.
+
+Extensions packages should be extracted in this ``system`` directory,
+with a resulting path like this:
+
+.. code-block:: bash
+
+    $BLENDER_SYSTEM_EXTENSIONS/system/my-addon/blender_manifest.toml
+
+In the Extensions preferences, it's possible to manually set a custom
+directory for the default System repository, or to create multiple
+repositories.
+
+
+Bundling Scripts
+================
+
+Besides extensions, it's possible to bundle scripts for presets,
+application templates, legacy add-ons, as well as scripts run on startup.
+
+Script directories can be manually added in the File Paths preferences.
+The ``$BLENDER_SYSTEM_SCRIPTS`` can also be used to add a script directory
+without modifying the preferences.
+
+These script directories are expected to contain specific directories
+like ``presets``, ``addons`` and ``startup`` for different types of
+scripts. See :ref:`blender-directory-path-layout` for a complete list.
+
+
+Startup Scripts
+---------------
+
+The Blender Python API can be used to customize Blender. This includes
+changing preferences, changing the startup file and adding UI elements.
+
+For example, a script can enable add-ons for every user.
+
+.. code-block:: bash
+
+    $BLENDER_SYSTEM_SCRIPTS/startup/enable_addons.py
+
+.. code-block:: python
+
+   def register():
+       import addon_utils
+       addon_utils.enable("my-addon")
+
+   def unregister():
+       pass
+
+   if __name__ == "__main__":
+       register()
+
+
+Application Templates
+---------------------
+
+:ref:`app_templates` can be used to set up Blender for particular
+tasks or projects, separate from the default configuration. When
+creating a new file the user can choose the template.
+
+The files are expected to be placed in the system script directories like this:
+
+.. code-block:: bash
+
+   $BLENDER_SYSTEM_SCRIPTS/startup/bl_app_templates_system/MyTemplate/__init__.py
+   $BLENDER_SYSTEM_SCRIPTS/startup/bl_app_templates_system/MyTemplate/startup.blend
+
+
+Legacy Add-ons
+--------------
+
+Add-ons that have not been converted to become an extension yet need
+to be placed in the ``addons`` script directory.
+
+For example, an add-on could be located at:
+
+.. code-block:: bash
+
+    $BLENDER_SYSTEM_SCRIPTS/addons/simple_addon.py
+    $BLENDER_SYSTEM_SCRIPTS/addons/complex_addon/__init__.py
+
+
+VFX Platform
+============
+
+Blender follows the `VFX reference platform <https://vfxplatform.com>`_,
+which means it is able to run on the same systems as other VFX software
+and exchange image, volume and scene files with them.
+
+
+Python Version
+--------------
+
+Blender and the `bpy module <https://pypi.org/project/bpy/>`_ are only compatible
+with a single Python version. This makes it possible for add-ons and VFX software
+in general to only have to target a single Python version.
+
+Blender bundles a complete Python installation and does not interact with the
+system Python by default. This can be changed with the ``--python-use-system-env``
+:ref:`command line argument <command-line-args-python-options>`, if care is
+taken to set up a compatible Python version.

manual/advanced/extensions/addons.rst

@@ -1,5 +1,4 @@
-.. Mark as "orphan" until extensions is out of beta.
-
+.. _extensions-addons:
 .. index:: Add-ons Extensions
 .. index:: Add-ons
 .. .. _bpy.types.Addon:
@@ -11,14 +10,15 @@ Add-ons
 *******
 
 *Add-ons* let you extend Blender's functionality using Python.
-Most of the time you can get add-ons as part of the :doc:`Extensions <index>` system.
+Most of the time you can get add-ons as part of the :ref:`Extensions <extensions-index>` system.
 
 .. tip::
 
    If the Add-on does not activate when enabled,
-   check the :doc:`Console window </advanced/command_line/introduction>`
+   check the :ref:`Console window <command_line-index>`
    for any errors that may have occurred.
 
+
 User-Defined Add-on Path
 ========================
 
@@ -39,14 +39,19 @@ Blender will copy newly installed add-ons under the directory selected in your P
 Internet Access
 ===============
 
-If the add-on needs to use internet, it should check for the (read-only) property ``bpy.app.online_access``.
+If the add-on needs to use internet, it must check for the (read-only) property ``bpy.app.online_access``.
 This option is controlled by Preferences, which can be overriding via command-line
 (``--offline-mode`` / ``--online-mode``).
 
 For better error messages, you can check also for ``bpy.app.online_access_overriden``,
-to determine whether users can turn ``Allow Online Access`` on the preferences, or not.
+to determine whether users can turn :ref:`Allow Online Access <bpy.types.PreferencesSystem.use_online_access>`
+on the preferences, or not.
+
+.. note::
+
+   Add-ons that follow this setting will only connect to the internet if enabled.
+   However, Blender cannot prevent third-party add-ons from violating this rule.
 
-Blender itself doesn't block internet access based on this setting. It is up to the add-ons to respect it.
 
 Bundle Dependencies
 ===================
@@ -56,7 +61,7 @@ That means they must come with all its dependencies. In particular 3rd party Pyt
 
 There are a few options for this:
 
-Bundle with :doc:`Python Wheels <./python_wheels>`.
+Bundle with :ref:`Python Wheels <extensions-python_wheels>`.
    This is the recommended way to bundle dependencies.
 
 Bundle other add-ons together.
@@ -72,6 +77,25 @@ Bundle with `Vendorize <https://pypi.org/project/vendorize>`__
 
    This has the advantage of avoiding version conflicts although it requires some work to setup each package.
 
+
+Local Storage
+=============
+
+Add-ons must not assume their own directory is user writable since this may not be the case for "System" repositories.
+Writing files into the add-on's directory also has the down side that upgrading the extension will remove all files.
+
+Add-ons which need their own user directory should use a utility function provided for this purpose:
+
+.. code-block:: python
+
+   extension_directory = bpy.utils.extension_path_user(__package__, path="", create=True)
+
+If you wish create subdirectories, this can be done with the ``path`` argument.
+
+This directory will be kept between upgrades but will be removed if the extension is uninstalled.
+
+
+.. This section is reference for legacy add-on installation.
 .. _bpy.ops.preferences.addon_install:
 
 Legacy vs Extension Add-ons
@@ -81,16 +105,17 @@ With the introduction of Extensions in Blender 4.2, the old way of creating add-
 While the changes are rather small they impact existing add-ons.
 
 In order to allow a smooth transition process, the so-called legacy add-ons will continue to be supported by Blender.
-They can be installed via :doc:`Install legacy Add-on </editors/preferences/extensions>` button in the User
+They can be installed via :ref:`Install legacy Add-on <prefs-extensions-install_legacy_addon>` button in the User
 Preferences.
 
 All add-on maintainers are urged to convert the add-ons they want to share, so they are future proof and can support
 features like updating from the extensions platform.
 
+
 Converting a Legacy Add-on into an Extension
 --------------------------------------------
 
-#. Create a :doc:`manifest file <./getting_started>`.
+#. Create a :ref:`manifest file <extensions-getting_started>`.
 #. Remove the ``bl_info`` information (this is now in the manifest).
 #. Replace all references to the module name to ``__package__``.
 #. Make all module imports to use relative import.
@@ -99,9 +124,10 @@ Converting a Legacy Add-on into an Extension
 
 .. note::
 
-   For testing it is import to :doc:`install the extension from disk </editors/preferences/extensions>` and check if
+   For testing it is import to :ref:`install the extension from disk <prefs-extensions>` and check if
    everything is working well. This will get you as close to the final experience as possible.
 
+
 Extensions and Namespace
 ------------------------
 
@@ -113,6 +139,7 @@ For example, now instead of ``kitsu`` the module name would be ``bl_ext.{reposit
 
 This has a few implications for preferences and module imports.
 
+
 User Preferences and ``__package__``
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 

manual/advanced/extensions/creating_repository/dynamic_repository.rst

@@ -0,0 +1,47 @@
+.. _extensions-create_repo-dynamic:
+
+****************************************
+Creating a Dynamic Extensions Repository
+****************************************
+
+A dynamic repository allows you to serve a smaller JSON file with only the latest version of the extensions which are
+compatible with the query parameters. This is only relevant for repositories which contain multiple version of
+multiple extensions.
+
+For small or personal repositories it is simpler and recommended to use :doc:`static repositories <static_repository>` 
+instead.
+
+Listing
+=======
+
+To setup a dynamic extensions repository, follow the steps for :doc:`static repositories <static_repository>`, since
+the format and the listing are the same.
+
+Query Parameters
+================
+
+When Blender fetches the extensions listing it passes the following arguments to make sure only
+compatible extensions are listed:
+
+- ``platform``
+- ``blender_version``
+
+These arguments are passed as parameters to the server via a query URL:
+
+   :URL: ``https://extensions.blender.org/api/v1/extensions/``
+   :query URL: ``https://extensions.blender.org/api/v1/extensions/?blender_version=4.2.0&platform=linux-x64``
+
+
+Access Token
+============
+
+Some repositories may require authentication. The user can specify an ``access token`` for a repository,
+which is passed along with the API request from Blender.
+
+This is passed to the servers via an Authorization header:
+
+.. code-block:: sh
+
+  curl -i https://extensions.blender.org/api/v1/extensions/ \
+    -H "Accept: application/json" \
+    -H "Authorization: Bearer abc29832befb92983423abcaef93001"

manual/advanced/extensions/creating_repository/index.rst

@@ -0,0 +1,30 @@
+.. _extensions-create_repo-index:
+
+*********************************
+Creating an Extensions Repository
+*********************************
+
+Third party sites that wish to support extensions in Blender can do so in several ways, in order of complexity:
+
+* :doc:`Static <static_repository>`: Host a static JSON file listing all the packages of your repository.
+* :doc:`Dynamic <dynamic_repository>`: Serve the JSON file on-demand based on the Blender version and platform.
+* `Platform <https://projects.blender.org/infrastructure/extensions-website>`__: Fork the entire Extensions Website to
+  create your own.
+
+Tags and Translations
+=====================
+
+If you are planning to use a different set of :ref:`tags <extensions-tags>` than the ones used by
+Blender Extensions Platform, remember to submit a pull request to
+`tags.py <https://projects.blender.org/blender/blender/src/scripts/modules/_bpy_internal/extensions/tags.py>`__.
+
+This way they can be shown translated within Blender.
+
+Sub-Pages
+=========
+
+.. toctree::
+   :maxdepth: 1
+
+   Static Repository <static_repository.rst>
+   Dynamic Repository <dynamic_repository.rst>

manual/advanced/extensions/creating_repository/static_repository.rst

@@ -0,0 +1,99 @@
+.. _extensions-create_repo-static:
+
+***************************************
+Creating a Static Extensions Repository
+***************************************
+
+To host your own extensions and leverage Blender update system all that is required is to host a static JSON file that
+is generated by Blender.
+
+JSON
+====
+
+To generate a valid JSON file use the :ref:`server generate <command-line-args-extension-server-generate>` Blender
+command-line tool:
+
+.. code:: bash
+
+   blender --command extension server-generate --repo-dir=/path/to/packages
+
+This creates an ``index.json`` listing from all the .zip extensions found in the `--repo-dir` location.
+
+For more details, read the generated JSON 
+`API <https://developer.blender.org/docs/features/extensions/api_listing/>`__.
+
+
+Testing
+-------
+
+To test the generated repository, add a new Remote Repository from the Preferences:
+
+- Get Extensions → Repositories → [+] → Add Remote Repository
+- Paste the location of the generated JSON as the URL.
+  So the example ``/path/to/packages`` would use the:
+
+  - ``file:///path/to/packages/index.json`` on Linux and macOS.
+  - ``file:///C:/path/to/packages/index.json`` on Windows.
+  - ``file://HOST/share/path/to/packages/index.json`` for network shares on Windows.
+
+.. tip::
+
+   Open ``file:///`` in a web browser and navigate to the repository location and copy that as the remote repository
+   URL.
+
+
+Extensions Listing HTML
+=======================
+
+The ``server-generate`` command can optionally create a simple website using the ``--html`` argument.
+
+.. code:: bash
+
+   blender --command extension server-generate --repo-dir=/path/to/packages --html
+
+This creates an ``index.html`` file ready to use, listing extensions which
+can be dropped into Blender for installation.
+
+
+Download Links
+--------------
+
+In order to support drag and drop for installing from a remote repository,
+there are a few optional ways to prepare the URLs.
+
+The only strict requirement is that the download URL must end in ``.zip``.
+
+You can pass different arguments to the URL to give more clues to Blender about what to do with the dropped URL.
+
+   :repository:
+      Link to the JSON file to be used to install the repository in Blender.
+      Supports relative URLs.
+   :platforms:
+      Comma-separated list of supported platforms.
+      If omitted, the extension will be available in all operating systems.
+   :blender_version_min:
+      Minimum supported Blender version, e.g., ``4.2.0``.
+   :blender_version_max:
+      Blender version that the extension does not support, earlier versions are supported.
+
+
+.. tip::
+
+   The more details you provide, the better the user experience.
+
+With the exception of the ``repository``, all the other parameters can be extracted from the extensions manifest.
+Those arguments are to be encoded as part of the URL.
+
+Expected format:
+   ``{URL}.zip?repository={repository}&blender_version_min={version_min}&blender_max=
+   {version_max_exclusive}&platforms={platform1,platform2}``
+
+Example from self-hosted repository:
+   ``http://my-site.com/my-addon.zip?repository=.%2Findex.json&blender_version_min=4.2.0&platforms=windows-x64``
+
+Example from the Extensions Platform:
+   ``https://extensions.blender.org/download/sha256:57a6a5f39fa2cc834dc086a27b7b2e572c12fd14f8377fb8bd1c7022df3d7ccb/add-on-amaranth-v1.0.23.zip?repository=%2Fapi%2Fv1%2Fextensions%2F&blender_version_min=4.2.0&platforms=linux-x64%2Cmacos-x64``
+
+   .. note::
+
+      ``%2F`` and ``%2C`` are simply the url-encoded equivalent of ``/`` and ``,`` respectively.

manual/advanced/extensions/getting_started.rst

@@ -1,3 +1,4 @@
+.. _extensions-getting_started:
 .. index:: Extensions
 
 ************************
@@ -6,11 +7,14 @@ How to Create Extensions
 
 Creating an extension takes only a few steps:
 
-#. Create a directory for your extension and populate it with the add-on code or theme file.
+#. Open the directory containing the add-on code or theme file.
 #. Add a `blender_manifest.toml <#manifest>`__  file with all the required meta-data ``(name, maintainer, ...)``.
-#. Compress the directory as a ``.zip`` file.
-#. :doc:`Install from Disk </editors/preferences/extensions>` to test if everything is working well.
-#. `Upload the zip file <https://extensions.blender.org/submit/>`__ (this step requires Blender ID).
+#. Use the :ref:`Blender command-line tool <command-line-args-extension-build>` to build the extension .zip file.
+
+How to publish to the `Blender Extensions Platform <https://extensions.blender.org>`__:
+
+* :ref:`Install from Disk <prefs-extensions-install>` to test if everything is working well.
+* `Upload the .zip file <https://extensions.blender.org/submit/>`__ (this step requires Blender ID).
 
 The extension will be held for `review <https://extensions.blender.org/approval-queue/>`__,
 and published once the moderation team approves it.
@@ -24,7 +28,7 @@ The expected files depend on the extension type.
 Add-on extension
 ----------------
 
-:doc:`Add-ons <addons>` need at least the manifest and an ``__init__.py`` file,
+:ref:`Add-ons <extensions-addons>` need at least the manifest and an ``__init__.py`` file,
 while more complex add-ons have a few different .py files or wheels together.
 
 .. code-block:: text
@@ -81,7 +85,8 @@ This example is a good starting point to the ``blender_manifest.toml`` that shou
    tags = ["Animation", "Sequencer"]
 
    blender_version_min = "4.2.0"
-   # Optional: maximum supported Blender version
+   # # Optional: Blender version that the extension does not support, earlier versions are supported.
+   # # This can be omitted and defined later on the extensions platform if an issue is found.
    # blender_version_max = "5.1.0"
 
    # License conforming to https://spdx.org/licenses/ (use "SPDX: prefix)
@@ -106,60 +111,63 @@ This example is a good starting point to the ``blender_manifest.toml`` that shou
    #   "./wheels/jsmin-3.0.1-py3-none-any.whl",
    # ]
 
-   ## Optional: add-ons can list which resources they will require:
-   ## * files (for access of any filesystem operations)
-   ## * network (for internet access)
-   ## * clipboard (to read and/or write the system clipboard)
-   ## * camera (to capture photos and videos)
-   ## * microphone (to capture audio)
-   ##
-   ## If using network, remember to also check `bpy.app.online_access`
-   ## https://docs.blender.org/manual/en/dev/advanced/extensions/addons.html#internet-access
-   ##
-   ## For each permission it is important to also specify the reason why it is required.
-   ## Keep this a single short sentence without a period (.) at the end.
-   ## For longer explanations use the documentation or detail page.
+   # # Optional: add-ons can list which resources they will require:
+   # # * files (for access of any filesystem operations)
+   # # * network (for internet access)
+   # # * clipboard (to read and/or write the system clipboard)
+   # # * camera (to capture photos and videos)
+   # # * microphone (to capture audio)
+   # #
+   # # If using network, remember to also check `bpy.app.online_access`
+   # # https://docs.blender.org/manual/en/dev/advanced/extensions/addons.html#internet-access
+   # #
+   # # For each permission it is important to also specify the reason why it is required.
+   # # Keep this a single short sentence without a period (.) at the end.
+   # # For longer explanations use the documentation or detail page.
    #
    # [permissions]
    # network = "Need to sync motion-capture data to server"
    # files = "Import/export FBX from/to disk"
    # clipboard = "Copy and paste bone transforms"
 
-   # Optional: build setting.
+   # Optional: build settings.
    # https://docs.blender.org/manual/en/dev/advanced/extensions/command_line_arguments.html#command-line-args-extension-build
    # [build]
    # paths_exclude_pattern = [
-   #   "/.git/",
    #   "__pycache__/",
+   #   "/.git/",
+   #   "/*.zip",
    # ]
 
 Required values:
 
    :blender_version_min: Minimum supported Blender version - use at least ``4.2.0``.
    :id: Unique identifier for the extension.
-   :license: List of :doc:`licenses <licenses>`, use `SPDX license identifier <https://spdx.org/licenses/>`__.
+   :license: List of :ref:`licenses <extensions-licenses>`,
+      use `SPDX license identifier <https://spdx.org/licenses/>`__.
    :maintainer: Maintainer of the extension.
    :name: Complete name of the extension.
    :schema_version: Internal version of the file format - use ``1.0.0``.
-   :tagline: One-line short description - cannot end with punctuation.
+   :tagline: One-line short description, up to 64 characters - cannot end with punctuation.
    :type: "add-on", "theme".
    :version: Version of the extension - must follow `semantic versioning <https://semver.org/>`__.
 
 Optional values:
 
-   :blender_version_max: Maximum version of Blender that can run this.
+   :blender_version_max: Blender version that the extension does not support, earlier versions are supported.
    :website: Website for the extension.
    :copyright: Some licenses require a copyright, copyrights must be "Year Name" or "Year-Year Name".
-   :tags: List of tags. See the :doc:`list of available tags <./tags>`.
+   :tags: List of tags. See the :ref:`list of available tags <extensions-tags>`.
    :platforms:
       List of supported platforms. If omitted, the extension will be available in all operating systems.
       The available options are
       ["windows-x64", "windows-arm64", "macos-x64", "macos-arm64", "linux-x64"]
-   :wheels: List of relative file-paths :doc:`Python Wheels <./python_wheels>`.
+   :wheels: List of relative file-paths :ref:`Python Wheels <extensions-python_wheels>`.
    :permissions:
       Add-ons can list which resources they require. The available options are
       *files*, *network*, *clipboard*, *camera*, *microphone*.
-      Each permission should be followed by an explanation (short single-sentence with no end pontuation (.)).
+      Each permission should be followed by an explanation (short single-sentence, up to 64 characters, with no end
+      punctuation).
 
 Optional values for "build":
 
@@ -183,8 +191,14 @@ Optional values for "build":
       paths_exclude_pattern = [
         "__pycache__/",
         ".*",
+        "*.zip",
       ]
 
+Reserved:
+   These values **must not** be declared in a TOML and are reserved for internal use.
+
+   - ``[build.generated]``
+
 
 .. note::
 
@@ -198,10 +212,6 @@ Command-line
 
 Extensions can be built, validated & installed via command-line.
 
-.. note::
-
-   Extension commands currently require a daily build of Blender with extensions enabled in the preferences.
-
 To build the package defined in the current directory use the following commands:
 
 .. code:: bash
@@ -234,55 +244,4 @@ See :ref:`validate <command-line-args-extension-validate>` docs.
 Third party extension sites
 ===========================
 
-Third party sites that wish to support extensions in Blender can do so in two ways:
-
-#. Fork the entire `Extensions Website <https://projects.blender.org/infrastructure/extensions-website>`__
-   as a start point; or
-#. Host a JSON file listing all the packages of your repository.
-
-To generate a valid JSON file you can use the command-line tool:
-
-.. code:: bash
-
-   blender --command extension server-generate --repo-dir=/path/to/packages
-
-This creates a listing from all the packages found in the specified location.
-
-See :ref:`server-generate <command-line-args-extension-server-generate>` docs.
-
-Example of what the JSON is expected to look like:
-
-.. code:: json
-
-   {
-     "version": "v1",
-     "blocklist": [],
-     "data": [
-      {
-         "id": "blender_kitsu",
-         "name": "Blender Kitsu",
-         "tagline": "Pipeline management for projects collaboration",
-         "version": "0.1.5-alpha+f52258de",
-         "type": "add-on",
-         "archive_size": 856650,
-         "archive_hash": "sha256:3d2972a6f6482e3c502273434ca53eec0c5ab3dae628b55c101c95a4bc4e15b2",
-         "archive_url": "https://extensions.blender.org/add-ons/blender-kitsu/0.1.5-alpha+f52258de/download/",
-         "blender_version_min": "4.2.0",
-         "maintainer": "Blender Studio",
-         "tags": ["Pipeline"],
-         "license": ["SPDX:GPL-3.0-or-later"],
-         "website": "https://extensions.blender.org/add-ons/blender-kitsu/",
-         "schema_version": "1.0.0"
-      }
-      ]
-  }
-
-Just like for the manifest file, the optional fields (e.g., ``blender_version_max``) are either to have a value
-or should be omitted from the entries.
-
-For the official Extensions Platform, the ``website`` value is the page of the extension in the online platform.
-Even if the manifest points to the project specific website.
-
-.. note::
-
-   Any remote repository is expected to follow the latest `API <https://extensions.blender.org/api/swagger/>`__.
+If you want to host the extensions yourself, see the :ref:`extensions-create_repo-index` docs.

manual/advanced/extensions/index.rst

@@ -11,11 +11,6 @@ They are shared in online platforms, and can be installed and updated from withi
 The official extensions platform for the Blender project is `extensions.blender.org <https://extensions.blender.org>`__.
 Other third party sites can also be supported, as long as they follow the Extensions Platform specification.
 
-.. seealso::
-
-   For the extension settings, and how to manage them, refer to the
-   :doc:`User Preferences </editors/preferences/extensions>`.
-
 .. toctree::
    :maxdepth: 1
 
@@ -24,4 +19,15 @@ Other third party sites can also be supported, as long as they follow the Extens
    Supported tags <tags.rst>
    Add-ons <addons.rst>
    Python Wheels <python_wheels.rst>
-   Command Line Arguments <command_line_arguments.rst>
+   Creating a Repository <creating_repository/index.rst>
+
+.. seealso::
+
+   For extension add-on guidelines (requirements for ``extensions.blender.org``), refer to the
+   :ref:`Developer Handbook <https://developer.blender.org/docs/handbook/addons/guidelines/>`__.
+
+   For the extension settings, and how to manage them, refer to the
+   :ref:`User Preferences <prefs-extensions>`.
+
+   For managing extensions from the command line, refer to
+   :ref:`Extension Command Line Arguments <command_line-args-extensions>`.

manual/advanced/extensions/licenses.rst

@@ -1,3 +1,4 @@
+.. _extensions-licenses:
 .. index:: Licenses
 
 ******************

manual/advanced/extensions/python_wheels.rst

@@ -1,3 +1,4 @@
+.. _extensions-python_wheels:
 
 *************
 Python Wheels
@@ -80,3 +81,44 @@ Running
 
       import PIL
       print(PIL.__file__)
+
+
+Platform Builds
+===============
+
+Wheels can severely impact the size of an extension. To mitigate this, it is possible to build different
+extension zip files for each unique required platform.
+
+For this you need to use the ``--split-platforms`` option from the
+:ref:`build <command-line-args-extension-build>` command.
+
+.. code:: bash
+
+   blender --command extension build --split-platforms
+
+Example
+-------
+
+Manifest file excerpt:
+
+.. code-block:: toml
+
+   id = "my_addon_with_wheels"
+   version = "1.0.0"
+
+   platforms = ["windows-x64", "macos-x64"]
+   wheels = [
+      "./wheels/pillow-10.3.0-cp311-cp311-macosx_11_0_arm64.whl",
+      "./wheels/pillow-10.3.0-cp311-cp311-manylinux_2_28_x86_64.whl",
+      "./wheels/pillow-10.3.0-cp311-cp311-win_amd64.whl",
+   ]
+
+Generated files from ``--split-platforms``:
+
+- my_addon_with_wheels-1.0.0-windows_x64.zip
+- my_addon_with_wheels-1.0.0-macos_x64.zip
+
+.. note::
+
+   Even though there is a Linux-only wheel present, no Linux zip file is generated.
+   This happens because the ``platforms`` field only has Mac and Windows.

manual/advanced/extensions/tags.rst

@@ -1,3 +1,4 @@
+.. _extensions-tags:
 .. index:: Tags
 
 ***************
@@ -5,7 +6,8 @@ Extensions Tags
 ***************
 
 A different set of tags is available for the different extensions types.
-This is the list of the tags currently supported:
+This is the list of the tags currently supported by the `Blender Extensions Platform
+<https://extensions.blender.org/>`_:
 
 Add-ons
 =======

manual/advanced/index.rst

@@ -17,4 +17,5 @@ This chapter covers advanced use (topics which may not be required for typical u
    limits.rst
    operators.rst
    blender_directory_layout.rst
+   deploying_blender.rst
    appendices/index.rst

manual/advanced/scripting/addon_tutorial.rst

@@ -485,7 +485,7 @@ For API documentation on the functions listed above, see:
 Bringing It All Together
 ^^^^^^^^^^^^^^^^^^^^^^^^
 
-::
+.. code-block:: python
 
    bl_info = {
        "name": "Cursor Array",

manual/animation/armatures/bones/properties/bendy_bones.rst

@@ -171,7 +171,7 @@ Ease In, Out
    The *Ease In/Out* number fields, change the "length" of the :ref:`"auto" <curve-handle-type-auto>` Bézier handle
    to control the "root handle" and "tip handle" of the bone, respectively.
    These values are proportional to the default length,
-   which of course automatically varies depending on bone length,
+   which of course automatically varies depending on :ref:`bone length <bpy.types.EditBone.length>`,
    angle with the reference handle, and so on.
 
    Although easing is a scale-like value, the Edit Mode and Pose Mode versions of the values are added,

manual/animation/armatures/bones/properties/display.rst

@@ -101,15 +101,22 @@ Rotation X, Y, Z
 Override Transform
    Bone that defines the display transform of the custom shape.
 
-Scale to Bone Length
-   Whether the custom shape should be scaled by a factor equal to the bone's length.
+.. _bpy.types.PoseBone.use_custom_shape_bone_size:
 
+Scale to Bone Length
+   Whether the custom shape should be scaled by a factor
+   equal to the :ref:`bone's length <bpy.types.EditBone.length>`.
 
 .. _bpy.types.Bone.show_wire:
 
 Wireframe
    When enabled, the bone is displayed in wireframe mode regardless of the viewport's shading mode.
 
+.. _bpy.types.PoseBone.custom_shape_wire_width:
+
+Wire Width
+   The line thickness of the wireframe for the custom shape.
+
 .. note::
 
    - Custom shapes will never be rendered. Like regular bones, they are only visible in the 3D Viewport.
@@ -118,5 +125,6 @@ Wireframe
    - The origin of each instanced shape object is at the :doc:`root </animation/armatures/bones/structure>`
      of the bone.
    - The rotation of each shape object is such that its Y axis lies along the direction of the bone.
-   - For best results when *Scale to Bone Length* is enabled, make sure the template object is 1 unit
-     in size along its Y axis. This will make it perfectly match the size of each bone.
+   - For best results when :ref:`Scale to Bone Length <bpy.types.PoseBone.use_custom_shape_bone_size>` is enabled,
+     make sure the template object is 1 unit in size along its Y axis.
+     This will make it perfectly match the size of each bone.

manual/animation/armatures/bones/properties/index.rst

@@ -3,10 +3,19 @@
   Properties
 ##############
 
+.. reference::
+
+   :Mode:      Object Mode, Edit Mode and Pose Mode
+   :Panel:     :menuselection:`Properties --> Bone`
+
+When bones are selected (hence in *Edit Mode* and *Pose Mode*), their
+properties are shown in the *Bone* tab of the Properties.
+This shows different panels used to control features of each selected bone;
+the panels change depending on which mode you are working in.
+
 .. toctree::
    :maxdepth: 2
 
-   introduction.rst
    transform.rst
    bendy_bones.rst
    relations.rst

manual/animation/armatures/bones/properties/introduction.rst

@@ -1,14 +0,0 @@
-
-************
-Introduction
-************
-
-.. reference::
-
-   :Mode:      Object Mode, Edit Mode and Pose Mode
-   :Panel:     :menuselection:`Properties --> Bone`
-
-When bones are selected (hence in *Edit Mode* and *Pose Mode*), their
-properties are shown in the *Bone* tab of the Properties.
-This shows different panels used to control features of each selected bone;
-the panels change depending on which mode you are working in.

manual/animation/armatures/bones/properties/transform.rst

@@ -40,6 +40,11 @@ Tail X, Y, Z
 Roll
    Bone rotation around head-tail axis.
 
+.. _bpy.types.EditBone.length:
+
+Length
+   The distance from the bone's head to it's tail. Changing the length moves the tail end.
+
 .. _bpy.types.EditBone.lock:
 
 Lock

manual/animation/armatures/bones/selecting.rst

@@ -193,7 +193,7 @@ Immediate Children
 Siblings
    Selects bones that have the same parent as the active bone.
 Length
-   Selects bones with a similar bone length (between tip and tail) under the specified *Threshold*.
+   Selects bones with a similar :ref:`bone length <bpy.types.EditBone.length>` under the specified *Threshold*.
 Direction (Y axis)
    Select bones aligned on the Y axis (along the bone's length).
 Prefix

manual/animation/armatures/properties/bone_collections.rst

@@ -23,7 +23,7 @@ Bone Collections
 This panel contains a Tree View to manage :doc:`Bone Collection </animation/armatures/bones/bone_collections>`
 From this panel, Bone Collections can be created, deleted, re-arranged, and more.
 
-Collections can be renamed by double clicking on the name.
+Collections can be renamed by double clicking on the name, or right clinking and selecting *Rename*.
 To nest a collection inside an existing collection, click and drag the name onto another collection's name.
 Child collection can also be made by :kbd:`RMB` and selecting "Add Child Collection".
 

manual/animation/armatures/properties/index.rst

@@ -8,4 +8,5 @@
 
    introduction.rst
    bone_collections.rst
+   selection_sets.rst
    display.rst

manual/animation/armatures/properties/selection_sets.rst

@@ -0,0 +1,67 @@
+.. _bpy.types.SelectionSet:
+
+**************
+Selection Sets
+**************
+
+.. reference::
+
+   :Mode:      Pose Mode
+   :Panel:     :menuselection:`Armature --> Selection Sets`
+
+Selection Sets are a feature that allows the definition of sets of bones for easy selection while animating.
+The sets can be created in local and linked armature overrides.
+
+.. _bpy.types.Object.active_selection_set:
+
+Selection Set
+   A :ref:`ui-list-view` listing all selection sets for the selected armature.
+   Here, selection sets can be renamed by double clicking on the name.
+
+   .. _bpy.types.SelectionSet.is_selected:
+
+   To the right of the name is a check box to include that selection set when copying to the clipboard.
+
+.. rubric:: Specials
+
+.. _bpy.ops.pose.selection_set_delete_all:
+
+Delete All Sets
+   Removes all selection sets from the list.
+
+.. _bpy.ops.pose.selection_set_remove_bones:
+
+Remove Selected Bones from All Sets
+   Removes the selected bones from all selection sets.
+
+.. _bpy.ops.pose.selection_set_copy:
+
+Copy Selected Set(s)
+   Copies the selected set to Blender's clipboard.
+
+.. _bpy.ops.pose.selection_set_paste:
+
+Paste Selected Set(s)
+   Pastes a selection set from Blender's clipboard.
+
+-----
+
+.. _bpy.ops.pose.selection_set_assign:
+
+Assign
+   Assigns the selected bones to the active selection set.
+
+.. _bpy.ops.pose.selection_set_unassign:
+
+Remove
+   Removes the selected bones to the active selection set.
+
+.. _bpy.ops.pose.selection_set_select:
+
+Select
+   Selects all the bones in the active selection set.
+
+.. _bpy.ops.pose.selection_set_deselect:
+
+Deselect
+   Deselects all the bones in the active selection set.

manual/animation/constraints/index.rst

@@ -18,7 +18,6 @@ Interface
 .. toctree::
    :maxdepth: 1
 
-   interface/adding_removing.rst
    interface/header.rst
    interface/common.rst
    interface/stack.rst

manual/animation/constraints/interface/adding_removing.rst

@@ -1,97 +0,0 @@
-
-****************************
-Adding/Removing a Constraint
-****************************
-
-What is described on this page about Object Constraints can be also be applied on Bone Constraints.
-
-
-Tab
-===
-
-.. reference::
-
-   :Mode:      Object Mode
-   :Menu:      :menuselection:`Properties --> Constraint tab`
-
-To add a constraint click on the *Add Object Constraint* menu in the Constraints tab.
-
-.. figure:: /images/animation_constraints_interface_adding-removing_add-menu.png
-
-To remove a constraint click on the "X" button
-in the :doc:`header </animation/constraints/interface/header>`.
-
-
-Menu
-====
-
-.. _bpy.ops.object.constraint_add_with_targets:
-
-Add Constraint (with Targets)
------------------------------
-
-.. reference::
-
-   :Mode:      Object Mode and Pose Mode
-   :Menu:      :menuselection:`Object --> Constraint --> Add Constraint (with Targets)`
-
-Adds a constraint to the active object.
-The type of constraint must be chosen from a pop-up menu,
-though it can be changed later from the *Add Constraint (with Targets)*
-:ref:`bpy.ops.screen.redo_last` panel.
-If there is an other object selected besides the active one,
-that object will be the constraint target (if the chosen constraint accepts targets).
-
-When using a bone from another armature as the target for a constraint, the tool
-will look inside the non-active armature and use its active bone,
-provided that armature is in Pose Mode.
-
-
-.. _bpy.ops.object.constraints_copy:
-
-Copy Constraints to Selected Objects
-------------------------------------
-
-.. reference::
-
-   :Mode:      Object Mode and Pose Mode
-   :Menu:      :menuselection:`Object --> Constraint --> Copy Constraints to Selected Objects`
-
-Copies the active object Constraints to the rest of the selected objects.
-
-
-.. _bpy.ops.object.constraints_clear:
-
-Clear Object Constraints
-------------------------
-
-.. reference::
-
-   :Mode:      Object Mode and Pose Mode
-   :Panel:     :menuselection:`Object --> Constraint --> Clear Object Constraints`
-
-Removes all Constraints of the selected object(s).
-
-
-.. _bpy.ops.object.track_set:
-.. _bpy.ops.object.track_clear:
-
-Track
-=====
-
-.. reference::
-
-   :Mode:      Object Mode
-   :Panel:     :menuselection:`Object --> Track`
-
-These tools add a tracking constraint to the selected objects;
-the target object of the constraint will be the active object, which won't have a constraint added.
-
-- :doc:`Damped Track Constraint </animation/constraints/tracking/damped_track>`
-- :doc:`Track To Constraint </animation/constraints/tracking/track_to>`
-- :doc:`Lock Track Constraint </animation/constraints/tracking/locked_track>`
-
-Clear Track
-   Removes all Damped Track, Track To and Lock Track Constraints from the selected objects.
-Clear and Keep Transformation (Clear Track)
-   Removes all Track Constraint from the selected objects, while keeping the final transform caused by them.

manual/animation/constraints/introduction.rst

@@ -50,6 +50,23 @@ in the :doc:`Armature chapter </animation/armatures/posing/bone_constraints/inde
 Constraints work in combination with each other to form a Constraint Stack.
 
 
+Adding & Removing Constraints
+=============================
+
+To add a constraint click on the *Add Object Constraint* menu in the Constraints tab.
+Alternatively, you can use the :ref:`bpy.ops.object.constraint_add_with_targets` operator.
+
+To copy constraints from one object to another use :ref:`bpy.ops.object.constraints_copy`.
+
+Any single constraint can be removed by clicking on the "X" button
+in the constraint's :doc:`header </animation/constraints/interface/header>`.
+To remove all constants from an object use :ref:`bpy.ops.object.constraints_clear`.
+
+.. tip::
+
+   Tracking constraints can be added/removed using the :doc:`Track menu </scene_layout/object/editing/track>`.
+
+
 Tips
 ====
 

manual/animation/constraints/transform/limit_rotation.rst

@@ -5,30 +5,36 @@
 Limit Rotation Constraint
 *************************
 
-An object or bone can be rotated around the X, Y and Z axes.
-This constraint restricts the amount of allowed rotations around each axis,
-through lower and upper bounds.
+This constraint restricts the rotation of an object or bone to be inside
+specified angular limits.  The limits are given as Euler rotation ranges (a min
+and max angle), and a separate range can be given for each of the three axes.
 
-It is interesting to note that even though the constraint limits the visual and
-rendered rotations of its owner, its owner's data-block still allows (by default)
-the object or bone to have rotation values outside the minimum and maximum ranges.
-This can be seen in the *Transform* panel.
-When an owner is rotated and attempted to be rotated outside the limit boundaries,
-it will be constrained to those boundaries visually and when rendered, but internally,
-its rotation values will still be changed beyond the limits. If the constraint is removed,
-its ex-owner will seem to jump to its internally specified rotation.
+As with all constraints in Blender, this does not (by default) restrict the
+user-set rotation values of the object/bone as seen in the *Transform* panel.
+When the object/bone is rotated outside the limit range, it will be constrained
+to that range in its final displayed/rendered position, but the user-set
+rotation values will still be outside that range. If the constraint is removed,
+the object/bone will then jump back to match those user-set values.
 
-Similarly, if its owner has an internal rotation that is beyond the limit, rotating it back
-into the limit area will appear to do nothing until the internal rotation values are back
-within the limit threshold (unless you enabled the *Affect Transform* option, see below).
+Something unique about the Limit Rotation constraint (as compared to the Limit
+Location and Limit Scale constraints) is that rotations loop, and therefore the
+meaning of the limit range is subtly different. All constraints in Blender
+internally work on transform matrices, which can't distinguish between e.g. 180
+and -180 degrees, or 0, 360, and 720 degrees. In other words, any angles that
+result in the same visual rotation are indistinguishable to the constraint
+system.
 
-Setting equal the min and max values of an axis,
-locks the owner's rotation around that axis... Although this is possible,
-using the *Transformation Properties* axis locking feature is probably easier.
+What this means for the Limit Rotation constraint is that when the user-set
+rotation is outside of the limit range, the final displayed rotation will snap
+to the closest *visual* rotation in that range, not the closest numerical angle.
+For example, if you have a limit range of 0 to 90 degrees then a user-set
+rotation of 340 degrees will actually snap to *0 degrees* because that is the
+closer *visual* rotation, even though 340 is numerically closer to 90.
 
-This transform does not constrain the bone if it is manipulated by the IK solver.
-For constraining the rotation of a bone for IK purposes,
-see :doc:`Inverse Kinematics </animation/armatures/posing/bone_constraints/inverse_kinematics/introduction>`.
+Note that this constraint does not constrain the bone if it is manipulated by
+the IK solver. For constraining the rotation of a bone for IK purposes, see
+:doc:`Inverse Kinematics
+</animation/armatures/posing/bone_constraints/inverse_kinematics/introduction>`.
 
 
 Options
@@ -55,13 +61,24 @@ Limit X, Y, Z
 
 Order
    Allows specifying which :term:`Euler` order to use when applying the limits.
-   Defaults to the order of the owner.
+   Defaults to the order of the owner, or XYZ if the owner uses non-Euler
+   rotations.
 
 Affect Transform
    The constraint is taken into account when the object is manually rotated using
    transformation tools in the editors. This prevents assigning transformation
    property values (as shown in the *Transform* panel) that exceed the specified limits.
 
+Legacy Behavior
+   For backwards compatibility: make the constraint behave in the semi-broken
+   way it did prior to Blender 4.2. This old behavior does not properly account
+   for the looping nature of rotations, and therefore causes
+   unpredictable/erratic rotation snapping. However, this behavior can still be
+   useful in some specific circumstances when `Owner` is set to local space, and
+   some older rig setups utilize that. However, that behavior is better and more
+   robustly accomplished with drivers directly on the object/bone's rotation
+   properties, so new rigs should favor that approach over using this option.
+
 Owner
    This constraint allows you to choose in which space evaluate its owner's transform properties.
    See :ref:`common constraint properties <rigging-constraints-interface-common-space>` for more information.

manual/animation/constraints/transform/transformation.rst

@@ -6,16 +6,15 @@ Transformation Constraint
 *************************
 
 This constraint is more complex and versatile than the other "transform" constraints.
-It allows you to map one type of transform properties (i.e. location, rotation or scale)
-of the target, to the same or another type of transform properties of the owner,
-within a given range of values (which might be different for each target and owner property).
-You can also switch between axes, and use the range values not as limits,
-but rather as "markers" to define a mapping between input (target) and output (owner) values.
+It lets you set the location, rotation or scale of an object/bone based on the
+location, rotation or scale of another, mixing and matching axes as you see fit.
+An example could be to set a gear's X rotation based on the Y coordinate of
+a rail next to it.
 
-So, e.g. you can use the position of the target along the X axis to control the rotation of
-the owner around the Z axis, stating that 1 unit along the target X axis corresponds
-to 10 units around the owner Z axis. Typical uses for this include gears (see note below),
-and rotation based on location setups.
+The constraint works with input and output value ranges, one for each axis.
+It first clamps the input value to the *Map From* range, then offsets and scales it
+to the corresponding *Map To* range. This lets you, say, map a Y coordinate
+in the range (-3m, 3m) to an X rotation in the range (0, 180°).
 
 
 Options
@@ -26,84 +25,80 @@ Options
    Transformation panel.
 
 Target
-   :ref:`ui-data-id` used to select the constraints target, and is not functional (red state) when it has none.
+   The reference object to read a transformation property from. If you don't select one, the constraint's
+   icon will turn red and it will have no effect.
+
    See :ref:`common constraint properties <rigging-constraints-interface-common-target>` for more information.
 
+Bone
+   If *Target* is an :doc:`Armature </animation/armatures/introduction>`, you can optionally choose a
+   bone here to use the transformation of that bone instead of the armature object as a whole.
+
 Extrapolate
-   By default, the *Min* and *Max* values bound the input and output values;
-   all values outside these ranges are clipped to them.
-   When you enable this button, the *Min* and *Max* values are no longer strict limits,
-   but rather "markers" defining a proportional (linear) mapping between input and corresponding output values.
-   Let us illustrate that with two graphs Fig. :ref:`fig-constraints-transformation-extrapolate`.
-   In these pictures, the input range (in abscissa) is set to (1.0 to 4.0),
-   and its corresponding output range (in ordinate), to (1.0 to 2.0).
-   The yellow curve represents the mapping between input and output.
+   By default, the input and output values are clamped to the *Min/Max* values.
+   When you enable *Extrapolate*, they're allowed to go beyond these limits.
+   This is illustrated with the graphs below, where the X axis represents the input
+   (*Map From* set to *Min* = 1 and *Max* = 4) and the Y axis represents the output
+   (*Map To* set to *Min* = 1 and *Max* = 2).
 
    .. _fig-constraints-transformation-extrapolate:
 
-   .. list-table:: The Extrapolate principles.
+   .. list-table:: The Extrapolate option.
 
       * - .. figure:: /images/animation_constraints_transform_transformation_extrapolate-1.png
 
-             Extrapolate disabled: the output values are bounded inside the (1.0 to 2.0) range.
+             Extrapolate disabled: the output values are limited to the Map To range.
 
         - .. figure:: /images/animation_constraints_transform_transformation_extrapolate-2.png
 
-             Extrapolate enabled: the output values are "free" to proportionally follow the input ones.
+             Extrapolate enabled: the output values can extend beyond the limits.
 
 Target/Owner
    Standard conversion between spaces.
    See :ref:`common constraint properties <rigging-constraints-interface-common-space>` for more information.
 
 Influence
-   Controls the percentage of affect the constraint has on the object.
+   Controls the percentage of effect the constraint has on the object.
    See :ref:`common constraint properties <bpy.types.constraint.influence>` for more information.
 
 
 Map From
 --------
 
-It contains the input (from target) settings.
+The transformation to read from the *Target* (or *Bone*).
 
 Location, Rotation, Scale
-   The radio buttons allow you to select which type of property to use.
+   The type of transformation to read.
 
-Mode (Rotation)
-   Allows specifying the type of rotation input to use, including different :term:`Euler` orders,
+Mode :guilabel:`Rotation`
+   The type of rotation to use, including different :term:`Euler` orders,
    :term:`Quaternion`, and other :ref:`Rotation Channel Modes <drivers-variables-rotation-modes>`.
    Defaults to using the :term:`Euler` order of the constraint owner.
 
-   In the *Quaternion* mode the channels are converted to weighted angles in the same way as
+   In the *Quaternion* mode, the channels are converted to weighted angles in the same way as
    the swing angles of the :ref:`Swing and X/Y/Z Twist <drivers-variables-rotation-modes>` modes.
 
 X/Y/Z Min, Max
-   Independently for each axis (X, Y, and Z) the min and max number fields control
-   the lower and upper bounds of the input value range.
-   Note that if a min value is higher than its corresponding max value,
-   the constraint behaves as if it had the same value as the max one.
+   The input value range for each axis.
 
 
 Map To
 ------
 
-It contains the output (to owner) settings.
+The transformation to apply to the owner.
 
 Location, Rotation, Scale
-   The three radio buttons allow you to select which type of property to control.
+   The type of transformation to apply.
 
-Order (Rotation)
-   For rotation, allows specifying which :term:`Euler` order to use during evaluation
-   of the constraint. Defaults to using the order of the constraint owner.
+Order :guilabel:`Rotation`
+   Which :term:`Euler` order to use. Defaults to the order of the constraint owner.
 
 X/Y/Z Source Axis
-   The three axis selectors allow you to select which input axis to map to,
-   respectively (from top to bottom), the X, Y and Z output (owner) axes.
+   For each of the three output axes, lets you choose the input axis that it should take
+   its value from. You can select the same input axis multiple times.
 
 Min, Max
-   The *Min* and *Max* number fields control the lower and upper bounds of the output value range,
-   independently for each mapped axis.
-   Note that if a min value is higher than its corresponding max value,
-   the constraint behaves as if it had the same value as the max one.
+   The output value range for each axis.
 
 Mix
    Specifies how the result of the constraint is combined with the existing transformation.
@@ -111,36 +106,62 @@ Mix
 
    Replace
       The result of the constraint replaces the existing transformation.
-   Multiply (Scale)
+   Multiply :guilabel:`Scale`
       The new values are multiplied with the existing axis values.
-   Add (Location, Rotation)
+   Add :guilabel:`Location` :guilabel:`Rotation`
       The new values are added to the existing axis values.
-   Before Original (Rotation)
-      The new rotation is added before the existing rotation, as if it was applied to
+   Before Original :guilabel:`Rotation`
+      The new rotation is added before the existing rotation, as if it were applied to
       a parent of the constraint owner.
-   After Original (Rotation)
-      The new rotation is added after the existing rotation, as if it was applied to
+   After Original :guilabel:`Rotation`
+      The new rotation is added after the existing rotation, as if it were applied to
       a child of the constraint owner.
 
 .. note::
 
    - For historical reasons, the *Mix* mode defaults to *Add* for location and rotation,
      and *Replace* for scale.
-   - When using the rotation transform properties of the target as input,
+   - When using the rotation of the target as input,
      whatever the real values are, the constraint will always "take them back" into the (-180 to 180) range.
      E.g. if the target has a rotation of 420 degrees around its X axis,
      the values used as *X* input by the constraint will be:
 
-     :math:`((420 + 180) modulo 360) - 180 = 60 - ...`
+     :math:`((420 + 180) modulo 360) - 180 = 60 - 180 = -120`
 
-     This is why this constraint is not really suited for gears!
+     As such, this constraint is not really suited for transforming an object based on a gear's rotation.
+     Rotating a gear based on an object's transformation works fine, however.
    - Similarly, when using the scale transform properties of the target as input,
      whatever the real values are, the constraint will always take their absolute values (i.e. invert negative ones).
-   - When a *min* value is higher than its corresponding *max* one,
-     both are considered equal to the *max* one. This implies you cannot create "reversed" mappings...
+   - When a *Min* value is higher than its corresponding *Max* one,
+     both are considered equal to the *Max* one. This means you cannot create "reversed" mappings.
 
 
 Example
 =======
 
-.. peertube:: a7206092-8ae1-4290-93d3-85ba8440bfe1
+In the following example, we add a constraint to a gear that sets its X rotation based on the
+Y position of a rail:
+
+- Target: Rail object
+
+- Map From: Location
+
+  * Y Min: -3m
+  * Y Max: 3m
+
+- Map To: Rotation
+
+  * X Source Axis: Y
+  * X Min: 0°
+  * X Max: 180°
+
+.. figure:: /images/animation_constraints_transform_example_before.png
+
+   Before moving the rail.
+
+.. figure:: /images/animation_constraints_transform_example_after.png
+
+   After moving the rail.
+
+By default, the gear will stop rotating if the rail goes outside the (-3m, 3m) range.
+You can enable *Extrapolate* to change this.

manual/animation/drivers/drivers_panel.rst

@@ -138,7 +138,7 @@ Variable Type
       .. tip::
 
          The easiest way to create a variable of this type is to use
-         the :ref:`Copy As New Driver <drivers-copy-as-new>`
+         the :ref:`Copy As New Driver <bpy.ops.ui.copy_as_driver_button>`
          context menu option of the input property, and paste the result
          into the driver via :ref:`Paste Driver Variables <drivers-variables>`.
 

manual/animation/drivers/usage.rst

@@ -28,6 +28,8 @@ This operation adds a driver with a single variable (which needs to be filled in
 and displays the *Edit Driver* popover.
 
 
+.. _bpy.ops.anim.driver_button_edit:
+
 Edit Driver
 ===========
 
@@ -42,6 +44,8 @@ Many drivers don't use their :doc:`F-Curve </editors/graph_editor/fcurves/introd
 component, so this reduced interface is sufficient.
 
 
+.. _bpy.ops.screen.drivers_editor_show:
+
 Open Drivers Editor
 ===================
 
@@ -53,6 +57,9 @@ Opens a new window with the *Drivers Editor* and
 selects the driver associated with the property.
 
 
+.. _bpy.ops.anim.copy_driver_button:
+.. _bpy.ops.anim.paste_driver_button:
+
 Copy & Paste
 ============
 
@@ -65,7 +72,22 @@ Drivers can be copied and pasted via the context menu.
 When adding drivers with the same settings, this can save time modifying settings.
 
 
-.. _drivers-copy-as-new:
+.. _bpy.ops.ui.copy_driver_to_selected_button:
+
+Copy Driver to Selected
+=======================
+
+.. reference::
+
+   :Menu:      :menuselection:`Context menu --> Copy Drivers to Selected`
+   :Menu:      :menuselection:`Context menu --> Copy Driver to Selected`
+   :Menu:      :menuselection:`Context menu --> Copy All Drivers to Selected`
+
+Copy the property's driver from the active item to the same
+property of all selected items, if the same property exists.
+
+
+.. _bpy.ops.ui.copy_as_driver_button:
 
 Copy As New Driver
 ==================

manual/animation/shape_keys/shape_keys_panel.rst

@@ -50,6 +50,7 @@ Active Shape Key Index
       and tools that move vertices abort with an error if the active shape key is locked.
 
       .. note::
+
          Operators that always modify all shape keys in exactly the same way, like
          :ref:`Apply Object Transforms <bpy.ops.object.transform_apply>`, don't check shape key locks.
          Neither currently do most edit mode operators that modify topology, because the topology is

manual/compositing/sidebar.rst

@@ -59,6 +59,14 @@ Performance
 
 This panel helps you tweak the performance of the Compositor.
 
+.. _bpy.types.RenderSettings.compositor_device:
+
+Device
+   The device used for compositing.
+
+   :CPU: Use the CPU for compositing.
+   :GPU: Use the GPU for compositing.
+
 .. _bpy.types.RenderSettings.compositor_precision:
 
 Precision
@@ -75,8 +83,3 @@ Viewer Region
    which will become the next preview in the backdrop.
    :kbd:`Ctrl-Alt-B` discards the region back to a full preview.
    This is only a preview option, final compositing during a render ignores this region.
-
-.. _bpy.types.SpaceNodeEditor.use_auto_render:
-
-Auto Render
-   Re-render and composite changed layer when edits to the 3D scene are made.

manual/compositing/types/color/rgb_to_bw.rst

@@ -17,6 +17,7 @@ RGB to BW Node
 The *RGB to BW Node* makes a color image black-and-white by outputting its luminance.
 
 .. note::
+
    You can directly connect Color sockets to Value sockets in node graphs,
    which also converts the image to black-and-white. As such, this node is
    not always necessary.

manual/compositing/types/filter/glare.rst

@@ -24,6 +24,13 @@ Properties
 ==========
 
 Glare Type
+   :Bloom:
+      Simulates the glow around bright objects caused by light scattering in eyes and cameras.
+
+      Size
+         Scale of the glow relative to the size of the image. 9 means the glow can cover the
+         entire image, 8 means it can only cover half the image, 7 means it can only cover quarter
+         of the image, and so on.
    :Ghosts:
       Creates a haze over the image.
    :Streaks:
@@ -36,15 +43,14 @@ Glare Type
       Fade
          Fade out factor for the streaks.
    :Fog Glow:
-      Looks similar to *Ghost*. However, it is much smaller in size
-      and gives more of an atmospheric haze or "glow" around the image.
-
-      .. note::
-
-         Viewport compositing results will vary from CPU compositing due to different algorithms.
+      Simulates the glow around bright objects caused by light scattering in eyes and cameras.
+      This is similar to the *Bloom* mode, but is more physically accurate, at the cost of much
+      slower computation time.
 
       Size
-         Scale of the glow relative to the size of the original bright pixels.
+         Scale of the glow relative to the size of the image. 9 means the glow will cover the
+         entire image, 8 means it will cover half the image, 7 means it will cover quarter of the
+         image, and so on.
    :Simple Star:
       Works similar to *Streaks* but gives a simpler shape looking like a star.
 

manual/compositing/types/input/texture.rst

@@ -11,6 +11,10 @@ Texture Node
 
 The Texture node makes 3D textures available to the Compositor.
 
+.. note::
+
+   The Texture node is not supported by the :doc:`viewport compositor </compositing/realtime_compositor>`.
+
 
 Inputs
 ======

manual/compositing/types/transform/translate.rst

@@ -32,10 +32,12 @@ Wrapping
    Repeat pixels on the other side when they extend over the image dimensions, making endless translating possible.
 
    None, X Axis, Y Axis, Both Axis
+Filter
+   Interpolation Methods.
 
-.. note::
-
-   Individual axis wrapping is only supported in the CPU compositor.
+   :Nearest: No interpolation, uses nearest neighboring pixel.
+   :Bilinear: Simple interpolation between adjacent pixels.
+   :Bicubic: Highest quality interpolation.
 
 
 Outputs

manual/conf.py

@@ -16,7 +16,7 @@ import sys
 
 from sphinx import version_info as sphinx_version
 
-sys.path.insert(0, os.path.abspath(os.path.join('..', 'build_files', 'extensions')))
+sys.path.insert(0, os.path.abspath(os.path.join("..", "build_files", "extensions")))
 
 # Sphinx errors out on single threaded builds see T86621
 sys.setrecursionlimit(2000)
@@ -26,14 +26,14 @@ sys.setrecursionlimit(2000)
 
 # Not used directly by Sphinx, but used by this file and the buildbot.
 
-blender_version = '4.3'
+blender_version = "4.3"
 
 
 # -- Project information -----------------------------------------------------
 
-project = 'Blender %s Manual' % blender_version
-copyright = ': This page is licensed under a CC-BY-SA 4.0 Int. License'
-author = 'Blender Documentation Team'
+project = "Blender {:s} Manual".format(blender_version)
+copyright = ": This page is licensed under a CC-BY-SA 4.0 Int. License"
+author = "Blender Documentation Team"
 
 # The major project version, used as the replacement for |version|.
 version = blender_version
@@ -45,48 +45,48 @@ release = blender_version
 # -- General configuration ---------------------------------------------------
 
 # Add any Sphinx extension module names here, as strings. They can be
-# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# extensions coming with Sphinx (named "sphinx.ext.*") or your custom
 # ones.
 extensions = [
-    '404',
-    'peertube',
-    'reference',
-    'sphinx.ext.intersphinx',
-    'sphinx.ext.mathjax',
-    'sphinx.ext.todo',
+    "404",
+    "peertube",
+    "reference",
+    "sphinx.ext.intersphinx",
+    "sphinx.ext.mathjax",
+    "sphinx.ext.todo",
 ]
 
 # Is there a better way to check for PDF building?
 if "latex" in sys.argv:
-    # To convert gif's when making a PDF.
-    extensions.append('sphinx.ext.imgconverter')
+    # To convert GIF images when making a PDF.
+    extensions.append("sphinx.ext.imgconverter")
     image_converter = "magick"
 
 # Add any paths that contain templates here, relative to this directory.
-templates_path = ['../build_files/templates']
+templates_path = ["../build_files/templates"]
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This pattern also affects html_static_path and html_extra_path.
-# exclude_patterns = ['_build']
+# exclude_patterns = ["_build"]
 
 # A string of reStructuredText that will be included at the end of every
 # source file that is read. This is a possible place to add substitutions
 # that should be available in every file.
 rst_epilog = """
-.. |BLENDER_VERSION| replace:: %s
+.. |BLENDER_VERSION| replace:: {:s}
 .. |TODO| replace:: The documentation here is incomplete, you can help by :doc:`contributing </contribute/index>`.
-""" % blender_version
+""".format(blender_version)
 
 # Quit warnings about missing download file
-# suppress_warnings = ['download.not_readable']
+# suppress_warnings = ["download.not_readable"]
 
-# If set to a major.minor version string like '1.1', Sphinx will compare it
+# If set to a major.minor version string like "1.1", Sphinx will compare it
 # with its version and refuse to build if it is too old.
-needs_sphinx = '3.3'
+needs_sphinx = "3.3"
 
 # The default language to highlight source code in.
-highlight_language = 'python3'
+highlight_language = "python3"
 
 # If true, figures, tables and code-blocks are automatically numbered if they have a caption.
 numfig = False
@@ -99,11 +99,11 @@ numfig_secnum_depth = 0
 
 # The code for the language the docs are written in.
 # Any text automatically generated by Sphinx will be in that language.
-language = 'en'
+language = "en"
 
 # Directories in which to search for additional message catalogs,
 # relative to the source directory.
-locale_dirs = ['../locale/']
+locale_dirs = ["../locale/"]
 gettext_compact = "blender_manual"
 
 # If true, "fuzzy" messages in the message catalogs are used for translation.
@@ -151,10 +151,10 @@ if html_theme == "furo":
         ]
     }
 
-# The "title" for HTML documentation generated with Sphinx's own templates.
+# The "title" for HTML documentation generated with Sphinx"s own templates.
 # This is appended to the <title> tag of individual pages, and
 # used in the navigation bar as the "topmost" element.
-html_title = 'Blender %s Manual' % blender_version
+html_title = "Blender {:s} Manual".format(blender_version)
 
 # The base URL which points to the root of the HTML documentation.
 # It is used to indicate the location of document using
@@ -171,28 +171,32 @@ html_logo = "../build_files/theme/blender-logo.svg"
 # If given, this must be the name of an image file
 # (path relative to the configuration directory) that is the favicon of
 # the docs, or URL that points an image file for the favicon.
-html_favicon = "../build_files/theme/favicon.ico"
+html_favicon = "../build_files/theme/favicon.png"
 
 if html_theme == "furo":
-    html_css_files = ["css/theme_overrides.css",
-                      "css/version_switch.css"]
-    html_js_files = ["js/version_switch.js"]
+    html_css_files = [
+        "css/theme_overrides.css",
+        "css/version_switch.css",
+    ]
+    html_js_files = [
+        "js/version_switch.js",
+    ]
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ["../build_files/theme"]
 
-# If this is not None, a 'Last updated on:' timestamp is inserted at
+# If this is not None, a "Last updated on:" timestamp is inserted at
 # every page bottom, using the given strftime() format.
-# The empty string is equivalent to '%b %d, %Y'
+# The empty string is equivalent to "%b %d, %Y"
 # (or a locale-dependent equivalent).
-html_last_updated_fmt = '%Y-%m-%d'
+html_last_updated_fmt = "%Y-%m-%d"
 
 # Additional templates that should be rendered to HTML pages,
 # must be a dictionary that maps document names to template names.
 html_additional_pages = {
-    '404': '404.html',
+    "404": "404.html",
 }
 
 # If true, the reST sources are included in the HTML build as _sources/name.
@@ -205,7 +209,7 @@ html_show_sourcelink = False
 # If nonempty, an OpenSearch description file will be output,
 # and all pages will contain a <link> tag referring to it.
 # Ed. Note: URL has to be adapted, when versioning is set up.
-html_use_opensearch = 'https://docs.blender.org/manual/' + language + '/latest'
+html_use_opensearch = "https://docs.blender.org/manual/{:s}/latest".format(language)
 
 # If true, "(C) Copyright …" is shown in the HTML footer.
 html_show_copyright = True
@@ -220,50 +224,53 @@ html_show_search_summary = True
 # -- Options for HTML help output --------------------------------------------
 
 # Output file base name for HTML help builder.
-htmlhelp_basename = 'Blender Reference Manual'
+htmlhelp_basename = "Blender Reference Manual"
 
 
 # -- Options for Epub output -------------------------------------------------
 
 # The basename for the epub file. It defaults to the project name.
-# epub_basename = ''
+# epub_basename = ""
 
 # The HTML theme for the epub output. Since the default themes are
 # not optimized for small screen space, using the same theme for HTML
 # and epub output is usually not wise.
-epub_theme = 'epub'
+epub_theme = "epub"
 
 # Bibliographic Dublin Core info.
 # These default to their non epub counterparts.
-# epub_title = ''
-epub_description = 'Blender Reference Manual'
-# epub_author = ''
-epub_publisher = 'Blender Foundation'
+# epub_title = ""
+epub_description = "Blender Reference Manual"
+# epub_author = ""
+epub_publisher = "Blender Foundation"
 
 # The language of the text. It defaults to the language option
-# or 'en' if the language is not set.
-# epub_language = ''
+# or "en" if the language is not set.
+# epub_language = ""
 
-epub_copyright = 'This manual is licensed under a CC-BY-SA 4.0 Int. License.'
+epub_copyright = "This manual is licensed under a CC-BY-SA 4.0 Int. License."
 
 # An identifier for the document. This is put in the Dublin Core metadata.
 # For published documents this is the ISBN number, but you can also
 # use an alternative scheme, e.g. the project homepage.
-# epub_identifier = ''
+# epub_identifier = ""
 
 # The publication scheme for the epub_identifier.
 # This is put in the Dublin Core metadata.
-# For published books the scheme is 'ISBN'.
-# If you use the project homepage, 'URL' seems reasonable.
-# epub_scheme = ''
+# For published books the scheme is "ISBN".
+# If you use the project homepage, "URL" seems reasonable.
+# epub_scheme = ""
 
 # A unique identifier for the document.
 # This is put in the Dublin Core metadata.
-# epub_uid = ''
+# epub_uid = ""
 
 # The cover page information. This is a tuple containing the filenames of
 # the cover image and the html template.
-epub_cover = ('_static/cover.png', 'epub-cover.html')
+epub_cover = (
+    "_static/cover.png",
+    "epub-cover.html",
+)
 
 epub_css_files = ["css/epub_overrides.css"]
 
@@ -282,7 +289,7 @@ epub_css_files = ["css/epub_overrides.css"]
 
 # A list of files that are generated/copied in the build directory
 # but should not be included in the epub file.
-epub_exclude_files = ['search.html', '404.html']
+epub_exclude_files = ["search.html", "404.html"]
 
 # The depth of the table of contents in the file toc.ncx.
 epub_tocdepth = 2
@@ -292,7 +299,7 @@ epub_tocdepth = 2
 # epub_tocdup = True
 
 # This setting control the scope of the epub table of contents.
-# epub_tocscope = 'default'
+# epub_tocscope = "default"
 
 # This flag determines if sphinx should try to fix image formats
 # that are not supported by some epub readers.
@@ -302,7 +309,7 @@ epub_tocdepth = 2
 # epub_max_image_width = 0
 
 # Control whether to display URL addresses.
-epub_show_urls = 'no'
+epub_show_urls = "no"
 
 # If true, add an index to the epub document.
 # epub_use_index = True
@@ -311,14 +318,19 @@ epub_show_urls = 'no'
 # -- Options for LaTeX output ------------------------------------------------
 # see https://github.com/sphinx-doc/sphinx/issues/3289
 
-latex_engine = 'xelatex'
+latex_engine = "xelatex"
 
 # This value determines how to group the document tree into LaTeX source files.
 # It must be a list of tuples
 # (startdocname, targetname, title, author, theme, toctree_only).
 latex_documents = [
-    ('index', 'blender_manual.tex', 'Blender User Manual',
-     'Blender Community', 'manual'),
+    (
+        "index",
+        "blender_manual.tex",
+        "Blender User Manual",
+        "Blender Community",
+        "manual",
+    ),
 ]
 
 # If given, this must be the name of an image file
@@ -329,13 +341,11 @@ latex_documents = [
 # LaTeX Error: Cannot determine size of graphic in blender-logo.svg (no
 # Boundin gBox).
 
-'''
-latex_logo = "../build_files/theme/blender-logo.svg"
-'''
+# latex_logo = "../build_files/theme/blender-logo.svg"
 
 # This value determines the topmost sectioning unit. It should be chosen from
-# 'part', 'chapter' or 'section'.
-# latex_toplevel_sectioning = 'None'
+# "part", "chapter" or "section".
+# latex_toplevel_sectioning = "None"
 
 # A list of document names to append as an appendix to all manuals.
 # latex_appendices = []
@@ -351,28 +361,28 @@ latex_logo = "../build_files/theme/blender-logo.svg"
 latex_show_urls = "no"
 
 latex_elements = {
-    # The paper size ('letterpaper' or 'a4paper').
-    'papersize': 'a4paper',
+    # The paper size ("letterpaper" or "a4paper").
+    "papersize": "a4paper",
 
-    # The font size ('10pt', '11pt' or '12pt').
-    'pointsize': '10pt',
+    # The font size ("10pt", "11pt" or "12pt").
+    "pointsize": "10pt",
 
     # Additional stuff for the LaTeX preamble.
 
-    'sphinxsetup': 'hmargin=0.75in, vmargin=1in',
+    "sphinxsetup": "hmargin=0.75in, vmargin=1in",
 
-    'classoptions': ',openany,oneside',
-    #  'babel': '\\usepackage[english]{babel}',
+    "classoptions": ",openany,oneside",
+    #  "babel": "\\usepackage[english]{babel}",
     # note that xelatex will use polyglossia by default,
-    # but if 'babel' key is redefined like above, it will use babel package.
+    # but if "babel" key is redefined like above, it will use babel package.
 
-    'fontpkg': r'''
+    "fontpkg": r"""
 \setmainfont{DejaVu Serif}
 \setsansfont{DejaVu Sans}
 \setmonofont{DejaVu Sans Mono}
-''',
+""",
 
-    'preamble': u'''
+    "preamble": u"""
 \\renewenvironment{wrapfigure}[2]{\\begin{figure}[H]}{\\end{figure}}
 \\usepackage{newunicodechar}
 
@@ -389,7 +399,7 @@ latex_elements = {
 \\newunicodechar{⏭}{\\faFastForward}
 \\newunicodechar{⏸}{\\faPause}
 \\newunicodechar{◀}{\\reflectbox{▶}}
-''',
+""",
 
 }
 
@@ -400,8 +410,13 @@ latex_elements = {
 # It must be a list of tuples
 # (startdocname, name, description, authors, section).
 man_pages = [
-    ('index', 'manual_docs', 'Blender Manual Documentation Documentation',
-     [''], 1)
+    (
+        "index",
+        "manual_docs",
+        "Blender Manual Documentation Documentation",
+        [""],
+        1,
+    ),
 ]
 
 # If true, add URL addresses after links.
@@ -415,8 +430,13 @@ man_show_urls = False
 # (startdocname, targetname, title, author, dir_entry,
 # description, category, toctree_only)
 texinfo_documents = [
-    ('index', 'Blender Reference Manual', 'Blender Manual Documentation',
-     'Blender Documentation Team', 'Blender Reference Manual'),
+    (
+        "index",
+        "Blender Reference Manual",
+        "Blender Manual Documentation",
+        "Blender Documentation Team",
+        "Blender Reference Manual",
+    ),
 ]
 
 # A list of document names to append as an appendix to all manuals.
@@ -426,7 +446,7 @@ texinfo_documents = [
 # texinfo_domain_indices = True
 
 # Control how to display URL addresses.
-# texinfo_show_urls = 'footnote'
+# texinfo_show_urls = "footnote"
 
 # If true, do not generate a @detailmenu in the "Top" node's menu
 # containing entries for each sub-node in the document.
@@ -436,11 +456,11 @@ texinfo_documents = [
 # -- Extension configuration -------------------------------------------------
 
 intersphinx_mapping = {
-    'blender_api': (
-        'https://docs.blender.org/api/' +
-        blender_version +
-        '/',
-        None)}
+    "blender_api": (
+        "https://docs.blender.org/api/{:s}/".format(blender_version),
+        None,
+    ),
+}
 peertube_instance = "https://video.blender.org/"
 
 # If true, `todo` and `todoList` produce output, else they produce nothing.
@@ -450,7 +470,7 @@ todo_include_todos = True
 
 
 # ----------------------------------------------------------------------------
-# Monkey Patch, without this 'zh-hant' fails
+# Monkey Patch, without this "zh-hant" fails
 #
 # See: https://lists.blender.org/pipermail/bf-docboard/2017-October/005259.html
 
@@ -463,10 +483,14 @@ def monkey_patch_babl_locale_dash():
     CatalogInfo._write_mo_real = CatalogInfo.write_mo
     if sphinx_version >= (4, 3, 0):
         CatalogInfo.write_mo = lambda self, locale, use_fuzzy: CatalogInfo._write_mo_real(
-            self, locale.replace('-', '_'))
+            self,
+            locale.replace("-", "_"),
+        )
     else:
         CatalogInfo.write_mo = lambda self, locale: CatalogInfo._write_mo_real(
-            self, locale.replace('-', '_'))
+            self,
+            locale.replace("-", "_"),
+        )
 
 
 monkey_patch_babl_locale_dash()

manual/contribute/guides/commit_guide.rst

@@ -28,9 +28,8 @@ If you leave out ``-m "message"``, you will be prompted to type the message in a
 
 .. seealso::
 
-   See :doc:`/contribute/release_cycle` for documentation on how to make
-   commits to a specific release branch and how to create merge commits.
-
+   See `release branch <https://developer.blender.org/docs/handbook/release_process/release_branch/>`__ for 
+   documentation on how to make commits to a specific release branch and how to create merge commits.
 
 .. _contribute-commit-good-message:
 

manual/contribute/index.rst

@@ -50,7 +50,6 @@ Guidelines
    guides/commit_guide.rst
    guides/templates.rst
    guides/maintenance_guide.rst
-   release_cycle.rst
 
 
 Translations

manual/contribute/install/linux.rst

@@ -25,7 +25,7 @@ Debian/Ubuntu::
 
 Redhat/Fedora::
 
-   sudo yum install python python-pip git git-lfs
+   sudo dnf install python python-pip git git-lfs
    git lfs install --skip-repo
 
 Arch Linux::

manual/contribute/release_cycle.rst

@@ -1,131 +0,0 @@
-.. highlight:: sh
-
-*************
-Release Cycle
-*************
-
-A new Blender version is targeted to be released every 3 months.
-The actual `release cycle <https://developer.blender.org/docs/handbook/release_process/release_cycle/>`__
-for a specific release is longer, and overlaps the previous and next release cycle.
-
-.. figure:: /images/about_contribute_release-cycle_diagram.png
-
-
-Branches
-========
-
-Work is done in two branches:
-
-- ``blender-v{VERSION}-release`` branch: fixes and other incremental improvements.
-- ``main`` branch: documentation for new features and improvements for the release after that.
-
-The ``blender-v{VERSION}-release`` branch will be available for 5 weeks prior to the release date.
-At the same time ``main`` will be open for the next release,
-giving 2 months to add documentation for new features of the next release, and another month to make improvements.
-
-
-Switching Branches
-------------------
-
-To switch to the release branch use::
-
-   git checkout blender-v{VERSION}-release
-
-To switch back to the development branch use::
-
-   git checkout main
-
-
-Updating Branches
------------------
-
-To merge changes from the release branch to the development branch,
-first switch to the development branch and use::
-
-   git merge blender-v{VERSION}-release
-
-
-Bcon Phases
-===========
-
-Each Blender version has its own Bcon phase,
-indicating which types of changes are allowed to be committed and what writers are focusing on.
-
-That means for example that Blender 2.90 can be in Bcon3 (wrapping up),
-while Blender 2.91 is in Bcon1 (new features and changes).
-
-.. list-table::
-   :header-rows: 1
-   :widths: 5 20 20 50 5
-
-   * - Phase
-     - Description
-     - Duration
-     - Details
-     - Branch
-
-   * - Bcon1
-
-     - New features and changes
-
-     - 4-5 weeks
-
-     - The first 5 weeks overlap with the Bcon3 and Bcon4 phases of the previous release,
-       Writing focus will be split on fixes for the previous release
-       and writing documentation for features already added or likely to be added to Blender.
-       This is also the perfect time to make any larger or more disruptive improvements to the manual.
-
-     - ``main``
-
-   * - Bcon2
-
-     - Improve and stabilize
-
-     - 4 weeks
-
-     - Work to improve, optimize and fix bugs in new and existing features.
-       All big or disruptive changes must be finished at the end of this stage.
-
-     - ``main``
-
-   * - Bcon3
-
-     - Wrapping up
-
-     - 4 weeks
-
-     - Focus should be on fixes and other incremental improvements.
-       All new Blender features should be documented by the end of this stage.
-
-     - ``blender-v{VERSION}-release``
-
-   * - Bcon4
-
-     - Prepare release
-
-     - 1 week
-
-     - Focus should be wrapping up fixes and other incremental improvements.
-
-     - ``blender-v{VERSION}-release``
-
-   * - Bcon5
-
-     - Release
-
-     - 1-2 days
-
-     - The manual is archived on the server and redirects / symlinks are updated.
-       See the :ref:`Release Guide <about-contribute-guides-release>` for more information.
-
-     -
-
-   * - Bcon6
-
-     - Long-term release
-
-     - 2 years
-
-     - In case a major error is found in the manual the patch will be committed to the release branch.
-
-     - ``blender-v{VERSION}-release``

manual/editors/3dview/display/overlays.rst

@@ -11,12 +11,15 @@ Viewport Overlays
    :Header:    |overlays-icon| :menuselection:`Overlays`
 
 Clicking the icon toggles all overlays in the 3D Viewport.
-The drop-down button displays a popover with more detailed settings,
-which are described below.
+
+.. note::
+
+   Cameras outline & :ref:`passepartout <bpy.types.Camera.show_passepartout>` are not considered Viewport overlays.
+
+The drop-down button displays a popover with more detailed settings, which are described below.
 
 Depending on the current :doc:`object interaction mode </editors/3dview/modes>`,
-there may be a second button with yet more settings,
-which are also described here.
+there may be a second button with yet more settings, which are also described here.
 
 
 General
@@ -73,6 +76,13 @@ Statistics
    - **Geometry** -- Displays information about the current scene depending on the mode and object type.
      This can be the number of vertices, faces, triangles, or bones.
 
+.. _bpy.types.View3DOverlay.show_camera_guides:
+
+Camera Guides
+   Show Camera guides
+   (:ref:`Safe Areas <bpy.ops.safe_areas>` & :ref:`Composition Guides <bpy.types.Camera.show_composition>`),
+   only available in :ref:`camera view <bpy.ops.view3d.view_camera>`.
+
 HDRI Preview
    Show two spheres, one glossy and one diffuse, to preview the HDRI that's being used for world lighting.
    While HDRIs can be used in both the *Material Preview* and *Rendered*
@@ -225,18 +235,22 @@ Shading
 .. _bpy.types.View3DOverlay.show_retopology:
 
 Retopology
-   Hide the solid mesh and offset the overlay towards the view.
-   Selection is occluded by inactive geometry, unless X-Ray is enabled
+   This overlay is useful when you have a sculpted mesh with the desired shape and
+   want to recreate it with better topology. It makes the edited mesh see-through
+   (so that you can see the sculpted mesh underneath it) and optionally renders it
+   in front of nearby geometry (so that you can see it underneath the sculpted mesh).
 
    .. _bpy.types.View3DOverlay.retopology_offset:
 
    Offset
-      Amount to offset edit mesh in front of other geometry.
+      Distance to "move the edited mesh towards the camera." Use this to display the
+      mesh in front of other objects that would normally occlude it.
 
 .. _bpy.types.View3DOverlay.show_weight:
 
 Vertex Groups Weights
-   Display weights in Edit Mode.
+   Visualize the weights of the active vertex group,
+   much like in :doc:`Weight Paint </sculpt_paint/weight_paint/introduction>` mode.
 
    .. _bpy.types.ToolSettings.vertex_group_user:
 

manual/editors/3dview/introduction.rst

@@ -110,3 +110,11 @@ The Sidebar region contains properties of the active object and tool,
 as well as of the viewport itself.
 
 See :doc:`Sidebar </editors/3dview/sidebar>` for more information.
+
+Asset Shelf Region
+==================
+
+Depending on the current mode, the asset shelf may be available, providing quick access to assets
+for this specific mode (for example pose assets in *Pose Mode*, brush assets in *Sculpt Mode*).
+
+See :ref:`ui-region-asset_shelf` for more information.

manual/editors/3dview/navigate/align.rst

@@ -32,7 +32,8 @@ Center View to Cursor
 
 View Lock to Active
    Centers the view on the active object and makes it the point of interest. The view
-   will continue orbiting around it even if you pan to a different location.
+   will continue orbiting around the object even if you pan to a different location.
+   In addition, it will follow the object if it moves.
 
 View Lock Clear
    Returns the view to how it was before using *View Lock to Active*.

manual/editors/3dview/navigate/regions.rst

@@ -105,6 +105,7 @@ Both Render Regions can exist at the same time.
      - .. figure:: /images/editors_3dview_navigate_regions_render-border-2.png
 
 .. note::
+
    Render regions only apply to the viewport when using Cycles, not when using EEVEE.
    However, they always affect the final render.
 

manual/editors/3dview/sidebar.rst

@@ -58,6 +58,12 @@ Local Camera
    separate from the global active camera that's defined in the scene.
    The selector next to the checkbox lets you choose this camera.
 
+.. _bpy.types.View3DOverlay.show_camera_passepartout:
+
+Passepartout
+   Show :ref:`camera passepartout <bpy.types.Camera.show_passepartout>`
+   when in :ref:`camera view <bpy.ops.view3d.view_camera>`.
+
 .. _bpy.types.SpaceView3D.use_render_border:
 
 Render Region

manual/editors/asset_browser.rst

@@ -14,12 +14,10 @@ expanded over multiple upcoming releases.
    :doc:`/files/asset_libraries/index`
       For general information on Blender's asset library system, including how to
       :ref:`create <asset-create>` and :ref:`edit <asset-edit>` assets, and design choices.
-
    :doc:`/files/asset_libraries/catalogs`
       For organizing assets.
-
    :doc:`/animation/armatures/posing/editing/pose_library`
-      Build on top of the Asset Browser.
+      Built on top of the Asset Browser.
 
 
 .. _bpy.ops.asset.catalog_undo:

manual/editors/dope_sheet/editing.rst

@@ -11,6 +11,8 @@ Select Menu
 .. seealso::
    :doc:`/interface/selecting`.
 
+.. _bpy.ops.action.select_all:
+
 All :kbd:`A`
    Selects all keyframes.
 None :kbd:`Alt-A`
@@ -32,6 +34,18 @@ Box Select (Axis Range) :kbd:`Alt-B`
 
 ----------
 
+More :kbd:`Ctrl-NumpadPlus`
+   Expand the selection to include the neighbors (in time) of the currently selected keys.
+Less :kbd:`Ctrl-NumpadMinus`
+   Deselect keyframes with fewer than two selected neighbors.
+
+----------
+
+Select Linked :kbd:`L`
+   Select keys that are on the same channel as a key that's already selected.
+
+----------
+
 Columns on Selected Keys :kbd:`K`
    Selects keys that are on the same frame as a key that's already selected.
 Column on Current Frame :kbd:`Ctrl-K`
@@ -50,18 +64,6 @@ After Current Frame :kbd:`]`
    Select the keys that lie after (or on) the current frame.
    You can also click :kbd:`Shift-Ctrl-LMB` anywhere to the right of the Playhead.
 
-----------
-
-Select More :kbd:`Ctrl-NumpadPlus`
-   Expand the selection to include the neighbors (in time) of the currently selected keys.
-Select Less :kbd:`Ctrl-NumpadMinus`
-   Deselect keyframes with fewer than two selected neighbors.
-
-----------
-
-Select Linked :kbd:`L`
-   Select keys that are on the same channel as a key that's already selected.
-
 .. _dopesheet-marker-menu:
 
 Marker Menu

manual/editors/dope_sheet/navigating.rst

@@ -29,6 +29,9 @@ Frame Selected :kbd:`NumpadPeriod`
    Pans and zooms the view to focus on the selected keyframes.
 Frame All :kbd:`Home`
    Pans and zooms the view to show all keyframes.
+Frame Scene/Preview Range
+   Reset the horizontal view to the current scene frame range,
+   taking the preview range into account if it is active.
 Go to Current Frame :kbd:`Numpad0`
    Pans the view so the Playhead is in the center.
 

manual/editors/geometry_node.rst

@@ -103,20 +103,6 @@ This tab allows you to edit the current node group's inputs and outputs.
    :doc:`/modeling/geometry_nodes/attributes_reference` for its outputs.
 
 
-Properties
-""""""""""
-
-.. _bpy.types.GeometryNodeTree.is_modifier:
-
-Modifier
-   The node group is used as a :doc:`/modeling/modifiers/generate/geometry_nodes`.
-
-.. _bpy.types.GeometryNodeTree.is_tool:
-
-Tool
-   The node group is used as a :doc:`/modeling/geometry_nodes/tools`.
-
-
 .. _editors-geometry_nodes-tool_context:
 
 Tool Context
@@ -163,3 +149,13 @@ Edit Mode
 
 Sculpt Mode
    The node group can be used in :doc:`Sculpt Mode </sculpt_paint/sculpting/index>`.
+
+
+Options
+-------
+
+.. _bpy.types.GeometryNodeTree.use_wait_for_click:
+
+Wait for Click
+   Wait for a mouse click input (:kbd:`LMB`) before running the operator from a menu.
+   This is useful for the :doc:`/modeling/geometry_nodes/input/scene/mouse_position`.

manual/editors/graph_editor/introduction.rst

@@ -108,6 +108,9 @@ Frame Selected :kbd:`NumpadPeriod`
    Pans and zooms the view to focus on the selected keyframes.
 Frame All :kbd:`Home`
    Pans and zooms the view to show all keyframes.
+Frame Scene/Preview Range
+   Reset the horizontal view to the current scene frame range,
+   taking the preview range into account if it is active.
 Go to Current Frame :kbd:`Numpad0`
    Centers the area to the Playhead.
 

manual/editors/image/editing.rst

@@ -93,6 +93,21 @@ Open the image in the *Image Editor* program specified in the
 :doc:`File Paths Preferences </editors/preferences/file_paths>`.
 
 
+.. _bpy.ops.image.clipboard:
+
+Copy/Paste
+==========
+
+.. reference::
+
+   :Mode:      All Modes
+   :Menu:      :menuselection:`Image --> Copy/Paste`
+
+Copy and pastes imaged to/from a computers operating system.
+
+Currently, only PNG files are supported and is only supported on Windows and Linux running Wayland.
+
+
 .. _bpy.ops.image.save:
 
 Save

manual/editors/image/introduction.rst

@@ -123,6 +123,15 @@ Display Channels
       Single color channel visualized as a grayscale image.
 
 
+Asset Shelf Region
+==================
+
+Depending on the current mode, the asset shelf may be available, providing quick access to assets
+for this specific mode (for example brush assets in *Paint* mode).
+
+See :ref:`ui-region-asset_shelf` for more information.
+
+
 Main View
 =========
 

manual/editors/image/navigating.rst

@@ -20,8 +20,20 @@ and zooming more comfortably when e.g. no mouse wheel is available.
 View Menu
 =========
 
-Region Controls
-   Adjust which regions are visible in the Image editor.
+.. _bpy.types.SpaceImageEditor.show_region:
+
+Toolbar :kbd:`T`
+   Show or hide the :ref:`Toolbar <ui-region-toolbar>`.
+Sidebar :kbd:`N`
+   Show or hide the :ref:`Sidebar <ui-region-sidebar>`.
+Tool Settings
+   Show or hide the settings for the currently selected tool.
+Asset Shelf
+   Toggle the visibility of the :ref:`ui-region-asset_shelf`.
+Adjust Last Operation
+   Displays a pop-up panel to alter properties of the last
+   completed operation. See :ref:`bpy.ops.screen.redo_last`.
+
 Update Automatically
    Instantly update any other editors that are affected by changes in this Image Editor.
    When disabled, the other editors may display outdated information until they're manually refreshed

manual/editors/nla/introduction.rst

@@ -57,6 +57,9 @@ Frame Selected :kbd:`NumpadPeriod`
    Pans and zooms the view to focus on the selected strips.
 Frame All :kbd:`Home`
    Pans and zooms the view to show all strips.
+Frame Scene/Preview Range
+   Reset the horizontal view to the current scene frame range,
+   taking the preview range into account if it is active.
 Go to Current Frame :kbd:`Numpad0`
    Centers the view on the Playhead.
 

manual/editors/nla/sidebar.rst

@@ -164,6 +164,7 @@ Lets you manually specify, and animate, the frame at which the underlying action
 is sampled.
 
 .. note::
+
    Although the setting is called *Strip Time*, its value is a frame number
    inside the action, not inside the strip. If you have an action going
    from frame 1 to frame 50 that's referenced by a strip going from frame

manual/editors/outliner/editing.rst

@@ -9,32 +9,49 @@ Context Menu
 ============
 
 Show the context menu for a data-block with :kbd:`RMB` on the icon or name.
-Depending on the type of the preselected data-block(s), you will have all or part of the following options:
+Depending on the type of the selected data-block(s), you will have all or part of the following options:
 
 Copy/Paste
-   Copy/pastes selected data-blocks.
+   Copies/pastes the selected data-blocks.
 
 .. _bpy.ops.outliner.delete:
 
-Delete
-   Deletes the selected data-block.
+Delete :kbd:`X`, :kbd:`Delete`
+   Removes all usages of the selected data-blocks. Objects are removed from all scenes,
+   materials are removed from all meshes, and so on.
 
-Select, Select Hierarchy, Deselect
-   Add object to current selection without making it the active one.
+.. note::
+   Pressing these shortcuts while hovering over the 3D Viewport will instead *Unlink* the selected objects,
+   removing them only from the current scene.
 
+Delete Hierarchy
+   As above, but also affects child collections/objects. Note that if you run this on a collection,
+   child objects that (also) belong to another collection will not be deleted.
+
+Select
+   Adds the items that are selected in the Outliner to the selection in the 3D Viewport. This is only
+   useful when :ref:`Sync Selection <bpy.types.SpaceOutliner.use_sync_select>` is disabled,
+   as when it's enabled (which is the default), the Outliner selection is synchronized to the
+   3D Viewport automatically.
+
+Select Hierarchy
+   Adds the children of the selected items to the selection in the Outliner. If *Sync Selection* is enabled,
+   this also adds them to the selection in the 3D Viewport.
+
+Deselect
+   Removes the items that are selected in the Outliner from the selection in the 3D Viewport.
+
+Unlink
+   Removes the current usage of the data-block while keeping any others. Objects are only removed
+   from the current scene, materials are only removed from the current mesh, and so on.
 
 .. _editors-outliner-editing-collections:
 
 Collections
 -----------
 
-Collections are a way Blender uses to organize scenes.
-Collections contain objects and everything else in a scene.
-They can include collections themselves and are fully recursive.
-
-.. seealso::
-
-   Read more about :doc:`Collections </scene_layout/collections/index>`.
+:doc:`Collections </scene_layout/collections/index>` let you organize the content of a scene.
+They can contain objects as well as other collections.
 
 .. _bpy.ops.outliner.collection_new:
 
@@ -49,13 +66,8 @@ Duplicate Collections
 .. _bpy.ops.outliner.collection_duplicate_linked:
 
 Duplicate Linked
-   Duplicate entire hierarchy keeping content linked with original.
-
-Delete Hierarchy
-   Deletes the collection and removes all its child objects or collections.
-   It is important to note that this only deletes the collection,
-   if child objects are part of another collection they will stay in the scene collection
-   and their data-blocks will not be deleted from the blend-file.
+   Recursively duplicates the collection including child collections and objects,
+   but reuses object data.
 
 .. _bpy.ops.outliner.collection_instance:
 
@@ -68,32 +80,36 @@ Visibility
    .. _bpy.ops.outliner.collection_isolate:
 
    Isolate
-      Hides all collections except the selected collection and any parent collections (if any exist).
+      Shows the selected collection (as well as its child and parent collections)
+      and hides all the others.
 
    .. _bpy.ops.outliner.collection_show:
    .. _bpy.ops.outliner.collection_hide:
 
    Show/Hide
-      Shows/Hides the selected collection from the :doc:`View Layer </scene_layout/view_layers/index>`.
+      Changes the :ref:`Hide in Viewports <bpy.types.LayerCollection.hide_viewport>` setting
+      for the selected collections.
 
    .. _bpy.ops.outliner.collection_show_inside:
    .. _bpy.ops.outliner.collection_hide_inside:
 
    Show/Hide Inside
-      Shows/Hides all items that are a member of the selected collection, include child collections,
-      from the :doc:`View Layer </scene_layout/view_layers/index>`.
+      Changes the :ref:`Hide in Viewports <bpy.types.LayerCollection.hide_viewport>` setting
+      for the selected collections and all their children.
 
    .. _bpy.ops.outliner.collection_enable:
    .. _bpy.ops.outliner.collection_disable:
 
    Enable/Disable in Viewports
-      Enables/disables drawing in the :doc:`View Layer </scene_layout/view_layers/index>`.
+      Changes the :ref:`Disable in Viewports <bpy.types.Collection.hide_viewport>` setting
+      for the selected collections.
 
    .. _bpy.ops.outliner.collection_enable_render:
    .. _bpy.ops.outliner.collection_disable_render:
 
    Enable/Disable in Renders
-      Enables/disables visibility of the collection in renders.
+      Changes the :ref:`Disable in Renders <bpy.types.Collection.hide_render>` setting
+      for the selected collections.
 
 View Layer
    Controls the collection's interactions with the :doc:`View Layer </render/layers/introduction>`.
@@ -102,7 +118,12 @@ View Layer
    .. _bpy.ops.outliner.collection_exclude_set:
 
    Disable/Enable in View Layer
-      Disables/Enables the collection from the view layer.
+      Changes the :ref:`Exclude from View Layer <bpy.types.LayerCollection.exclude>` setting
+      for the selected collections.
+
+   Set/Clear Holdout
+      Changes the :ref:`Holdout <bpy.types.LayerCollection.holdout>` setting
+      for the selected collections.
 
 .. _bpy.ops.outliner.collection_color_tag_set:
 
@@ -117,42 +138,28 @@ ID Data
 -------
 
 Unlink
-   To unlink a data-block from its "owner" (e.g. a material from its mesh).
+   Removes the current usage of the data-block while keeping any others
+   (e.g. removing a material from only the current mesh).
 Make Local
-   To create a "local" duplicate of this data-block.
+   Turns an :doc:`externally linked </files/linked_libraries/link_append>` data-block into a local one.
 Make Single User
-   This feature is not yet implemented.
+   This menu item is not currently functional. You can use the *User Count* button in the
+   :doc:`/interface/controls/templates/data_block` instead.
 Delete
    Deletes the selected data-block.
-Make Library Override
-   Make a local :doc:`override </files/linked_libraries/library_overrides>` of this linked data-block.
-Make Library Override Hierarchy
-   Make a local :doc:`override </files/linked_libraries/library_overrides>` of this linked data-block,
-   and its hierarchy of dependencies.
-Reset Library Override
-   Reset this local :doc:`override </files/linked_libraries/library_overrides>` to its linked values.
-Reset Library Override Hierarchy
-   Reset this local :doc:`override </files/linked_libraries/library_overrides>` to its linked values,
-   as well as its hierarchy of dependencies. This allows you to update local overrides
-   when the relationship between data-blocks changed in the linked library data.
-Resync Library Override Hierarchy
-   Rebuilds the local :doc:`override </files/linked_libraries/library_overrides>`
-   from its linked reference, as well as its hierarchy of dependencies.
-Delete Library Override Hierarchy
-   Deletes the local :doc:`override </files/linked_libraries/library_overrides>`
-   (including its hierarchy of override dependencies) and relinks its users to the linked data-blocks.
 Remap Users
-   Remap Users of a data-block to another one (of same type of course).
-   This means you can e.g. replace all usages of a material or texture by another one.
+   Replaces all usages of the selected data-block by a different one. For example,
+   you could use this to globally replace a material by another.
 Copy/Paste
-   Copy/pastes selected data-blocks.
-Add Fake User, Clear Fake User
-   Adds a "dummy" (fake) user so that the selected data-block always gets saved even if it has no users.
-   The fake user can be removed with *Clear Fake User*.
+   Copies/pastes selected data-blocks.
+Add/Clear Fake User
+   Adds/removes a :ref:`fake user <data-system-datablock-fake-user>`, which prevents unused data-blocks
+   from getting automatically deleted when saving and reloading the blend-file.
 Rename :kbd:`F2`
    Renames the selected data-block.
 Select Linked
-   Selects the linked data, see :ref:`bpy.ops.object.select_linked` for more information.
+   Selects the data-blocks that use the currently selected one (e.g. selecting all the objects that use the
+   selected material). See :ref:`bpy.ops.object.select_linked`.
 
 
 Mark as Asset
@@ -173,22 +180,31 @@ Clear Asset (Set Fake User)
 See :ref:`assets-clear-set-fake-user`.
 
 
+Library Override
+----------------
+
+See :doc:`/files/linked_libraries/library_overrides`.
+
+
 View
 ----
 
-The view menu is part of the context menu and supported in all the Outliner elements.
-
 .. _bpy.ops.outliner.show_active:
 
 Show Active :kbd:`Period`
-   Centers the Tree View to selected object.
+   Centers the tree view to the active item.
+
+.. _bpy.ops.outliner.expanded_toggle:
+
+Expand/Collapse All :kbd:`Shift-A`
+   Expands/collapses every single item in the tree.
 
 .. _bpy.ops.outliner.show_hierarchy:
 
-Show Hierarchy :kbd:`Home`
-   To collapse all levels of the tree.
+Show Object Hierarchy :kbd:`Home`
+   Expands all objects that have child objects, and collapses all objects that don't.
 
 .. _bpy.ops.outliner.show_one_level:
 
 Show/Hide One Level :kbd:`NumpadPlus`/ :kbd:`NumpadMinus`
-   Expand one level down in the tree or collapse one level using the keyboard shortcuts.
+   Expands/collapses a level down/up the tree across all items.

manual/editors/outliner/interface.rst

@@ -11,52 +11,57 @@ Header
 Display Mode
 ------------
 
-The editors header has a select menu that let you filter what the Outliner should show.
-It helps to narrow the list of objects so that you can find things quickly and easily.
+This header dropdown lets you choose what the Outliner should show.
 
 :Scenes:
-   Shows *everything* the *Outliner* can display (in all scenes, all view layers, etc.).
+   Shows the :doc:`view layers </scene_layout/view_layers/introduction>`,
+   :doc:`collections </scene_layout/collections/introduction>`,
+   and objects across all scenes.
 :View Layer:
-   Shows all the collections and objects in the current view layer.
+   Shows the collections and objects in the current view layer of the current scene.
 :Video Sequencer:
-   Lists data, images and videos, that are used by the :doc:`Video Sequencer </video_editing/index>`.
+   Shows the images and videos that are used in the :doc:`Video Sequencer </video_editing/index>`.
+
+.. _outliner-blender-file-mode:
+
 :Blender File:
-   Lists all data in the current blend-file.
+   Lists all data in the current blend-file. On the right side of the list, a shield icon shows the number
+   of users -- clicking it adds or removes a :ref:`fake user <data-system-datablock-fake-user>`.
 :Data API:
-   Lists every :doc:`data-block </files/data_blocks>` along with any properties that they might have.
+   Lists every :doc:`data-block </files/data_blocks>` in the file along with any properties that it might have.
 :Library Overrides:
-   Display library override data in the current blend-file. Separated further into two view modes:
+   Shows the :doc:`library overrides </files/linked_libraries/library_overrides>`.
+   Separated further into two view modes:
 
    .. _bpy.types.SpaceOutliner.lib_override_view_mode:
 
-   Library Overrides Display Mode
-      :Properties:
-         Display data-blocks with overridden properties. The overridden properties are listed together with widgets to
-         modify the value of the properties.
-      :Hierarchies:
-         Visualize the hierarchical dependencies between data-blocks with library overrides. For example, to create a
-         library override of a mesh used by an object inside of a linked collection, Blender automatically creates
-         (disabled) library overrides for the object and the collection, resulting in a collection > object > mesh
-         library override hierarchy.
+   :Properties:
+      Shows the data-blocks that have overridden properties in a list grouped by type.
+      You can expand each data-block to see and change these properties.
+   :Hierarchies:
+      Shows the overridden data-blocks in a tree that visualizes their hierarchy.
+      This includes parent data-blocks that were overridden implicitly.
+      For example, if you created an override for a material,
+      this tree would show the hierarchy object > mesh > material.
 
       .. _bpy.ops.ed.lib_id_override_editable_toggle:
 
-   This library override view mode has a column on the right side
-   of the editor to toggle if the library is editable or not.
+      This view also shows a column of icons on the right that let you toggle whether
+      each override is editable.
 :Unused Data:
-   Lists :doc:`data-blocks </files/data_blocks>` and other data
-   that are unused and/or will be lost when the file is reloaded.
-   It includes data-blocks which have only a fake user. You can add/remove the Fake User
-   by clicking on cross/tick icon on the right side of the Outliner editor.
+   Lists the data-blocks that are unused or only have a :ref:`fake user <data-system-datablock-fake-user>`.
+   You can add/remove a fake user by clicking the shield icon on the right.
 
+   Unused data-blocks are automatically deleted when saving and reloading the file.
+   You can also delete them manually by clicking *Purge* in the header.
 
 .. _bpy.types.SpaceOutliner.filter_text:
 
-Display Filter
---------------
+Search
+------
 
-You can search the view for data-blocks,
-by using Search field in the header of the *Outliner*,
+The textbox lets you filter the tree by typing a substring. You can focus it using :kbd:`Ctrl-F`
+or clear it using :kbd:`Alt-F`.
 
 
 .. _editors-outliner-interface-filter:
@@ -64,10 +69,13 @@ by using Search field in the header of the *Outliner*,
 Filter
 ------
 
+The funnel icon in the header offers further control over what is displayed in the editor.
+Depending on the *Display Mode*, some options are not available.
+
 .. _bpy.types.SpaceOutliner.show_restrict_column:
 
 Restriction Toggles
-   Set which `Restriction Columns`_ should be visible.
+   Set which `Restriction Toggles`_ should be visible.
 
 .. _bpy.types.SpaceOutliner.use_sort_alpha:
 
@@ -77,15 +85,14 @@ Sort Alphabetically
 .. _bpy.types.SpaceOutliner.use_sync_select:
 
 Sync Selection
-   Sync Outliner selection to and from the :doc:`3D Viewport </editors/3dview/index>` and
-   :doc:`Video Sequencer </video_editing/index>` editors. Disable to manage collections,
-   object relations, and scene data without changing the selection state.
-   Selection syncing is only available in Scenes, View Layer, and Video Sequencer display modes.
+   Whether to synchronize the Outliner selection to and from the
+   :doc:`3D Viewport </editors/3dview/index>` and
+   :doc:`Video Sequencer </video_editing/index>` editors.
 
 .. _bpy.types.SpaceOutliner.show_mode_column:
 
 Show Mode Column
-   Show the object mode toggling column in View Layer and Scenes display modes.
+   Show the column for toggling the :doc:`object interaction mode </editors/3dview/modes>`.
 
 
 .. rubric:: Search
@@ -93,71 +100,68 @@ Show Mode Column
 .. _bpy.types.SpaceOutliner.use_filter_complete:
 
 Exact Match
-   The results of :ref:`bpy.types.SpaceOutliner.filter_text` must match the full text and not just a part of it.
+   Only show the items whose name fully matches the :ref:`search text <bpy.types.SpaceOutliner.filter_text>`
+   rather than only containing it as a substring.
 
 .. _bpy.types.SpaceOutliner.use_filter_case_sensitive:
 
 Case Sensitive
-   The results of :ref:`bpy.types.SpaceOutliner.filter_text` are case sensitive.
+   Take lower/upper case into account when comparing the search text to the item names.
 
 
 .. rubric:: Filter
 
-Some options will only show if compatible with the active `Display Mode`_.
-
 .. _bpy.types.SpaceOutliner.use_filter_view_layers:
 
 All View Layers
-   Toggle between only the active or all the :doc:`view layers </scene_layout/view_layers/index>` of the scene.
-   Combined with disabling the *Objects* filter it gives a compact overview of all the collections in relation
+   Show all the :doc:`view layers </scene_layout/view_layers/index>` in the scene instead of only the active one.
+   Combined with disabling the *Objects* filter, this gives a compact overview of all the collections in relation
    to the view layers.
 
 .. _bpy.types.SpaceOutliner.use_filter_collection:
 
 Collections
-   List the objects and collections under
-   the :doc:`collection hierarchy </scene_layout/collections/index>` of the scene.
-   Objects may appear in more than one collection.
+   Show the collections in the scene hierarchy. Only the collections themselves are hidden when this option
+   is disabled; the objects within them remain visible.
 
 .. _bpy.types.SpaceOutliner.use_filter_object:
 
 Objects
-   List of all the objects, respecting the other filter options.
-   Disabled only if you need an overview of the collections without the objects.
+   Show the objects in the scene hierarchy. Disabling this gives you an overview of just the collections.
 
 .. _bpy.types.SpaceOutliner.filter_invert:
 .. _bpy.types.SpaceOutliner.filter_state:
 
 Object State
    List the objects based on their state or restrictions.
-   The results can be inverted using the *Invert* button.
+   The results can be inverted using the *Invert* toggle button.
 
    :All:
-      The default option, no restrictions.
+      Show all objects.
    :Visible:
-      List only the objects visible in the viewports.
-      The global and temporary visibility settings are taken into consideration.
-   :Invisible:
-      List only the objects not visible in the viewports.
+      Only show the objects that are visible in the 3D Viewport.
+      This takes both the *Hide in Viewports* and *Disable in Viewports* settings into account;
+      see :ref:`editors-outliner-interface-restriction_columns`.
    :Selected:
-      Lists the object(s) that are currently selected in the 3D Viewport.
-      See :doc:`selecting in the 3D Viewport </scene_layout/object/selecting>` for more information.
+      Only show the object(s) that are currently :doc:`selected </scene_layout/object/selecting>`
+      in the 3D Viewport.
    :Active:
-      Lists only the active (often last selected) object.
+      Only show the active object (typically the one that was selected last).
    :Selectable:
-      List all objects whose :ref:`Selectability <bpy.types.Collection.hide_select>` option is enabled.
+      Only show the objects that can be selected in the 3D Viewport;
+      see :ref:`editors-outliner-interface-restriction_columns`.
 
 .. _bpy.types.SpaceOutliner.use_filter_object_content:
 
 Object Contents
-   List materials, modifiers, mesh data, ...
+   List relevant materials, modifiers, mesh data and so on as children of each object.
 
 .. _bpy.types.SpaceOutliner.use_filter_children:
 
 Object Children
-   List the object children. If the *Collections* option is enabled,
-   you will see the object children even if the children are not in the collection.
-   Yet the Outliner shows them as a dashed line.
+   Show :doc:`child objects </scene_layout/object/editing/parent>` as child nodes in the Outliner tree.
+   When disabled, child objects are shown as sibling nodes instead (unless they're in a different collection
+   than their parent, in which case they're not shown in the parent's collection at all).
 
 .. _bpy.types.SpaceOutliner.use_filter_object_mesh:
 .. _bpy.types.SpaceOutliner.use_filter_object_light:
@@ -166,108 +170,163 @@ Object Children
 .. _bpy.types.SpaceOutliner.use_filter_object_empty:
 .. _bpy.types.SpaceOutliner.use_filter_object_others:
 
-Data-Block
-   Allows you to filter out certain data-blocks currently present in the scene.
+Meshes/Lights/...
+   Lets you filter out objects by type.
 
 .. _bpy.types.SpaceOutliner.use_filter_lib_override_system:
 
 System Overrides
-   Shows the data-block properties that are defined/controlled automatically (e.g. to make users of an overridden
-   data-block point to the override data, not the original linked data). Only available in the *Library Overrides*
+   Shows the data-block properties that are defined/controlled automatically (e.g. to make data-blocks
+   point to overridden data instead of the original). Only available in the *Library Overrides*
    `Display Mode`_.
 
 
-.. _bpy.ops.outliner.orphans_purge:
-
 Miscellaneous
 -------------
 
 Some options in the header will only show if compatible with the active `Display Mode`_.
 
-New Collection (View Layer)
-   Add a new collection inside selected collection.
-Filter by Type (Orphan Data, Blender File)
+New Collection :guilabel:`View Layer`
+   Add a new collection inside the selected one.
+Filter by Type :guilabel:`Blender File` :guilabel:`Unused Data`
    Restrict the type of the data-blocks shown in the Outliner.
-Keying Sets (Data API)
-   Add/Remove selected data to the active :doc:`Keying Set </animation/keyframes/keying_sets>`.
+Keying Sets (Data API) :guilabel:`Data API`
+   Add/Remove the selected property to/from the active :doc:`Keying Set </animation/keyframes/keying_sets>`.
 Drivers
    Add/Remove :doc:`Drivers </animation/drivers/index>` to the selected item.
-Purge (Orphan Data)
-   Recursively remove all unused data-blocks from the file (cannot be undone).
+
+.. _bpy.ops.outliner.orphans_purge:
+
+Purge (Orphan Data) :guilabel:`Unused Data`
+   Opens a dialog to remove unused data-blocks from both the current blend-file or any
+   :doc:`Linked Data </files/linked_libraries/link_append>` (cannot be undone).
+
+   Local Data-Blocks
+      Removes unused data-blocks from the current blend-file.
+   Linked Data-Blocks
+      Removes unused data-blocks from :doc:`Linked Data </files/linked_libraries/link_append>`.
+   Recursive Delete
+      Removes data-blocks only used by unused data-blocks,
+      ensuring that no orphaned data-blocks remain after execution.
 
 
 Main Region
 ===========
 
-Object Mode
------------
+Object Interaction Mode
+-----------------------
 
-The far left of the Outliner contains a region to toggle the current :doc:`Object Mode </editors/3dview/modes>`.
-When an object is in a mode other than Object Mode, the mode icon will be displayed in this region.
-Any other objects that are valid to be added or swapped into the current mode display a dot.
-Clicking the dot icon will swap that object with the current active object.
-For modes that support :ref:`3dview-multi-object-mode`,
-:kbd:`Ctrl-LMB` on the dot icon will add that object to the current mode.
-Clicking the mode icon next to the active object removes it or all other objects
-from the current mode depending if multiple object are in the same mode.
+.. figure:: /images/editors_outliner_interface_mode-icons.png
+
+   Mode icons. Two objects are currently in Edit Mode; a third could be added.
+
+If a selected object is in an :doc:`interaction mode </editors/3dview/modes>`
+other than the default Object Mode, the Outliner shows an icon representing
+this mode on the left.
+
+If the active object has such an icon, the Outliner also shows a dot next to
+objects of the same type. You can click such a dot to switch over to a different
+object while staying in the same mode.
+
+If the mode supports :ref:`3dview-multi-object-mode`, you can also click a
+dot with :kbd:`Ctrl-LMB` to *add* an object to the mode.
+
+You can click the mode icon of the active object to switch it (and any other objects
+in case of Multi-Object Editing) back to Object Mode. You can also :kbd:`Ctrl-LMB`
+the mode icon of a selected -- but not active -- object to switch only that object
+back to Object Mode.
 
 
 .. _editors-outliner-interface-restriction_columns:
 
-Restriction Columns
+Restriction Toggles
 -------------------
 
-The following toggles, in the right side of the *Outliner* editor,
-are available for collections, objects, bones, modifiers and constraints.
+.. figure:: /images/editors_outliner_interface_restriction-toggles.png
+   :align: right
 
-By default only the temporary viewport visibility is enabled.
-The other options can be enabled in the *Restriction Toggles* option in the Outliner `filter`_.
+   Restriction toggles.
 
-- Holding :kbd:`Shift` sets or unsets the value to all its child collections or objects.
-- Holding :kbd:`Ctrl` isolates the object or collection, so they are the only ones with its value set.
+The right side of the Outliner shows a series of toggle icons for every collection,
+object, bone, modifier, and constraint. These can be used to make the item invisible,
+unselectable, and so on.
+
+.. note::
+   Only a few icons are shown by default. You can use the `Filter`_ pop-over to
+   show additional ones.
+
+Clicking an icon with :kbd:`Shift-LMB` toggles it for the item and all its children.
+
+Clicking a collection's icon with :kbd:`Ctrl-LMB` enables it for the collection (and its
+parent/child collections) and disables it for all others. Clicking again enables it for the others again.
 
 .. _bpy.types.LayerCollection.exclude:
 
-Enable Collection (checkbox, collection only)
-   Exclude the collection from the view layer.
-
-Visibility (eye icon)
-   Toggles the visibility of the object or collection in the 3D Viewport.
-   This is a file-local setting, and does not get imported when this data-block
-   is linked into another blend-file. Objects hidden this way are still part of
-   the :doc:`View Layer </scene_layout/view_layers/index>` and evaluated,
-   so they still affect playback performance.
-
-.. note::
-
-   The following options are hidden by default and need to be enabled in
-   the Outliner Filter before they can be used.
+Exclude from View Layer (checkbox) :guilabel:`Collections`
+   Uncheck to disable the collection for the current :doc:`View Layer </scene_layout/view_layers/index>`.
+   Its contents will be hidden in the 3D Viewport, the render, and even the Outliner.
 
 .. _bpy.types.Collection.hide_select:
 
-Selectability (mouse cursor icon)
-   Toggles the ability to select the objects from the 3D Viewport.
-   This is useful for if you have placed something in the scene
-   and do not want to accidentally select it when working on something else.
+Disable Selection (mouse cursor icon)
+   Toggles whether the object can be selected in the 3D Viewport. This can be useful for, say,
+   references images that you only want to display and never select/move.
 
 .. _bpy.types.LayerCollection.hide_viewport:
 
-Global Viewport Visibility (screen icon)
-   This will still render the object/collection, but it will be ignored by all the viewports.
-   Often used for collections with high-poly objects that need to be instanced in other files.
-   Objects hidden this way are no longer part of the :doc:`View Layer </scene_layout/view_layers/index>`,
-   are not evaluated, and such do not negatively affect playback performance.
+Hide in Viewports (eye icon)
+   Toggles the visibility of the object or collection in (only) the 3D Viewport, for the current view layer.
+   The render is not affected.
 
-Rendering (camera icon)
-   This will still keep the object visible in the scene, but it will be ignored by the renderer.
-   Usually used by support objects that help modeling and animation yet do not belong in the final images.
+   As an alternative to clicking this icon, you can press :kbd:`H` while hovering over the
+   3D Viewport to hide the selected objects, or :kbd:`Alt-H` to unhide all objects.
+
+   This setting only applies within the current blend-file: when you
+   :doc:`Link or Append </files/linked_libraries/link_append>` it to another
+   blend-file, all collections and objects will be visible there.
+
+   Objects hidden this way are still part of the view layer,
+   so they still get evaluated and affect playback performance.
+
+   .. seealso::
+
+      Collections can be hidden for individual 3D Viewports;
+      see :ref:`Local Collections <bpy.types.SpaceView3D.use_local_collections>` in the Sidebar.
+
+.. _bpy.types.Collection.hide_viewport:
+
+Disable in Viewports (screen icon)
+   Toggles the visibility of the object or collection in (only) the 3D Viewport, for all view layers.
+   The render is not affected.
+
+   This setting is separate from *Hide in Viewports*. An object needs to have both settings
+   enabled to be visible. You can use this one for "long-term invisibility,"
+   keeping an object invisible even after pressing :kbd:`Alt-H`.
+
+   This setting carries over to other blend-files when linking or appending.
+
+   Objects hidden this way are no longer part of the view layer,
+   so they no longer get evaluated and don't affect playback performance.
+
+.. _bpy.types.Collection.hide_render:
+
+Disable in Renders (camera icon)
+   Toggles the visibility of the object or collection in (only) the render,
+   for all view layers. The 3D Viewport is not affected.
+
+   This is typically used for supporting objects that help modeling and animation
+   yet don't belong in the final image.
 
 .. _bpy.types.LayerCollection.holdout:
 
-Holdout (collection only)
-   Mask out objects in collection from view layer.
+Holdout :guilabel:`Collections`
+   Makes the objects in the collection cut a fully transparent hole into the
+   render output of the view layer.
+
+   .. seealso::
+      :doc:`Holdout Shader Node </render/shader_nodes/shader/holdout>`
 
 .. _bpy.types.LayerCollection.indirect_only:
 
-Indirect Only (collection only)
-   Objects in these collections only contribute to indirect light -- *Cycles only*.
+Indirect Only :guilabel:`Collections` :guilabel:`Cycles`
+   Objects in the collection only contribute to indirect light.

manual/editors/outliner/introduction.rst

@@ -9,25 +9,18 @@ Introduction
 
    The Outliner editor.
 
-The *Outliner* is a list that organizes data in the blend-file,
-i.e. the scene data, Video Sequencer data, or anything that gets stored in a blend-file.
-The *Outliner* can be used to:
+The *Outliner* shows the content of the blend-file in a tree. You can use it to:
 
-- View the data in the scene.
-- Select and deselect objects in the scene.
-- Hide or show an object in the scene.
-- Enable or disable selection (to make an object "unselectable" in the 3D Viewport).
-- Enable or disable the rendering of an object.
-- Delete objects from the scene.
-- Unlink data (equivalent to pressing the *X* button next to the name of a data-block).
-- Manage collections in the scene.
+- Get an overview of the data in the scene.
+- Select and deselect objects.
+- Make objects unselectable or invisible in the 3D Viewport.
+- Exclude objects from rendering.
+- Duplicate objects.
+- Delete objects.
+- Manage parent/child relationships and :doc:`collections </scene_layout/collections/introduction>`.
 
-.. (TODO) create new objects by drag & drop from the outliner
-
-Each row in the *Outliner* shows a data-block. You can :kbd:`LMB` click the disclosure triangle to
-the left of a name to expand the current data-block and see what other data-blocks it contains.
-Holding :kbd:`Shift` when clicking on the disclosure triangle will expand child data-blocks recursively.
-:kbd:`LMB` Clicking and dragging along disclosure triangles will expand or collapse multiple data-blocks.
+Items with an arrow on the left can be expanded. Click it with :kbd:`LMB` to expand a single item,
+drag :kbd:`LMB` to expand multiple items, or click :kbd:`Shift-LMB` to expand an item recursively.
 
 
 Example

manual/editors/outliner/selecting.rst

@@ -1,7 +1,7 @@
 
-************************
-Selecting and Activating
-************************
+*********
+Selecting
+*********
 
 .. figure:: /images/editors_outliner_selecting_example.png
    :align: right
@@ -71,7 +71,6 @@ Keyboard selection and navigation starts from the active data-block.
 Properties Editor Sync
 ======================
 
-When clicking the data-block icons or any other data icon (modifiers, constraints, object data, etc.),
-:doc:`/editors/properties_editor` will change to the corresponding tab to modify the properties of
-that data-block.This feature can be enabled or disabled in Properties editor using
-the :ref:`Sync with Outliner <bpy.types.SpaceProperties.outliner_sync>` option.
+When clicking the icon (not the name) of an item in the Outliner, the :doc:`/editors/properties_editor`
+editor will automatically switch to the relevant tab. This feature can be disabled using
+the Properties editor's :ref:`Sync with Outliner <bpy.types.SpaceProperties.outliner_sync>` option.

manual/editors/outliner/usage.rst

@@ -11,13 +11,13 @@ Relations Management
 
    Linking objects to a collection.
 
-Data-blocks can be dragged and dropped to manage data relations in the Outliner.
-To begin a drag and drop, :kbd:`LMB` click and drag from the name or icon of a data-block.
+You can move an object (or collection) to a different parent collection by dragging and dropping.
 
-Objects can be moved to collections by dropping on the name or contents of a collection.
-To link an object to a collection, hold :kbd:`Ctrl` while dropping.
-To set parent-child relations between objects, drop an object onto another object
-while holding :kbd:`Shift`.
+You can link an object (or collection) to a parent collection by dragging and then holding
+:kbd:`Ctrl` while dropping. This way, you can make the object (or child collection) part of
+multiple parent collections at the same time.
+
+You can parent an object to another by dragging and then holding :kbd:`Shift` while dropping.
 
 .. note::
 
@@ -25,26 +25,26 @@ while holding :kbd:`Shift`.
    that are incompatible with the operation will remain unmodified.
 
 
-Modifiers, Constraints, & Visual Effects
-========================================
+Modifiers, Constraints, and Visual Effects
+==========================================
 
 You can manage :doc:`Modifiers </modeling/modifiers/index>`, :doc:`Constraints </animation/constraints/index>`, and
-:doc:`Visual Effects </grease_pencil/visual_effects/index>` from the Outliner in a couple ways:
+:doc:`Visual Effects </grease_pencil/visual_effects/index>` from the Outliner in a couple of ways:
+
+- You can drag and drop individual items to change their order within the :ref:`stack <modifier-stack>` or to copy
+  them to another object.
+- You can drag and drop the group item (e.g. *Modifiers*) to copy the whole stack to another object.
+  The target object's existing stack will be replaced.
+- You can apply and delete items using the context menu.
 
-- To change the order within the :ref:`stack <modifier-stack>`
-  select the desired modifier and move it above or below other modifiers.
-- To apply a single modifier, right click on the modifier and select apply in the popover menu.
-- To delete a single modifier, right click on the modifier and select delete in the popover menu.
-- To copy a single modifier to another, select the modifier and drag it on top of the desired object.
-- To copy the whole modifier stack to another object, select the modifier icon and drag in to the desired object.
 
 Drag & Dropping to 3D Viewport
 ==============================
 
-Objects & Object Data
----------------------
+Dragging an object from the Outliner to the :doc:`3D Viewport </editors/3dview/index>`
+creates a :doc:`duplicate </scene_layout/object/editing/duplicate>` -- a new object with its own copy
+of the underlying object data.
 
-Dragging object data-blocks from the Outliner to the :doc:`3D Viewport </editors/3dview/index>`
-creates a :doc:`duplicate </scene_layout/object/editing/duplicate>` of the object.
-Dragging *object data* data-blocks from the Outliner to the 3D Viewport
-creates a :doc:`linked duplicate </scene_layout/object/editing/duplicate_linked>` of the object.
+Dragging object data from the Outliner to the 3D Viewport creates a
+:doc:`linked duplicate </scene_layout/object/editing/duplicate_linked>` -- a new object that references
+the same underlying object data.

manual/editors/preferences/addons.rst

@@ -0,0 +1,109 @@
+
+*******
+Add-ons
+*******
+
+The Add-ons section lets you manage secondary scripts, called “Add-ons” that extends Blender's functionality.
+Most of the time you can get add-ons as part of the :ref:`Extensions <extensions-index>` system.
+
+In this section you can search, install, enable and disable Add-ons.
+
+.. tip::
+
+   If the Add-on does not activate when enabled,
+   check the :ref:`Console window <command_line-index>`
+   for any errors that may have occurred.
+
+
+Filtering Add-ons
+=================
+
+.. _bpy.types.WindowManager.addon_search:
+
+Search Add-ons
+    Blender comes with some preinstalled Add-ons already, ready to be enabled. But you can also add your own, or any 
+    interesting ones you find on the web.
+
+.. _bpy.types.PreferencesView.show_addons_enabled_only:
+
+Enabled Add-ons Only
+    Shows only enabled add-ons for the current Category.
+
+Add-on Tags
+    Add-ons are assigned categories by what areas of Blender they affect.
+
+
+Add-on Settings
+===============
+
+Refresh Local
+   Scan extension & legacy add-ons for changes to modules & meta-data (similar to restarting). Any issues are 
+   reported as warnings.
+Install from Disk
+   Install an extension from a ``.zip`` package.
+   This is installed to a Local Repository and no updates will be available.
+
+   This can also be used to install legacy Add-ons, for more information see:
+   :ref:`prefs-extensions-install_legacy_addon`.
+
+
+.. _bpy.ops.preferences.addon_enable:
+.. _bpy.ops.preferences.addon_disable:
+
+Enabling & Disabling Add-ons
+============================
+
+To enable or disable an add-on check or uncheck the box to the right of the add-ons.
+
+The add-on functionality should be immediately available.
+
+
+Add-on Information
+==================
+
+You can click the arrow at the left of the add-on box to see more information,
+such as its location, a description and a link to the documentation.
+Here you can also find a button to report a bug specific of this add-on.
+
+.. _bpy.types.AddonPreferences:
+
+Add-on Preferences
+------------------
+
+Some add-ons may have their own preferences which can be found
+in the *Preferences* section of the add-on information box.
+
+Some add-ons use this section for example to enable/disable
+certain functions of the add-on. Sometimes these might even all default to off.
+So it is important to check if the enabled add-on has any particular preferences.
+
+
+
+.. _prefs-extensions-install_legacy_addon:
+
+Installing Legacy Add-ons
+=========================
+
+To install legacy add-ons, click the *Install from Disk* menu item and select the add-on's
+``.py`` file (if it has only one such file) or its ``.zip`` file.
+
+The add-on will not be automatically enabled after installation; click the checkbox to do that.
+
+Refresh
+   Scans the :ref:`Add-on Directory <blender-directory-layout>` for new add-ons.
+
+.. tip::
+
+   While this screen doesn't allow installing a folder-based addon with loose ``.py`` files,
+   you can still do so by adding it as a :ref:`Script Directory <bpy.types.ScriptDirectory>`:
+
+   #. Create an empty directory in a location of your choice (e.g. ``my_scripts``).
+   #. Add a subdirectory under ``my_scripts`` called ``addons``
+      (it *must* have this name for Blender to recognize it).
+   #. Place your addon folder inside this ``addons`` folder.
+   #. Open the *File Paths* section of the *Preferences*.
+   #. Add a *Script Directories* entry pointing to your script folder (e.g. ``my_scripts``).
+   #. Save the preferences and restart Blender for it to recognize the new add-on location.
+
+   The add-ons in this folder will automatically become available; all you need to
+   do is enable them.

manual/editors/preferences/extensions.rst

@@ -2,12 +2,13 @@
 .. _bpy.ops.wm.addon:
 .. _bpy.types.WindowManager.addon:
 .. _bpy.ops.preferences.addon:
+.. _prefs-extensions:
 
-**********
-Extensions
-**********
+**************
+Get Extensions
+**************
 
-The *Extensions* section lets you manage the extensions preferences.
+The *Get Extensions* section lets you install and manage extensions preferences.
 
 .. figure:: /images/editors_preferences_section_extensions.png
 
@@ -17,56 +18,37 @@ The *Extensions* section lets you manage the extensions preferences.
 
    To learn about extensions and how to create them, refer to the :ref:`Extensions <extensions-index>` page.
 
-Install
-=======
+
+.. _prefs-extensions-install:
+
+Installing Extensions
+=====================
 
 There are different ways to install an extension:
 
-- **Install from the Website**: Drag the installation URL into Blender.
-- **Install from Blender**: Search for the extension name and click on Install.
-- **Install from Disk**: Use the dropdown menu in the top right,
-  or drag-and-drop an extension ``.zip`` package into Blender.
+Install from the Website
+   Drag the installation URL into Blender.
+Install from Blender
+   Search for the extension name and click on Install.
+:ref:`Install from Disk <bpy.ops.extensions.package_install_files>`
+   Use the drop-down menu in the top right,
+   or drag-and-drop an extension ``.zip`` package into Blender.
 
-Any installed extension can be removed. This is a permanent change, though.
-To stop an extension temporarily, it is better to Disable it instead.
+.. note::
+
+   Any installed extension can be removed. This is a permanent change, though.
+   To stop an extension temporarily, it is better to Disable it instead.
 
 
-Install Legacy Add-on
----------------------
-
-To install legacy addons, click the *Install from Disk* menu item and select the addon's
-``.py`` file (if it has only one such file) or its ``.zip`` file.
-
-The add-on will not be automatically enabled after installation; click the checkbox to do that.
-
-Refresh
-   Scans the :doc:`Add-on Directory </advanced/blender_directory_layout>` for new add-ons.
-
-.. tip::
-
-   While this screen doesn't allow installing a folder-based addon with loose ``.py`` files,
-   you can still do so by adding it as a :ref:`Script Directory <bpy.types.ScriptDirectory>`:
-
-   #. Create an empty directory in a location of your choice (e.g. ``my_scripts``).
-   #. Add a subdirectory under ``my_scripts`` called ``addons``
-      (it *must* have this name for Blender to recognize it).
-   #. Place your addon folder inside this ``addons`` folder.
-   #. Open the *File Paths* section of the *Preferences*.
-   #. Add a *Script Directories* entry pointing to your script folder (e.g. ``my_scripts``).
-   #. Save the preferences and restart Blender for it to recognize the new add-on location.
-
-   The addons in this folder will automatically become available; all you need to
-   do is enable them.
-
-
-Update
-======
+Updating Extensions
+===================
 
 You need to manually check for available updates.
 Once an update is found, Blender will let you update any of the available extensions.
 
 The current available version of an extension on the repository will always be considered the latest version.
 
+
 Enable/Disable
 ==============
 
@@ -76,74 +58,106 @@ Some extension types do not support this, and will always be shown as enabled.
 .. tip::
 
    If the Add-on does not activate when enabled,
-   check the :doc:`Console window </advanced/command_line/introduction>`
+   check the :doc:`Console window </advanced/command_line/index>`
    for any errors that may have occurred.
 
 
-Settings
-========
+Extension Settings
+==================
 
-- **Check for Updates**: Manually check the online repositories for available updates.
-- **Update All**: Update all the extensions that have an update available.
-- **Install from Disk**: Install an extension from a ``.zip`` package.
-  This is installed to a Local Repository and no updates will be available.
-- **Install Legacy Add-on**: Add-ons are effectively replaced by extensions.
-  However to keep old add-ons working for now, they can still be installed independently of the new system.
+Visit Extensions Platform
+   Opens `extensions.blender.org <https://extensions.blender.org/>` in a web browser.
+
+.. _bpy.ops.extensions.repo_sync_all:
+
+Refresh Remote
+   Manually check the online repositories for available updates.
+
+.. _bpy.ops.extensions.repo_refresh_all:
+
+Refresh Local
+   Scan extension & legacy add-ons for changes to modules & meta-data
+   (similar to restarting). Any issues are reported as warnings
+
+.. _bpy.ops.extensions.package_upgrade_all:
+
+Install Available Updates
+   Update all the extensions that have an update available.
+
+.. _bpy.ops.extensions.package_install_files:
+
+Install from Disk
+   Install an extension from a ``.zip`` package.
+   This is installed to a Local Repository and no updates will be available.
+
+   This can also be used to install legacy Add-ons, for more information see:
+   :ref:`prefs-extensions-install_legacy_addon`.
 
 
-.. _bpy.types.AddonPreferences:
-
-Add-on Preferences
-------------------
-
-Some add-ons may have their own preferences which can be found
-in the *Preferences* section of the add-on information box.
-
-Some add-ons use this section for example to enable/disable
-certain functions of the add-on. Sometimes these might even all default to off.
-So it is important to check if the enabled add-on has any particular preferences.
-
-
-Filter
-======
-
-The available filtering options are:
-
-- Enabled Extensions
-- Installed Extensions
-- Legacy Add-ons
+.. _bpy.types.WindowManager.extension_type:
 
 Filter by Type
 ==============
 
-- **All**: Show all the extension types combined.
-
 Or show only extensions of a single type:
 
-- **Add-ons**
-- **Themes**
+:Add-ons: Only show add-ons.
+:Themes: Only show themes.
+
 
 Repositories
 ============
 
-By default Blender has a Local Repository and a Remote Repository pointing towards the
-`Official Blender Extensions Platform <https://extensions.blender.org>`__.
+By default Blender has a Remote Repository pointing towards the
+`Official Blender Extensions Platform <https://extensions.blender.org>`__ and two Local Repositories.
 
 In the cases where more repositories are needed (e.g., to access third party extension platforms),
 new repositories can be added.
 
 .. figure:: /images/editor_preferences_section_extensions_repositories.png
+   :width: 450px
 
    Repositories.
 
 To add new repositories click on the :menuselection:`+` icon:
 
-- **Add Remote Repository**: Add a repository from a URL.
-- **Add Local Repository**: Add a repository which will be managed by the user (to be used with Install from Disk).
+Add Remote Repository
+   Add a repository from a URL.
+Add Local Repository
+   Add a repository which will be managed by the user (to be used with Install from Disk).
 
 To remove repositories click on the :menuselection:`-` icon:
 
-- **Remove Repository**: Remove an extension repository.
-- **Remove Repository & Files**: Remove a repository and delete all associated files when removing.
+Remove Repository
+   Remove an extension repository.
+Remove Repository & Files
+   Remove a repository and delete all associated files when removing.
 
 These changes are permanent and cannot be reversed.
+
+
+Remote Repository
+-----------------
+
+Remote repository with support for listing and updating extensions.
+
+Options:
+
+Check for Updates on Startup
+   Allows Blender to check for updates upon launch.
+   When updates are available a notification will be visible on the status bar.
+Access Token
+   Personal access token, may be required by some repositories.
+
+
+Local Repository
+----------------
+
+A repository managed manually by the users.
+
+There are two types of local repositories. By default new local repositories are added as User repositories.
+This is what you want most of the time.
+
+After creating a repository they can be changed in the Advanced options to have a source System.
+These repositories are intended to :ref:`bundle extensions <deploying-blender-bundling>`
+with Blender, to make it portable.

manual/editors/preferences/index.rst

@@ -8,15 +8,18 @@
 ###############
 
 .. toctree::
-   :maxdepth: 1
+   :maxdepth: 2
 
    introduction.rst
 
+
+Sections
+========
+
 .. toctree::
    :maxdepth: 1
 
    interface.rst
-   themes.rst
    viewport.rst
    lights.rst
    editing.rst
@@ -27,6 +30,12 @@
 
    extensions.rst
 
+.. toctree::
+   :maxdepth: 1
+
+   addons.rst
+   themes.rst
+
 .. toctree::
    :maxdepth: 1
 

manual/editors/preferences/input.rst

@@ -144,6 +144,17 @@ Multi-touch Gestures
    For more detail on supported gestures,
    see :doc:`Configuring Peripherals </getting_started/configuration/hardware>`.
 
+.. _bpy.types.PreferencesInput.touchpad_scroll_direction:
+
+Scroll Direction
+   The direction scrolling responds to the scroll gestures.
+
+   Only available on Linux using Wayland.
+
+   :Traditional: Scrolls content down when gestures move up.
+   :Natural: Scrolls content up when gestures move up.
+
+
 Tablet
 ======
 

manual/editors/preferences/interface.rst

@@ -145,6 +145,42 @@ File Browser
    :New Window: A new File Browser editor is opened as a regularly sized temporary window.
 
 
+.. _prefs-interface-status_bar:
+
+Status Bar
+----------
+
+Preferences that affect the :doc:`/interface/window_system/status_bar`.
+
+.. _bpy.types.PreferencesView.show_statusbar:
+
+.. rubric:: Show
+
+Scene Statistics
+   Shows information about the data in the active scene.
+
+   - **Collection**: The name of the active :doc:`Collection </scene_layout/collections/index>`.
+   - **Active Object**: The name of the active selected object.
+   - **Geometry**: Information about the current scene depending on the mode and object type.
+     This can be the number of vertices, faces, triangles, or bones.
+   - **Objects**: The number of selected objects and the total count of objects.
+
+Scene Duration
+   Shows the total amount of time of the playback along with the current frame number and total frame count.
+   The format of the duration text is determined by the
+   :ref:`Timecode Style <bpy.types.PreferencesView.timecode_style>`.
+
+System Memory
+   Shows an estimate of Blender's RAM consumption. On a single-instance single-machine scenario,
+   this estimate provides a measurement against the hardware limit of the machine.
+
+Extensions Updates
+   Shows the number of :doc:`extensions </advanced/extensions/index>` with available updates.
+
+Blender Version
+   Shows the version number of Blender that is currently running.
+
+
 .. _prefs-interface-translation:
 
 Language

manual/editors/preferences/keymap.rst

@@ -23,6 +23,14 @@ Preset Management
 Keymap Presets
    Select the keymap from a list of predefined keymaps.
 
+   .. _bpy.ops.wm.keyconfig_preset_add:
+
+   You add a custom keymap configuration to the preset list by :kbd:`LMB` on the *Add* button ``+``.
+
+   .. _bpy.ops.wm.keyconfig_preset_remove:
+
+   You remove a custom keymap configuration from the preset list by :kbd:`LMB` on the *Remove* button ``-``.
+
 .. _bpy.ops.preferences.keyconfig_import:
 
 Import

manual/editors/preferences/system.rst

@@ -71,6 +71,9 @@ Operating System Settings
 
 Make this installation your default Blender (MS-Windows & Linux only).
 
+On Linux, if Blender is installed from a package manager such as Snap,
+file association is handled by the package manager.
+
 Register
    Make the currently in use Blender installation the default
    for generating thumbnails and the default for opening blend-files.
@@ -81,9 +84,8 @@ For All Users
    Register Blender for all users, requires escalated privileges.
 
 
-.. note::
-
-   Linux Registration
+.. admonition:: Linux Registration
+   :class: note
 
    Files are setup files under: ``/usr/local`` for all users, otherwise ``~/.local`` is used.
 
@@ -92,6 +94,27 @@ For All Users
    - The thumbnailer is installed so blend-file thumbnails will be shown in file managers (**For All Users** only).
 
 
+Network
+=======
+
+.. _bpy.types.PreferencesSystem.use_online_access:
+
+Allow Online Access
+   Allow Blender to access the internet.
+
+   Add-ons that follow this setting will only connect to the internet if enabled.
+   However, Blender cannot prevent third-party add-ons from violating this rule.
+
+Time Out
+   The time (in seconds) that online operations may wait before timing out.
+
+   Use the systems default when zero.
+
+Connection Limit
+   The maximum number of simultaneous connections an online operation may make.
+
+   Do not limit the number of connections when zero.
+
 .. _prefs-system-memory-and-limits:
 
 Memory & Limits

manual/editors/preferences/themes.rst

@@ -1,5 +1,3 @@
-.. _bpy.ops.preferences.theme_install:
-.. _bpy.ops.preferences.reset_default_theme:
 .. _bpy.types.Theme:
 
 ******
@@ -15,12 +13,39 @@ change in the multi-choice list at the left, and adjusting colors as required.
 Notice that changes appear in real-time on your screen. In addition, details such as the dot size
 in the *3D Viewport* or the *Graph Editor* can also be changed.
 
-Themes use Blender's preset system to save a theme.
-This will save the theme to an XML file in the ``./scripts/presets/interface_theme/`` subdirectory of one of
-the :doc:`configuration directories </advanced/blender_directory_layout>`.
+Preset Management
+=================
+
+Theme Presets
+   Select the Theme from a list of predefined Themes.
+
+   .. _bpy.ops.wm.interface_theme_preset_add:
+
+   You add a custom theme to the preset list by :kbd:`LMB` on the *Add* button ``+``.
+
+   .. _bpy.ops.wm.interface_theme_preset_remove:
+
+   You remove a custom theme from the preset list by :kbd:`LMB` on the *Remove* button ``-``.
+
+   .. _bpy.ops.wm.interface_theme_preset_save:
+
+   You save a custom theme in the preset list by :kbd:`LMB` on the *Save* button.
+
+   This will save the theme to an XML file in the ``./scripts/presets/interface_theme/`` subdirectory of one of
+   the :doc:`configuration directories </advanced/blender_directory_layout>`.
+
+.. _bpy.ops.preferences.theme_install:
+
+Install
+   Load and apply a Blender XML theme file and add it to the list of theme presets.
+
+.. _bpy.ops.preferences.reset_default_theme:
+
+Reset
+   Reset to the default theme colors.
+
+Blender comes bundled with a small selection of themes.
 
 .. figure:: /images/editors_preferences_themes_example.png
 
-   Blender comes bundled with a small selection of themes.
-
    This is an example of the theme *Blender Light*.

manual/editors/preferences/viewport.rst

@@ -56,7 +56,7 @@ HDRI Preview Size
    :Interactive Navigation:
       Display the axis as an interactive gizmo.
       Click sets the viewport to display along this axis and dragging orbits the view.
-   :Simple Axis:
+   :Simple Axes:
       Display simple, less intrusive axis in the viewport.
 
       .. _bpy.types.PreferencesView.mini_axis_brightness:
@@ -93,7 +93,7 @@ Viewport Anti-Aliasing
 Smooth Wires
    Overlay
       Display overlays with smooth wire, without this wires will be rendered aliased.
-      To increase the visibility you can disable this and *Edit Mode*,
+      To increase the visibility you can disable this for Edit Mode specificity (see below),
       since edges do not blend into other shaded regions.
 
    .. _bpy.types.PreferencesSystem.use_edit_mode_smooth_wire:

manual/editors/properties_editor.rst

@@ -19,6 +19,7 @@ Tabs
 The Properties editor has several categories, which can be chosen via tabs (the icons column to its left).
 Each tab regroups properties and settings of a data type, and is documented in its own manual sections, linked below.
 
+.. _properties-tool-tab:
 
 Active Tool and Workspace Settings
 ----------------------------------

manual/editors/timeline.rst

@@ -153,7 +153,12 @@ Playback
 Play In
    Which editors to update on each animation frame. If an editor is unchecked,
    it'll only be updated once playback stops (with some exceptions where it'll
-   update on each frame anyway).
+   update on each frame anyway). When starting playback in either the
+   :doc:`Graph Editor </editors/graph_editor/introduction>`,
+   :doc:`Dope Sheet </editors/dope_sheet/introduction>` or the
+   :doc:`NLA Editor</editors/nla/introduction>`,
+   all editors will play back regardless of the settings.
+   This is a feature requested by animators to easily play back all views.
 
 .. _bpy.types.Scene.show_subframe:
 
@@ -281,6 +286,12 @@ Channels
 
 Frame All :kbd:`Home`
    Pans and zooms the view so that all keyframes are visible.
+
+.. _bpy.ops.anim.scene_range_frame:
+
+Frame Scene/Preview Range
+   Reset the horizontal view to the current scene frame range,
+   taking the preview range into account if it is active.
 Go to Current Frame :kbd:`Numpad0`
    Centers the Timeline to the Playhead.
 

manual/editors/uv/introduction.rst

@@ -135,7 +135,7 @@ Show Overlays
    Lets you show/hide all overlays using the toggle button, or specific overlays
    using the drop-down arrow. See :doc:`/editors/uv/overlays`.
 
-Active UV Loop Layer
+Active UV Map Layer
    Select which UV map to use.
 
 Display Channels