Makefile

@@ -27,6 +27,8 @@ Utilities
 ---------
 
 - update               to update the repository to the most recent version.
+- format_py            to auto-format Python scripts.
+
 endef
 # HELP_TEXT (end)
 
@@ -125,6 +127,9 @@ report_po_progress:
 update:
 	@git pull --rebase
 
+format_py:
+	@autopep8 --in-place --recursive .
+
 # ----------------------
 # Help for build targets
 

manual/addons/3d_view/precision_drawing_tools/download.rst

@@ -8,9 +8,10 @@ In this case you need only enable the Add-on in the Add-on Preferences.
 
 However, the latest releases can be found on our GitHub.
 
-Downloads should only be taken the from the official releases page:
+Downloads should only be taken the from the
+`official releases page <https://github.com/Clockmender/Precision-Drawing-Tools/releases>`__.
+
 
-https://github.com/Clockmender/Precision-Drawing-Tools/releases
 
 Patches and Commits, that may add new features and/or bug fixes may be downloaded
 from the Commits to the Master branch, no development code should be used
@@ -55,6 +56,6 @@ again only edit the message section in quotes, not the PDT assignments.
 Issues
 ======
 
-Please report any issues, or feature request, etc. using the Issues section
-of the PDT Repository (https://github.com/Clockmender/Precision-Drawing-Tools/issues),
+Please report any issues, or feature request, etc. using the Issues section of the
+`PDT Repository <https://github.com/Clockmender/Precision-Drawing-Tools/issues>`__,
 that way they can be properly tracked, actioned and incorporated into the add-on.

manual/addons/import_export/mesh_atomic.rst

@@ -42,14 +42,15 @@ See `Examples`_ at the end of this page.
    - A list of software that deals with PDB in different ways can be found on
      the `RCSB site <https://www.rcsb.org/docs/additional-resources/molecular-graphics-software>`__. There also is
      `Vesta <https://jp-minerals.org/vesta/en/>`__, `ASE <https://wiki.fysik.dtu.dk/ase/>`__ and all the
-     `quantum chemical calculators <https://en.wikipedia.org/wiki/List_of_quantum_chemistry_and_solid-state_physics_
-     software>`__ used in research, which can create or even calculate atomic structures and store them in PDB/XYZ
-     files.
+     `quantum chemical calculators
+     <https://en.wikipedia.org/wiki/List_of_quantum_chemistry_and_solid-state_physics_software>`__
+     used in research, which can create or even calculate atomic structures and store them in PDB/XYZ files.
 
 .. seealso:: **Forum**
 
-   - Please, use the `Blender Artists forum <https://blenderartists.org/t/atomic-blender-pdb-xyz-for-blender-2-8-and-
-     higher/1197801>`__ for comments and questions or directly the `Blender chat <https://blender.chat/home>`__.
+   - Please, use the `Blender Artists forum
+     <https://blenderartists.org/t/atomic-blender-pdb-xyz-for-blender-2-8-and-higher/1197801>`__
+     for comments and questions or directly the `Blender chat <https://blender.chat/home>`__.
    - There also is the possibility to ask questions on `Stack Exchange <https://blender.stackexchange.com/>`__.
      However, note that some of the developers like Blendphys don't have enough credits, which are, however, needed to
      have the permission for giving answers on Stack Exchange.

manual/addons/import_export/scene_3ds.rst

@@ -7,7 +7,7 @@ Autodesk 3DS
 
    :Category: Import-Export
    :Menu: :menuselection:`File --> Import/Export --> 3D Studio (.3ds)`
-   :Version: 2.3.4
+   :Version: 2.4.1
    :Blender: 3.6
    :Authors: Bob Holcomb, Campbell Barton, Sebastian Schrand
    :Maintainer: Sebastian Sille (NRGSille)
@@ -36,7 +36,7 @@ Image Search
    This enables a recursive file search if an image file can't be found.
 
 Read Keyframe
-   Reads the keyframe tracks from a 3ds file and transforms the objects to the data wich was found.
+   Reads the keyframe tracks from a 3ds file and transforms the objects to the data which was found.
    Usually only one frame is found in static scenes, it will be imported to the timeline.
    If the 3ds scene is animated, the complete animation will be imported to the timeline.
 
@@ -60,7 +60,7 @@ Apply Transform
 
 World Space
    Use world matrix instead of local matrix to transform the objects.
-   This is useful for older 3ds files from 3D Studio DOS wich only used world space to transform the objects.
+   This is useful for older 3ds files from 3D Studio DOS which only used world space to transform the objects.
    It is also useful if the object was exported without apply transform.
 
 
@@ -73,6 +73,10 @@ Include
 Selection Only
    When checked, only selected objects are exported. Otherwise export all objects in the scene.
 
+Write Keyframe
+   Writes the keyframe section of a 3ds file and exports the animation if an action was found.
+   The animation can be imported the same way, un-check if any importer crashes,
+   not every application can handle the keyframe section.
 
 Transform
 ^^^^^^^^^
@@ -88,11 +92,11 @@ Forward / Up
 Materials
 =========
 
-Materials in 3ds are defined in various color and percent chunks wich can include
+Materials in 3ds are defined in various color and percent chunks which can include
 either integer percent and 24bit color values or float color and percent values,
 both can be read by the importer and will be converted to blender values.
 The exporter uses the integer values, since this is used from 3ds version 3 and above.
-The material definitions wich Blender can use are the following:
+The material definitions which Blender can use are the following:
 
 - 3ds Diffuse Color <-> blender Base Color
 - 3ds Specular Color <-> blender Specular Color
@@ -101,8 +105,8 @@ The material definitions wich Blender can use are the following:
 - 3ds Mat Shin2 <-> blender Specular Intensity
 - 3ds Mat Shin3 <-> blender Metallic
 - 3ds Mat Opacity <-> blender Alpha inverted
-- 3ds Mat Bump PCT <-> blender Normalmap Strength
-- 3ds Self Illum PCT <-> blender Emission Strength
+- 3ds Mat Bump PCT <-> blender Normal-map Strength
+- 3ds Self Illumination PCT <-> blender Emission Strength
 
 
 Textures
@@ -111,8 +115,8 @@ Textures
 Each 3ds material can include different texture mappings,
 which are all imported to Blender material nodes including texture coordinates.
 The 3ds exporter basically takes the images and coordinates,
-wich are directly connected to the Principled BSDF shader,
-if an image is connected to a colormix shader, it will exported as secondary texture.
+which are directly connected to the Principled BSDF shader,
+if an image is connected to a color-mix shader, it will exported as secondary texture.
 Shininess maps to roughness and opacity to the alpha channel,
 they must be color inverted afterwards to match with Blender definition.
 The material mappings are defined as following:
@@ -122,9 +126,9 @@ The material mappings are defined as following:
 - 3ds Shininess Map <-> blender Roughness Texture
 - 3ds Reflection Map <-> blender Metallic Texture
 - 3ds Opacity Map <-> blender Alpha Texture
-- 3ds Self Illum Map <-> blender Emission Texture
+- 3ds Self Illumination Map <-> blender Emission Texture
 - 3ds Bump Map <-> blender Normal Map (tangent space)
-- 3ds Tex2 Map <-> blender Color Texture (connect to mixshader)
+- 3ds Tex2 Map <-> blender Color Texture (connect to mix-shader)
 
 .. figure:: /images/addons_io_3ds_material-nodes.jpg
 
@@ -140,12 +144,12 @@ Meshes
 ======
 
 Meshes are made of triangles only, no quads are supported,
-3ds Studio uses edge visibilty flags to hide and show edges, many 3ds files use them to mark the quads.
+3ds Studio uses edge visibility flags to hide and show edges, many 3ds files use them to mark the quads.
 The Blender 3ds importer and exporter will use those flags to mark edges sharp,
 this can be used to convert the triangles back to quads.
-The importer can read the smoothchunk and shades a face smooth if it belongs to a smoothgroup,
+The importer can read the smooth-chunk and shades a face smooth if it belongs to a smooth-group,
 the exporter creates a smooth chunk if the mesh contains any smooth faces.
-3ds only supports one pair of UV coordinates per vertex. If any vertex has more UVs, it will be dublicated.
+3ds only supports one pair of UV coordinates per vertex. If any vertex has more UVs, it will be duplicated.
 
 
 Ambient
@@ -178,3 +182,4 @@ Keyframes
 The importer can read the keyframes, they will be added to the timeline.
 Most animations will play, but the transformations may not be correct,
 some axes or rotations can be inverted. It depends on how it was exported from other applications.
+The exporter can write the keyframes of the timeline to an animated 3ds file.

manual/addons/import_export/scene_dxf.rst

@@ -6,7 +6,7 @@ AutoCAD DXF
 .. reference::
 
    :Category:  Import-Export
-   :Menu:      :menuselection:`File --> Import/Export --> AutoCAD DXF`
+   :Menu:      :menuselection:`File --> Import/Export --> AutoCAD DXF (.dxf)`
 
 
 .. _dxf-import:

manual/addons/interface/amaranth.rst

@@ -330,7 +330,7 @@ Timeline Extra Info
 
 Display amount of frames left until Frame End, very handy especially when rendering an animation or OpenGL preview.
 
-Display current/end time in `SMPTE <https://en.wikipedia.org/wiki/SMPTE_timecode>`_.
+Display current/end time in `SMPTE <https://en.wikipedia.org/wiki/SMPTE_timecode>`__.
 
 Usage: Find it in the Timeline Editor's header.
 
@@ -381,7 +381,7 @@ Sequencer: Display Image File Name
 When seeking through an image sequence, display the active strips'
 file name for the current frame, and its playhead (in square brackets).
 
-Usage: Find it in the VSE header.
+Usage: Find it in the sequencer header.
 
 
 EXR Render: Warn when Z not connected

manual/addons/mesh/tissue.rst

@@ -414,8 +414,8 @@ that generate the various patterns of many living organisms.
 See `this video <https://youtu.be/J-0NzU1TmIY>`__ for an example of the Reaction-Diffusion simulation with Tissue.
 
 
-Radom Materials
----------------
+Random Materials
+----------------
 
 (To Do)
 

manual/addons/object/greasepencil_tools.rst

@@ -76,7 +76,7 @@ Timeline Scrub
 Call a timeline popup at mouse position to scrub without leaving the 3D viewport.
 
 Default shortcut to call the timeline is :kbd:`Alt-MMB`.
-The shortcut enable the scrubbing when hovering timeline editors as well (dopesheet, sequencer, etc).
+The shortcut enable the scrubbing when hovering timeline editors as well (dope-sheet, sequencer, etc).
 
 Scene start/end and keyframes are represented with symbols on the timeline.
 

manual/advanced/command_line/arguments.rst

@@ -65,6 +65,28 @@ Render Options
    [1-1024], 0 for systems processor count.
 
 
+.. _command-line-args-cycles-render-options:
+
+Cycles Render Options
+=====================
+
+Cycles add-on options must be specified following a double dash.
+
+--cycles-device OPTIX
+   Set the device used for rendering. Options: CPU, CUDA, OPTIX, HIP, ONEAPI, METAL.
+
+   Append +CPU to a GPU device to render on both CPU and GPU.
+
+   Example:
+
+   .. code-block:: sh
+
+      blender -b file.blend -f 20 -- --cycles-device OPTIX
+
+--cycles-print-stats
+   Log statistics about render memory and time usage.
+
+
 .. _command-line-args-format-options:
 
 Format Options
@@ -257,6 +279,8 @@ Debug Options
    Enable floating-point exceptions.
 ``--debug-exit-on-error``
    Immediately exit when internal errors are detected.
+``--debug-freestyle``
+   Enable debug messages for Freestyle.
 ``--disable-crash-handler``
    Disable the crash handler.
 ``--disable-abort-handler``
@@ -305,10 +329,14 @@ Misc Options
    Print this help text and exit.
 ``/?``
    Print this help text and exit (Windows only).
-``-R``
-   Register blend-file extension, then exit (Windows only).
-``-r``
-   Silently register blend-file extension, then exit (Windows only).
+``-r``, ``--register``
+   Register blend-file extension for current user, then exit (Windows only).
+``--register-allusers``
+   Register blend-file extension for all users, then exit (Windows only).
+``--unregister``
+   Unregister blend-file extension for current user, then exit (Windows only).
+``--unregister-allusers``
+   Unregister blend-file extension for all users, then exit (Windows only).
 ``-v``, ``--version``
    Print Blender version and exit.
 ``--``
@@ -320,8 +348,6 @@ Misc Options
 Other Options
 =============
 
-``--debug-freestyle``
-   Enable debug messages for Freestyle.
 
 
 .. _command-line-args-argument-parsing:
@@ -381,5 +407,5 @@ Environment Variables
 :BLENDER_SYSTEM_DATAFILES:  Directory for system wide data files.
 :BLENDER_SYSTEM_PYTHON:     Directory for system Python libraries.
 :OCIO:                     Path to override the OpenColorIO config file.
-:TEMP:                     Store temporary files here.
-:TMP: or $TMPDIR           Store temporary files here.
+:TEMP:                     Store temporary files here (MS-Windows).
+:TMP: or $TMPDIR           Store temporary files here (UNIX Systems).

manual/advanced/command_line/render.rst

@@ -14,13 +14,14 @@ and consequently we can render via a remote shell (typically SSH).
 - See :doc:`Command Line Arguments </advanced/command_line/arguments>`
   for a full list of arguments
   (for example to specify which scene to render, the end frame number, etc.), or simply run:
-- See :ref:`Command Line Launching <command_line-launch-index>`
-  for specific instructions on launching Blender from the command line.
 
 .. code-block:: sh
 
    blender --help
 
+- See :ref:`Command Line Launching <command_line-launch-index>`
+  for specific instructions on launching Blender from the command line.
+
 .. note::
 
    Arguments are executed in the order they are given!
@@ -97,21 +98,5 @@ Cycles
 ------
 
 In addition to the options above, which apply to all render engines,
-Cycles has additional options to further control its behavior.
-
-.. code-block:: sh
-
-   blender -b file.blend -f 20 -- --cycles-device CPU
-
-.. note::
-
-   Unlike the generic options, the Cycles-specific ones must be passed on
-   the end of the command line, following a double dash.
-
-``--cycles-device CPU``
-   Override the device that is used to render frames.
-   Currently supported options are ``CPU``, ``CUDA``, ``OPTIX``, ``HIP``, ``ONEAPI``, and ``METAL``.
-   Additionally, you can append ``+CPU`` to any GPU type for hybrid rendering.
-
-``--cycles-print-stats``
-   Show detailed statistics about memory and time usage for Cycles renders on the console.
+Cycles has additional options to further control its behavior. 
+See :ref:`Cycles Render Options <command-line-args-cycles-render-options>`

manual/animation/armatures/posing/editing/pose_library.rst

@@ -228,15 +228,16 @@ Apply Pose Flipped
    be applied for asymmetrical facial expressions that depend on the camera
    angle. While blending (see below), keep :kbd:`Ctrl` pressed to blend the flipped pose.
 
-. _bpy.ops.poselib.blend_pose_asset:
+.. _bpy.ops.poselib.blend_pose_asset:
 
 Blend Pose
    Allows you to gradually blend a pose from the library into the character's pose.
    Click the button, then move the mouse left/right to determine the desired blend.
-   A pose asset can be "subtracted" while blending. Drag to the right to blend as usual, drag to the left to subtract the pose.
-   While blending, you can use :kbd:`Tab` to toggle between the original and the blended pose.
-   As usual in Blender, :kbd:`LMB` or press :kbd:`Enter` to confirm; :kbd:`RMB` or press :kbd:`Esc` to cancel the operator.
-   Blending can also exaggerate a pose, by pressing :kbd:`E` (for Extrapolate) and applying a pose for more than 100%.
+   A pose asset can be "subtracted" while blending. Drag to the right to blend as usual, drag to the left to subtract
+   the pose. While blending, you can use :kbd:`Tab` to toggle between the original and the blended pose.
+   As usual in Blender, :kbd:`LMB` or press :kbd:`Return` to confirm; :kbd:`RMB` or press :kbd:`Esc` to cancel the
+   operator. Blending can also exaggerate a pose, by pressing :kbd:`E` (for Extrapolate) and applying a pose for more
+   than 100%.
 
 .. _bpy.ops.poselib.pose_asset_select_bones:
 

manual/compositing/realtime_compositor.rst

@@ -184,9 +184,9 @@ If an input image to a node is not perfectly aligned with the operation domain o
 different size in pixels, the node would typically need to do a process called Interpolation, where
 the input image is read at the exact positions of the pixels of the operation domain. This can be
 done using different interpolation methods, including Nearest-Neighbor, Bilinear, and Bicubic
-interpolations. Those interpolation methods are demonstrated in the following `Wikipedia gallery
-<https://en.wikipedia.org/wiki/Comparison_gallery_of_image_scaling_algorithms>`_. Transformation
-nodes like the :ref:`Transform <bpy.types.CompositorNodeTransform>` and :ref:`Rotate
+interpolations. Those interpolation methods are demonstrated in the following
+`Wikipedia gallery <https://en.wikipedia.org/wiki/Comparison_gallery_of_image_scaling_algorithms>`__.
+Transformation nodes like the :ref:`Transform <bpy.types.CompositorNodeTransform>` and :ref:`Rotate
 <bpy.types.CompositorNodeRotate>` nodes include an interpolation option to set how they prefer their
 output image to be read and interpolated.
 

manual/compositing/types/output/file.rst

@@ -27,11 +27,6 @@ Image
    The image(s) will be saved on rendering, writing to the current frame.
    An entire sequence of images will be saved, when an animation is rendered.
 
-.. note::
-
-   To support subsequent arrangement and layering of images, the node can supply a Z-depth map.
-   However, please note that only the OpenEXR image formats save the Z information.
-
 
 Properties
 ==========

manual/conf.py

@@ -26,7 +26,7 @@ sys.setrecursionlimit(2000)
 
 # Not used directly by Sphinx, but used by this file and the buildbot.
 
-blender_version = '3.6'
+blender_version = '4.0'
 
 
 # -- Project information -----------------------------------------------------
@@ -237,7 +237,7 @@ 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 = ''
+# epub_language = ''
 
 epub_copyright = 'This manual is licensed under a CC-BY-SA 4.0 Int. License.'
 
@@ -330,17 +330,17 @@ latex_logo = "../resources/theme/blender-logo.svg"
 
 # This value determines the topmost sectioning unit. It should be chosen from
 # 'part', 'chapter' or 'section'.
-#latex_toplevel_sectioning = 'None'
+# latex_toplevel_sectioning = 'None'
 
 # A list of document names to append as an appendix to all manuals.
-#latex_appendices = []
+# latex_appendices = []
 
 # If true, generate domain-specific indices in addition to the general index.
-#latex_domain_indices = True
+# latex_domain_indices = True
 
 # If true, add page references after internal references.
 # This is very useful for printed copies of the manual.
-#latex_show_pagerefs = False
+# latex_show_pagerefs = False
 
 # Control whether to display URL addresses.
 latex_show_urls = "no"
@@ -415,17 +415,17 @@ texinfo_documents = [
 ]
 
 # A list of document names to append as an appendix to all manuals.
-#texinfo_appendices = []
+# texinfo_appendices = []
 
 # If true, generate domain-specific indices in addition to the general index.
-#texinfo_domain_indices = True
+# 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.
-#texinfo_no_detailmenu = False
+# texinfo_no_detailmenu = False
 
 
 # -- Extension configuration -------------------------------------------------

manual/contribute/pull_requests.rst

@@ -73,8 +73,7 @@ Guidelines for Reviewers
   ``WIP:`` prefix in the title, indicating the author considers the pull request not ready to be merged.
   No review is expected unless the author specifically asks for it.
 - Writers are expected to reply to pull requests in 3 working days.
-- Add relevant modules/projects to tags.
-- Assign individuals (instead of modules/projects) for reviewers, to avoid too much noise.
+- Add relevant modules/projects to the labels.
 - Encourage new writes to do review, it's a good way to learn and important to grow the project.
 
 

manual/contribute/translations/add_language.rst

@@ -24,7 +24,7 @@ This will give you a foundation environment for:
 Below examples show the process to create a new set of files for French, language code ``fr``, on Linux platform.
 Other platforms might vary slightly but should be mainly the same.
 
-#. `Create a Blender ID <https://id.blender.org/register/>` if you have not done so already
+#. `Create a Blender ID <https://id.blender.org/register/>`__ if you have not done so already
 #. Log into `projects.blender.org <https://projects.blender.org/>`__ and
    `Create an Issue <https://projects.blender.org/blender/documentation/issues/new>`__
    requesting for commit access in order to transfer changes to the central repository of the translation team.

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

@@ -84,8 +84,13 @@ Annotations
 Objects
 -------
 
-Extra
+Extras
    Show objects that don't have geometry (such as empties, cameras and lights).
+
+.. _bpy.types.View3DOverlay.show_light_colors:
+
+Light Colors
+   Shades the outline of light objects to the color the light produces.
 Relationship Lines
    Show dashed lines indicating parent or constraint relationships.
 Outline Selected
@@ -183,27 +188,31 @@ Seams
 Shading
 -------
 
-Hidden Wire
-   Show only front-facing wireframes.
-   This is useful for a retopology workflow.
+.. _bpy.types.View3DOverlay.show_retopology:
 
-   .. tip::
+Retopology
+   Hide the solid mesh and offset the overlay towards the view.
+   Selection is occluded by inactive geometry, unless X-Ray is enabled
 
-      Optimally this could be combined with the *X-Ray* display setting.
+   .. _bpy.types.View3DOverlay.retopology_offset:
+
+   Offset
+      Amount to offset edit mesh in front of other geometry.
+
+.. _bpy.types.View3DOverlay.show_weight:
 
 Vertex Groups Weights
    Display weights in Edit Mode.
 
+   .. _bpy.types.ToolSettings.vertex_group_user:
+
    Zero Weights
       Display unreferenced and zero-weighted areas in black.
       This helps to identify areas with very low weights that have been painted onto.
 
-      None
-         Vertices are displayed in the usual way.
-      Active
-         Vertices are shown in black if they have no weight in the active vertex group.
-      All
-         Vertices are shown in black if they have no weight in any vertex group.
+      :None: Vertices are displayed in the usual way.
+      :Active: Vertices are shown in black if they have no weight in the active vertex group.
+      :All: Vertices are shown in black if they have no weight in any vertex group.
 
 
 Mesh Analysis

manual/editors/graph_editor/channels/introduction.rst

@@ -54,7 +54,8 @@ Selecting
 ---------
 
 - Select channel (text in white/black): :kbd:`LMB`
-- Multi Select/Deselect: :kbd:`Shift-LMB`
+- Multi Select/Deselect: :kbd:`Ctrl-LMB`
+- Range Select: :kbd:`Shift-LMB`
 - Select All: :kbd:`A`
 - Deselect All: :kbd:`Alt-A`
 - Box Select: (:kbd:`LMB` drag) or :kbd:`B` (:kbd:`LMB` drag)

manual/editors/graph_editor/fcurves/editing.rst

@@ -150,14 +150,14 @@ Copy/Paste
 
 .. admonition:: Reference
 
-   :Menu:      :menuselection:`Key --> Copy Keyframes`, :menuselection:`Key --> Paste Keyframes`
+   :Menu:      :menuselection:`Key --> Copy`, :menuselection:`Key --> Paste`
    :Shortcut:  :kbd:`Ctrl-C`, :kbd:`Ctrl-V`
 
 Use :kbd:`Ctrl-C` to copy selected keyframes and :kbd:`Ctrl-V` to paste the previously copied keyframes.
 During the paste action, the :ref:`bpy.ops.screen.redo_last` panel provides some options in
 how the paste is applied.
 
-Offset
+Frame Offset
    :No Offset:
       Pastes the keyframes in the location they were copied from.
    :Frame Relative:
@@ -167,6 +167,19 @@ Offset
       Pastes the keyframes with the first keyframe of the copied set placed at the current frame.
    :Frame End:
       Pastes the keyframes with the last keyframe of the copied set placed at the current frame.
+
+Value Offset
+   :No Offset:
+      Pastes the keyframes with the value they were copied from.
+   :Cursor Value:
+      Paste the keyframes at the 2D cursor as a starting point.
+   :Current Frame Value:
+      Paste keyframes relative to the value of the curve under the cursor.
+   :Right Key:
+      Paste keyframes such that the last frame matches the key value right of the cursor.
+   :Left Key:
+      Paste keyframes such that the first key matches the key value left of the cursor.
+
 Type
    :Mix:
       Integrates the pasted keyframes in with existing keyframes only overwriting keyframes that share a frame.
@@ -442,3 +455,31 @@ seem to be never modified by this tool.
      - .. figure:: /images/editors_graph-editor_fcurves_editing_smooth.png
 
           F-Curve after smoothing.
+
+
+.. _bpy.ops.graph.gaussian_smooth:
+
+Smooth (Gaussian)
+-----------------
+
+.. reference::
+
+   :Menu:      :menuselection:`Key --> Smooth --> Smooth (Gaussian)`
+
+Smooths the selected keyframes using a Gaussian kernel. It can handle gaps in the keyframe data.
+The operator is modal with a blend factor, making it possible to tweak the strength of the filter.
+
+Factor
+   A blend factor from original to filtered curve.
+
+Sigma
+   The shape of the gaussian distribution. Lower values mean a sharper curve, giving keys that are close to each
+   other more weight. A high value behaves like a simple average filter.
+
+Filter Width
+   A wider filter looks at more keyframes, producing a smoother result.
+   At a size of 1 the filter only looks at the keyframes to the immediate left and right for a weighted average.
+
+.. figure:: /images/editors_graph-editor_gaussian_smooth.jpg
+
+   F-Curve after applying the Gaussian Smooth with the original curve overlayed.

manual/editors/graph_editor/fcurves/properties.rst

@@ -163,8 +163,9 @@ Interpolation
 
    .. seealso::
 
-      For more info and a few live demos, see https://easings.net and
-      http://robertpenner.com/easing/
+      For more info and a few live demos,
+      see `easings.net <https://easings.net>`__ and
+      `Robert Penner's Easing Functions <http://robertpenner.com/easing>`__.
 
 
    .. rubric:: Dynamic Effects

manual/editors/outliner/interface.rst

@@ -34,10 +34,10 @@ Data API
 Library Overrides
    Display library override data in the current blend-file. Separated further into two view modes:
 
-   Properties:
+   :Properties:
       Display data-blocks with overridden properties. The overridden properties are listed together with widgets to
       modify the value of the properties.
-   Hierarchies:
+   :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
@@ -137,19 +137,19 @@ Object State
    List the objects based on their state or restrictions.
    The results can be inverted using the *Invert* button.
 
-   All
+   :All:
       The default option, no restrictions.
-   Visible
+   :Visible:
       List only the objects visible in the viewports.
       The global and temporary visibility settings are taken into consideration.
-   Invisible
+   :Invisible:
       List only the objects not visible in the viewports.
-   Selected
+   :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.
-   Active
+   :Active:
       Lists only the active (often last selected) object.
-   Selectable
+   :Selectable:
       List all objects whose :ref:`Selectability <bpy.types.Collection.hide_select>` option is enabled.
 
 .. _bpy.types.SpaceOutliner.use_filter_object_content:
@@ -167,6 +167,7 @@ Object Children
 .. _bpy.types.SpaceOutliner.use_filter_object_mesh:
 .. _bpy.types.SpaceOutliner.use_filter_object_light:
 .. _bpy.types.SpaceOutliner.use_filter_object_camera:
+.. _bpy.types.SpaceOutliner.use_filter_object_grease_pencil:
 .. _bpy.types.SpaceOutliner.use_filter_object_empty:
 .. _bpy.types.SpaceOutliner.use_filter_object_others:
 

manual/editors/video_sequencer/preview/introduction.rst

@@ -23,7 +23,7 @@ The gizmos however are unique for the Preview.
 .. figure:: /images/editors_vse_type.svg
    :alt: Preview window
 
-   Figure 1: Preview window of VSE.
+   Figure 1: Preview window of Video Sequencer.
 
 Sequencer preview is used to display result of rendering Sequencer timeline.
 This can be further configured to display output from certain channel, overlay or image analyzer (scope).

manual/files/import_export/usd.rst

@@ -89,6 +89,9 @@ Materials
    See `USD issue #542 <https://github.com/PixarAnimationStudios/USD/issues/542>`__
    for more information.
 
+Root Prim
+   If set, add a transform primitive with the given path to the stage as the parent of all exported data.
+
 Use Settings for
    Determines the whether to use *Viewport* or *Render* visibility of collection, modifiers,
    or any other property that can be set for both the *Viewport* and *Render*.

manual/grease_pencil/modes/weight_paint/index.rst

@@ -8,5 +8,5 @@
 
    introduction.rst
    tools.rst
-   tool_settings/brush.rst
+   tool_settings/index.rst
    weights_menu.rst

manual/grease_pencil/modes/weight_paint/tool_settings/brush.rst

@@ -1,8 +1,8 @@
 .. _tool-grease-pencil-weight-paint-weight:
 
-*****
-Brush
-*****
+**************
+Brush Settings
+**************
 
 Painting needs paint brushes and Blender provides a Brush panel within the Toolbar
 when in *Weight Paint Mode*.
@@ -11,12 +11,17 @@ Brush
    In the :ref:`Data-Block menu <ui-data-block>` you find predefined Brush presets.
    And you can create your own custom presets as needed.
 
-Radius
+Radius :kbd:`F`
    The radius defines the area of influence of the brush.
 Strength
    This is the amount of paint to be applied per brush stroke.
 Use Falloff
    When enabled, use Strength falloff for the brush.
    Brush Strength decays with the distance from the center of the brush.
-Weight
+Weight :kbd:`Ctrl-F`
    The weight (visualized as a color) to be used by the brush.
+
+   Using :kbd:`Ctrl-RMB` you can set the weight to the value thats under the cursor.
+Direction :kbd:`D`
+   Brush direction toggle, *Add* adds weight value while *Subtract* removes weight value.
+   This setting can be toggled with :kbd:`D`.

manual/grease_pencil/modes/weight_paint/tool_settings/index.rst

@@ -0,0 +1,10 @@
+
+#################
+  Tool Settings
+#################
+
+.. toctree::
+   :maxdepth: 2
+
+   brush.rst
+   options.rst

manual/grease_pencil/modes/weight_paint/tool_settings/options.rst

@@ -0,0 +1,16 @@
+
+*******
+Options
+*******
+
+Auto Normalize
+   Ensures that all deforming vertex groups add up to one while painting.
+   When this option is turned off, then all weights of a point can have any value between 0 and 1.
+   However, when vertex groups are used as deform groups for character animation
+   then Blender always interprets the weight values relative to each other.
+   That is, Blender always does a normalization over all deform bones.
+   Hence in practice it is not necessary to maintain a strict normalization and
+   further normalizing weights should not affect animation at all.
+
+   This option works most intuitively when used to maintain normalization while
+   painting on top of weights that are already normalized with another tool.

manual/grease_pencil/modes/weight_paint/tools.rst

@@ -14,6 +14,17 @@ See :doc:`Brush </grease_pencil/modes/weight_paint/tool_settings/brush>` for mor
 Draw
    Paints a specified weight over the strokes.
 
+Blur
+   Smooths out the weighting of adjacent points. In this mode the Weight
+   Value is ignored. The strength defines how much the smoothing is applied.
+
+Average
+   Smooths weights by painting the average resulting weight from all weights under the brush.
+
+Smear
+   Smudges weights by grabbing the weights under the brush and "dragging" them.
+   This can be imagined as a finger painting tool.
+
 :ref:`Annotate <tool-annotate-freehand>`
    Draw free-hand annotation.
 

manual/modeling/geometry_nodes/hair/deformation/smooth_hair_curves.rst

@@ -4,7 +4,7 @@
 Smooth Hair Curves
 ******************
 
-Smoothes the shape of  hair curves.
+Smooths the shape of  hair curves.
 
 .. peertube:: 7fpUB2eRT6zjMyHRzJ2ZoJ
 

manual/modeling/meshes/editing/uv.rst

@@ -193,10 +193,8 @@ Follow Active Quads
    :Menu:      :menuselection:`UV --> Follow Active Quads`
    :Shortcut:  :kbd:`U`
 
-The Follow Active Quads tool takes the selected faces and lays them out
-by following continuous face loops, even if the mesh face is irregularly-shaped.
-Note that it does not respect the image size,
-so you may have to scale them all down a bit to fit the image area.
+Extrapolate UV's based on the active quad by following continuous face loops,
+even if the mesh face is irregularly-shaped.
 
 
 Options
@@ -205,16 +203,27 @@ Options
 Edge Length Mode
    Method to space UV edge loops.
 
-   :Even: Space all UVs evenly.
-   :Length: Todo.
-   :Length Average: Average space UVs edge length of each loop.
+   :Even:
+      Space all UVs evenly, where the shape of the quad in the 3D viewport is ignored.
+   :Length:
+      Each face's UV's are calculated based on the edge length.
+
+      While this minimizes distortion, adjacent loops may become disconnected.
+   :Length Average:
+      Average space UVs edge length of each loop.
+
+      This has the benefit of minimizing distortion, while keeping UV's connected.
 
 .. note::
 
-   Please note that it is the shape of the active quad in UV space that is being followed,
-   not its shape in 3D space. To get a clean 90-degree unwrap make sure the active quad is
-   a rectangle in UV space before using "Follow active quad".
+   For a clean 90-degree unwrap it's typically best to first make sure the quad a rectangle in UV space.
 
+   Otherwise any distortion in the active UV is extended which doesn't result in a useful grid-layout.
+
+.. note::
+
+   The resulting unwrap is not clamped within the UV bounds,
+   you may wish to scale down the active quad's UV's so the result is in a usable range.
 
 .. _bpy.ops.uv.cube_project:
 

manual/modeling/modifiers/physics/explode.rst

@@ -15,9 +15,12 @@ That particle system will control how the mesh is exploded.
 Both the number of emitted particles and number of faces determine how granular the *Explode* modifier is.
 More of each faces and particles will mean more individual pieces.
 
-Here is a `demo video <https://archive.blender.org/wiki/index.php/File:Manual_-_Explode_Modifier_-_Exploding_Cube_-_
-2.5.ogg/>`__ showing a cube with a particle system and *Explode* modifier. (`blend-file <https://archive.blender.org/
-wiki/index.php/File:Manual_-_Explode_Modifier_-_Exploding_Cube_-_2.5.blend>`__).
+Here is a
+`demo video <https://archive.blender.org/wiki/index.php/File:Manual_-_Explode_Modifier_-_Exploding_Cube_
+-_2.5.ogg/>`__
+showing a cube with a particle system and *Explode* modifier.
+(`blend-file <https://archive.blender.org/wiki/index.php/File:Manual_-_Explode_Modifier_-_Exploding_Cube_
+-_2.5.blend>`__).
 
 .. note::
 

manual/modeling/texts/properties.rst

@@ -15,6 +15,8 @@ Most of the settings in the *Shape* panel are shared with those of
 :doc:`Curves </modeling/curves/properties/shape>`
 data-blocks, please refer to those for details.
 
+.. _bpy.types.TextCurve.use_fast_edit:
+
 Fast Editing
    Does not fill the letters in Edit Mode, only show their outline.
 
@@ -101,18 +103,39 @@ but you have to choose between different styles of a same font, or different fon
 Blender has a number of typographic controls for changing the style and layout of text,
 found in the *Font* panel.
 
+.. _bpy.types.TextCharacterFormat.use_bold:
+
 Bold
-   Toggled with the *Bold* button before typing. Text can also be set to
-   **bold** by selecting it then using the *Bold* entry in the *Text* menu of
-   the 3D Viewport.
-Italics
-   Toggled with the *Italic* button before typing. Text can also be set to
-   *italic* by selecting it then using the *Italic* entry in the *Text* menu of
-   the 3D Viewport.
+   With no text selected, toggles new text to be **bold**.
+   With text selected, toggles the selected text to be **bold**.
+   Text can also be set to bold by selecting it then using the *Bold*
+   entry in the *Text* menu of the 3D Viewport.
+
+.. _bpy.types.TextCharacterFormat.use_italic:
+
+Italic
+   With no text selected, toggles new text to be *italic*.
+   With text selected, toggles the selected text to be *italic*.
+   Text can also be set to italic by selecting it then using the *Bold*
+   entry in the *Text* menu of the 3D Viewport.
+
+.. _bpy.types.TextCharacterFormat.use_underline:
+
 Underline
-   Enables underlining, as controlled by the :ref:`underline settings <modeling-text-character-underline>` below.
+   With no text selected, toggles new text to be underline.
+   With text selected, toggles the selected text to be underline.
+   Text can also be set to underline by selecting it then using the *Underline*
+   entry in the *Text* menu of the 3D Viewport.
+
+   See also :ref:`underline settings <modeling-text-character-underline>` below.
+
+.. _bpy.types.TextCharacterFormat.use_small_caps:
+
 Small Caps
-   Enable this option to type characters as small caps.
+   With no text selected, toggles new text to be small capitals.
+   With text selected, toggles the selected text to be small capitals.
+   Text can also be set to small caps by selecting it then using the *Small Caps*
+   entry in the *Text* menu of the 3D Viewport.
 
    The size of the *Small Caps* can be changed with
    the :ref:`Small Caps Scale setting <modeling-text-character-underline>`.
@@ -121,9 +144,14 @@ Small Caps
 Transform
 ---------
 
+.. _bpy.types.TextCurve.size:
+
 Size
    Controls the size of the whole text (no way to control each char size independently).
    Note however, that chars with different fonts (different styles, see below) might have different visible sizes.
+
+.. _bpy.types.TextCurve.shear:
+
 Shear
    Controls the inclination of the whole text.
    As similar as it may seem, this is not the same thing as italics style.
@@ -133,6 +161,8 @@ Shear
 
       Shear example.
 
+.. _bpy.types.TextCurve.family:
+
 Object Font
    Allows individual objects to be used to render fonts, you can create/model your own complex font inside Blender!
    This field is used to select the objects prefix name (object "family") to be used
@@ -153,6 +183,8 @@ Object Font
       The objects are duplicated so that their center is positioned at
       the *lower right corner* of the corresponding characters.
 
+.. _bpy.types.TextCurve.follow_curve:
+
 Text on Curve
    Select a curve object for the text object to follow.
 
@@ -167,15 +199,18 @@ Text on Curve
       which offers more control, and is the standard way to achieve such effects in modern Blender.
 
 .. _modeling-text-character-underline:
+.. _bpy.types.TextCurve.underline_position:
 
-Underline
-   Toggled with the *Underline* button before typing.
-   Text can also be set to Underlined by selecting it
-   then using the *Underline* entry in the *Text* menu of the 3D Viewport.
 Underline Position
    This allows you to shift vertically the position of the underline.
+
+.. _py.types.TextCurve.underline_height:
+
 Underline Thickness
    This controls the thickness of the underline.
+
+.. _bpy.types.TextCurve.small_caps_scale:
+
 Small Caps Scale
    The scaling applied to capital letters to turn them into small caps.
 
@@ -198,6 +233,8 @@ The *Paragraph* Panel has settings for the alignment and spacing of text.
 Alignment
 ---------
 
+.. _bpy.types.TextCurve.align_x:
+
 Horizontal
    :Left:
       Aligns text to the left of the frames when using them,
@@ -218,6 +255,8 @@ Horizontal
 
    .. note:: Both *Justify* and *Flush* only work within frames.
 
+.. _bpy.types.TextCurve.align_y:
+
 Vertical
    :Top:
       - With text boxes, aligns the top of the text to the top of the frames.
@@ -247,16 +286,27 @@ Vertical
 Spacing
 -------
 
+.. _bpy.types.TextCurve.space_character:
+
 Character Spacing
    A factor by which space between each character (kerning) is scaled in width.
 
    In Edit Mode in the 3D Viewport, you can also control individual kerning
    at text cursor position by pressing :kbd:`Alt-Left` / :kbd:`Alt-Right` to decrease/increase it.
+
+.. _bpy.types.TextCurve.space_word:
+
 Word Spacing
    A factor by which whitespace between words is scaled in width.
+
+.. _bpy.types.TextCurve.space_line:
+
 Line Spacing
    A factor by which the vertical space between lines is scaled.
 
+.. _bpy.types.TextCurve.offset_x:
+.. _bpy.types.TextCurve.offset_y:
+
 Offset X, Y
    These settings control the X and Y offset of the text position within the object.
    This applies relatively to the object's origin, either to the whole text or, when using text boxes, to each frame.
@@ -284,13 +334,19 @@ If the last frame is reached, text overflows out of it (by default, see options
 
    Text Boxes panel.
 
+.. _bpy.ops.font.textbox_add:
+
 Add Textbox
    Inserts a new frame, just after the current one (in text flow order).
    The new frame will have the same size and position as the selected one.
 
+.._bpy.ops.font.textbox_remove:
+
 Delete ``X``
    Delete the current frame.
 
+.. _bpy.types.TextCurve.overflow:
+
 Overflow
    How to handle text overflowing available space in the defined boxes.
 
@@ -306,10 +362,15 @@ Overflow
          It will only truncate in *Object Mode*,
          in *Edit Mode* the whole text remains visible (and overflows as needed).
 
+.. _bpy.types.TextBox.width:
+
 Size X, Y
    Specifies the width and height of the text box, if set to **zero** no word wrapping happens
    (it is ignored, and the whole text box system is disabled if all are set to a null size).
 
+.. _bpy.types.TextBox.x:
+.. _bpy.types.TextBox.y:
+
 Offset X, Y
    Controls the *X* and *Y* offset of the frame, i.e. its position.
 

manual/modeling/texts/selecting.rst

@@ -15,6 +15,8 @@ it determines where new chars will be inserted.
 
 Select All :kbd:`Ctrl-A`
    Selects the full text.
+Top/Bottom :kbd:`Shift-Ctrl-Home`/ :kbd:`Shift-Ctrl-End`
+   Moves the cursor to the start or end of the text object.
 Next/Previous Character :kbd:`Left`/ :kbd:`Right`
    You can move the cursor with the arrow keys.
 Next/Previous Word :kbd:`Ctrl-Left`/ :kbd:`Ctrl-Right`

manual/physics/soft_body/introduction.rst

@@ -49,8 +49,8 @@ Soft bodies are well suited for:
 
 The following videos may give you some more ideas:
 
-- https://www.youtube.com/watch?v=hLnY-OFUBzM
-- https://www.youtube.com/watch?v=qdusMZlBbQ4
+- `New Penguoen <https://www.youtube.com/watch?v=hLnY-OFUBzM>`__.
+- `Blender Softbody Simulations <https://www.youtube.com/watch?v=qdusMZlBbQ4>`__.
 
 
 Creating a Soft Body

manual/render/cycles/gpu_rendering.rst

@@ -246,8 +246,7 @@ but the only real solution is to use separate graphics cards for display and ren
 
 Another solution can be to increase the time-out,
 although this will make the user interface less responsive when rendering heavy scenes.
-`Learn More Here <https://learn.microsoft.com/en-us/windows-hardware/drivers/display/timeout-detection-and-
-recovery>`__.
+`Learn More Here <https://learn.microsoft.com/en-us/windows-hardware/drivers/display/timeout-detection-and-recovery>`__.
 
 
 CUDA error: Unknown error in cuCtxSynchronize()

manual/render/cycles/world_settings.rst

@@ -53,8 +53,8 @@ Falloff
 
 .. figure:: /images/render_cycles_world-settings_mist-example1-BI.jpg
 
-   Mist example (`blend-file <https://archive.blender.org/wiki/index.php/File:25-Manual-World-Mist-
-   Example1.blend>`__).
+   Mist example
+   (`blend-file <https://archive.blender.org/wiki/index.php/File:25-Manual-World-Mist-Example1.blend>`__).
 
 
 .. _bpy.types.CyclesVisibilitySettings.camera:

manual/sculpt_paint/brush/texture.rst

@@ -135,7 +135,7 @@ Size X, Y, Z
 
 Sample Bias :guilabel:`Sculpt Mode`
    Value added to texture samples.
-   This can be used if the midlevel of a height map is not correct.
+   This can be used if the mid-level of a height map is not correct.
 
 .. _bpy.types.Brush.use_color_as_displacement:
 

manual/sculpt_paint/sculpting/editing/expand.rst

@@ -12,7 +12,7 @@ When executed, it uniformly expand outwards a pattern from the vertex under the
 
    These operators are meant to be used interactively through the shortcut.
 
-There is also a `full showcase of the Expand features and use cases <https://www.youtube.com/watch?v=XT7h6lmE5bc>`_.
+There is also a `full showcase of the Expand features and use cases <https://www.youtube.com/watch?v=XT7h6lmE5bc>`__.
 
 .. figure:: /images/sculpt-paint_sculpting_expand_example.png
 

manual/sculpt_paint/sculpting/introduction/cloth_sculpting.rst

@@ -27,4 +27,4 @@ but other transform brushes like :doc:`Pose </sculpt_paint/sculpting/tools/pose>
 :doc:`Boundary </sculpt_paint/sculpting/tools/boundary>` also support cloth sculpting in the brush settings.
 
 A demo file for trying out the various brushes and tools is available
-`here <https://www.blender.org/download/demo-files/#sculpting>`_.
+`here <https://www.blender.org/download/demo-files/#sculpting>`__.

manual/sculpt_paint/sculpting/tools/draw.rst

@@ -34,10 +34,10 @@ to displace geometry in three directions instead of just one.
 .. figure:: /images/sculpt-paint_sculpt_vdm_example.png
    :width: 580px
 
-   An example of various VDM brushes used on a smooth head from the offical demo file.
+   An example of various VDM brushes used on a smooth head from the official demo file.
 
-`Download the demo file <https://www.blender.org/download/demo-files/#sculpting>`_ for more information and to try
-the feature out.
+`Download the demo file <https://www.blender.org/download/demo-files/#sculpting>`__
+for more information and to try the feature out.
 
 To use this feature, enable :ref:`Vector Displacement <bpy.types.Brush.use_color_as_displacement>` in the texture
 panel. All :ref:`stroke methods <bpy.types.Brush.stroke_method>` are supported, but the recommended behavior is

manual/video_editing/edit/montage/editing.rst

@@ -28,7 +28,7 @@ Expand
 Snapping
 ^^^^^^^^
 
-It is possible to enable snapping in the header of the VSE.
+It is possible to enable snapping in the header of the Video Sequencer.
 The snapping behavior can be configured as follows:
 
 .. _bpy.types.SequencerToolSettings.snap_to_current_frame:

pyproject.toml

@@ -0,0 +1,41 @@
+# SPDX-License-Identifier: GPL-2.0-or-later
+
+[tool.autopep8]
+# Configuration for `autopep8`, allowing the command: autopep8 .
+# to reformat all source files.
+#
+# NOTE: the settings defined here map directly to command line arguments
+# which will override these settings when passed in to autopep8.
+
+max_line_length = 120
+
+ignore = [
+    # Info: Use `isinstance()` instead of comparing types directly.
+    # Why disable? Changes code logic, in rare cases we want to compare exact types.
+    "E721",
+    # Info: Fix bare except.
+    # Why disable? Disruptive, leave our exceptions alone.
+    "E722",
+    # Info: Fix module level import not at top of file.
+    # Why disable? Re-ordering imports is disruptive and breaks some scripts
+    # that need to check if a module has already been loaded in the case of reloading.
+    "E402",
+    # Info: Fix various deprecated code (via lib2to3)
+    # Why disable? Does nothing besides incorrectly adding a duplicate import,
+    # could be reported as a bug except this is likely to be removed soon, see:
+    # https://github.com/python/cpython/issues/84540.
+    "W690",
+]
+
+# Use aggressive as many useful edits are disabled unless it's enabled.
+# Any edits which are overly disruptive or risky can be removed in the `ignore` list.
+aggressive = 2
+
+# Exclude:
+# - `./tools/svn_rev_map` because it's a large data-file.
+exclude = """
+./tools/svn_rev_map/sha1_to_rev.py,
+"""
+
+# Omit settings such as `jobs`, `in_place` & `recursive` as they can cause editor utilities that auto-format on save
+# to fail if the STDIN/STDOUT is used for formatting (which isn't compatible with these options).

tools_maintenance/blender_help_extract.py

@@ -33,6 +33,7 @@ def text_remove_preprocess(text):
     non_comment_lines = [line for line in lines if not line.strip().startswith("#")]
     return "\n".join(non_comment_lines)
 
+
 def text_join_lines(text):
     lines = text.split("\n")
     lines_out = [[]]
@@ -163,10 +164,10 @@ def text_extract_strings(text):
 
 
 def text_extract_help(text, args, static_strings):
-    func_id = 'static int arg_handle_print_help(int UNUSED(argc), const char **UNUSED(argv), void *data)\n'
+    func_id = 'static void print_help(bArgs *ba, bool all)\n'
     index_start = text.find(func_id)
-    assert(index_start != -1)
-    index_end = text.find("exit(0);", index_start)
+    assert (index_start != -1)
+    index_end = text.find("\n}\n", index_start)
     # print(index_start, index_end)
     body = text[index_start + len(func_id):index_end]
     body = [l for l in body.split("\n") if not l.strip().startswith("#")]
@@ -225,8 +226,8 @@ def text_extract_help(text, args, static_strings):
 
     ind_re = None
     for l in body:
-        if l.startswith("printf"):
-            l = eval(l.replace("printf(", "").replace(");", ""), other_vars)
+        if l.startswith("PRINT"):
+            l = eval(l.replace("PRINT(", "").replace(");", ""), other_vars)
             if type(l) is tuple:
                 # Run the C-style string format.
                 l = l[0] % l[1:]

tools_rst/rst_check_spelling.py

@@ -49,56 +49,91 @@ def check_word(w):
     return dict_spelling.check(w)
 
 
+def regex_key_raise(x):
+    raise Exception("Unknown role! " + "".join(x.groups()))
+
+
+# A table of regex and their replacement functions.
+#
+# This is used to clean up text from `docutils.nodes.NodeVisitor.visit_Text` which doesn't remove inline markup.
+# Note that in some cases the order matters, especially with include/excluding roles.
+
+RE_TEXT_REPLACE_ROLES_INCLUDE = ("menuselection", "guilabel")
+RE_TEXT_REPLACE_ROLES_EXCLUDE = ("kbd", "ref", "doc", "abbr")
+
+RE_TEXT_REPLACE_TABLE = (
+    # Match HTML link: `Text <url>`__
+    # A URL may span multiple lines.
+    (
+        re.compile(r"(`)([^`<]+)(<[^`>]+>)(`)(__)", re.MULTILINE),
+        lambda x: x.groups()[1].strip(),
+    ),
+    # Roles with plain-text: :some_role:`Text <ref>`
+    (
+        re.compile(r"(:[A-Za-z_]+:)(`)([^`<]+)(<[^`>]+>)(`)", flags=re.MULTILINE),
+        lambda x: x.groups()[2].strip(),
+    ),
+    # Roles to always include.
+    (
+        re.compile(r"(:(" + ("|".join(RE_TEXT_REPLACE_ROLES_INCLUDE)) + r"):)(`)([^`]+)(`)", flags=re.MULTILINE),
+        lambda x: x.groups()[3].strip(),
+    ),
+    # Roles to always exclude.
+    (
+        re.compile(r"(:(" + ("|".join(RE_TEXT_REPLACE_ROLES_EXCLUDE)) + r"):)(`)([^`]+)(`)", flags=re.MULTILINE),
+        lambda _: " ",
+    ),
+    # Ensure all roles are handled.
+    (
+        re.compile(r"(:[A-Za-z_]+:)(`)([^`]+)(`)", flags=re.MULTILINE),
+        regex_key_raise,
+    ),
+    # Match substitution for removal: `|identifier|`
+    (
+        re.compile(r"\|[a-zA-Z0-9_]+\|"),
+        lambda _: " ",
+    ),
+)
+
+RE_WORDS = re.compile(
+    r"\b("
+    # Capital words, with optional '-' and "'".
+    r"[A-Z]+[\-'A-Z]*[A-Z]|"
+    # Lowercase words, with optional '-' and "'".
+    r"[A-Za-z][\-'a-z]*[a-z]+"
+    r")\b"
+)
+
+
 def check_spelling_body(text):
-    for w in text.split():
-        # skip directive args (e.g. figure target), could do differently?
-        if w.startswith(":") and w.endswith(":"):
-            continue
-        if w.startswith("<") and w.endswith(">"):
+
+    # Wash text or inline RST.
+    for re_expr, re_replace_fn in RE_TEXT_REPLACE_TABLE:
+        text = re.sub(re_expr, re_replace_fn, text)
+
+    for re_match in RE_WORDS.finditer(text):
+        w = re_match.group(0)
+
+        # Skip entirely uppercase words.
+        # These are typically used for acronyms: XYZ, UDIM, API ... etc.
+        if w.isupper():
             continue
 
-        w = w.strip("{}[](),.!?;\"'1234567890-_*")
+        w_lower = w.lower()
 
-        if w.startswith(":") and w.endswith(":"):
-            continue
-        if w.startswith("<") and w.endswith(">"):
+        if USE_ONCE and w_lower in once_words:
             continue
 
-        # skip character and name entities
-        if w.startswith("\\") or w.startswith("|"):
-            continue
+        if check_word(w):
+            pass
+        elif "-" in w and all(check_word(w_split) for w_split in w.split("-")):
+            pass  # all words split by dash are correct, also pass
+        else:
+            bad_words.add(w)
+            # print(" %r" % w)
 
-        # now we've gotten rid of typical roles, strip other chars
-        w = w.strip(":`()<>{}")
-
-        # skip python references
-        if w.startswith("bpy."):
-            continue
-
-        # skip document references and keyboard shortcuts
-        if w.startswith("doc:") or w.startswith("kbd:") or w.startswith("menuselection:") or w.startswith("ref:"):
-            continue
-
-        w_ = w
-        for w in w_.split("/"):
-            if not w:
-                continue
-
-            w_lower = w.lower()
-
-            if USE_ONCE and w_lower in once_words:
-                continue
-
-            if check_word(w):
-                pass
-            elif "-" in w and all(check_word(w_split) for w_split in w.split("-")):
-                pass  # all words split by dash are correct, also pass
-            else:
-                bad_words.add(w)
-                # print(" %r" % w)
-
-                if USE_ONCE:
-                    once_words.add(w_lower)
+            if USE_ONCE:
+                once_words.add(w_lower)
 
 
 CURRENT_DIR = os.path.abspath(os.path.dirname(__file__))
@@ -192,6 +227,7 @@ directives.register_directive('highlight', directive_ignore_recursive)
 directives.register_directive('parsed-literal', directive_ignore_recursive)
 # Custom directives from extensions
 directives.register_directive('youtube', directive_ignore_recursive)
+directives.register_directive('peertube', directive_ignore_recursive)
 directives.register_directive('vimeo', directive_ignore_recursive)
 directives.register_directive('todolist', directive_ignore_recursive)
 
@@ -223,7 +259,7 @@ def role_ignore_recursive(
         name, rawtext, text, lineno, inliner,
         options={}, content=[],
 ):
-    return [RoleIgnore("", '', *(), **{})], []
+    return [RoleIgnoreRecursive("", '', *(), **{})], []
 
 
 roles.register_canonical_role('abbr', role_ignore)
@@ -306,13 +342,21 @@ def check_spelling(filename):
     doc.walkabout(visitor)
 
 
+RST_CONTEXT_FLAG_LITERAL = 1 << 0
+RST_CONTEXT_FLAG_LITERAL_BLOCK = 1 << 1
+RST_CONTEXT_FLAG_MATH = 1 << 2
+RST_CONTEXT_FLAG_COMMENT = 1 << 3
+
+
 class RstSpellingVisitor(docutils.nodes.NodeVisitor):
     __slots__ = (
         "document",
+        "skip_context",
     )
 
     def __init__(self, doc):
         self.document = doc
+        self.skip_context = 0
 
     # -----------------------------
     # Visitors (docutils callbacks)
@@ -400,8 +444,10 @@ class RstSpellingVisitor(docutils.nodes.NodeVisitor):
         # check_spelling_body(text)
 
     def visit_Text(self, node):
+        # Visiting text in a sipped context (literal for example).
+        if self.skip_context:
+            return
         text = node.astext()
-        # print(text)
         check_spelling_body(text)
 
     def depart_Text(self, node):
@@ -420,37 +466,48 @@ class RstSpellingVisitor(docutils.nodes.NodeVisitor):
         self.is_emphasis = False
 
     def visit_math(self, node):
+        self.skip_context |= RST_CONTEXT_FLAG_MATH
         raise docutils.nodes.SkipNode
 
     def depart_math(self, node):
-        pass
+        self.skip_context &= ~RST_CONTEXT_FLAG_MATH
 
     def visit_literal(self, node):
+        self.skip_context |= RST_CONTEXT_FLAG_LITERAL
         raise docutils.nodes.SkipNode
 
     def depart_literal(self, node):
-        pass
+        self.skip_context &= ~RST_CONTEXT_FLAG_LITERAL
 
     def visit_literal_block(self, node):
+        self.skip_context |= RST_CONTEXT_FLAG_LITERAL_BLOCK
         raise docutils.nodes.SkipNode
 
     def depart_literal_block(self, node):
+        self.skip_context &= ~RST_CONTEXT_FLAG_LITERAL_BLOCK
         pass
 
     def visit_code_block(self, node):
+        # No need to flag.
         raise docutils.nodes.SkipNode
 
     def depart_code_block(self, node):
         pass
 
     def visit_reference(self, node):
-        raise docutils.nodes.SkipNode
+        pass
 
     def depart_reference(self, node):
         pass
 
+    def visit_title_reference(self, node):
+        pass
+
+    def depart_title_reference(self, node):
+        pass
+
     def visit_download_reference(self, node):
-        raise docutils.nodes.SkipNode
+        pass
 
     def depart_download_reference(self, node):
         pass
@@ -458,7 +515,7 @@ class RstSpellingVisitor(docutils.nodes.NodeVisitor):
     def visit_date(self, node):
         # date = datetime.date(*(
         #    map(int, unicode(node[0]).split('-'))))
-        #metadata['creation_date'] = date
+        # metadata['creation_date'] = date
         pass
 
     # def visit_document(self, node):
@@ -466,10 +523,11 @@ class RstSpellingVisitor(docutils.nodes.NodeVisitor):
     #    # metadata['searchable_text'] = node.astext()
 
     def visit_comment(self, node):
+        self.skip_context |= RST_CONTEXT_FLAG_COMMENT
         raise docutils.nodes.SkipNode
 
     def depart_comment(self, node):
-        pass
+        self.skip_context &= ~RST_CONTEXT_FLAG_COMMENT
 
     def visit_raw(self, node):
         raise docutils.nodes.SkipNode

tools_rst_editor/rst_find_reference.py

@@ -178,7 +178,7 @@ def main(argv=None):
         print("Role", role_id, "not handled!", file=sys.stderr)
         sys.exit(1)
 
-    assert(line is not None)
+    assert (line is not None)
     print("%s:%d:%d" % (fn, line, col))