Docs - formatting - clean up whitespace

docs/advanced_topics/streamfield_migrations.md

@@ -187,15 +187,14 @@ The `wagtail.blocks.migrations` modules were added.
 
 Wagtail provides a set of utilities for creating data migrations on StreamField data. These are exposed through the modules:
 
-- `wagtail.blocks.migrations.migrate_operation`
-- `wagtail.blocks.migrations.operations`
-- `wagtail.blocks.migrations.utils`
+-   `wagtail.blocks.migrations.migrate_operation`
+-   `wagtail.blocks.migrations.operations`
+-   `wagtail.blocks.migrations.utils`
 
 ```{note}
    An add-on package [wagtail-streamfield-migration-toolkit](https://github.com/wagtail/wagtail-streamfield-migration-toolkit) is available, additionally providing limited support for auto-generating migrations.
 ```
 
-
 ### Why are data migrations necessary?
 
 If you change the block definition of a StreamField on a model that has existing data, you may have to manually alter that data to match the new format.
@@ -206,8 +205,8 @@ Generally, data migrations are performed manually by making an empty migration f
 
 To reduce boilerplate, and the potential for errors, `wagtail.blocks.migrations` provides the following:
 
-- utilities to recurse through stream data structures and apply changes; and
-- operations for common use cases like renaming, removing and altering values of blocks.
+-   utilities to recurse through stream data structures and apply changes; and
+-   operations for common use cases like renaming, removing and altering values of blocks.
 
 (streamfield_migration_basic_usage)=
 
@@ -335,10 +334,10 @@ class Migration(migrations.Migration):
 The `MigrateStreamData` class takes a list of operations and corresponding block paths as a parameter `operations_and_block_paths`. Each operation in the list will be applied to all blocks that match the corresponding block path.
 
 ```python
-operations_and_block_paths=[ 
+operations_and_block_paths=[
     (operation1, block_path1),
     (operation2, block_path2),
-    ... 
+    ...
 ]
 ```
 
@@ -358,7 +357,7 @@ class MyDeepNestedBlock(StreamBlock):
     foo = CharBlock()
     date = DateBlock()
 
-class MyNestedBlock(StreamBlock): 
+class MyNestedBlock(StreamBlock):
     char1 = CharBlock()
     deepnested1 = MyDeepNestedBlock()
 
@@ -406,7 +405,7 @@ If we want to match all "deepnested1" blocks, which are a direct child of "neste
 When the path contains a ListBlock child, 'item' must be added to the block path as the name of said child. For example, if we consider the following stream definition:
 
 ```python
-class MyStructBlock(StructBlock): 
+class MyStructBlock(StructBlock):
     char1 = CharBlock()
     char2 = CharBlock()
 
@@ -420,10 +419,10 @@ Then if we want to match "char1", which is a child of the StructBlock which is t
 
 The following operations are available for renaming and removing blocks.
 
-- [RenameStreamChildrenOperation](rename_stream_children_operation)
-- [RenameStructChildrenOperation](rename_struct_children_operation)
-- [RemoveStreamChildrenOperation](remove_stream_children_operation)
-- [RemoveStructChildrenOperation](remove_struct_children_operation)
+-   [RenameStreamChildrenOperation](rename_stream_children_operation)
+-   [RenameStructChildrenOperation](rename_struct_children_operation)
+-   [RemoveStreamChildrenOperation](remove_stream_children_operation)
+-   [RemoveStructChildrenOperation](remove_struct_children_operation)
 
 Note that all of these operations operate on the value of the parent block of the block which must be removed or renamed. Hence make sure that the block path you are passing points to the parent block when using these operations (see the example in [basic usage](streamfield_migration_basic_usage)).
 
@@ -431,9 +430,9 @@ Note that all of these operations operate on the value of the parent block of th
 
 The following operations allow you to alter the structure of blocks in certain ways.
 
-- [](stream_children_to_list_block_operation): operates on the value of a `StreamBlock`. Combines all child blocks of type `block_name` as children of a single ListBLock which is a child of the parent `StreamBlock`.
-- [](stream_children_to_stream_block_operation): operates on the value of a `StreamBlock`. Note that `block_names` here is a list of block types and not a single block type unlike `block_name` in the previous operation. Combines each child block of a type in `block_names` as children of a single `StreamBlock` which is a child of the parent `StreamBlock`.
-- [](stream_children_to_struct_block_operation): moves each `StreamBlock` child of the given type inside a new `StructBlock`
+-   [](stream_children_to_list_block_operation): operates on the value of a `StreamBlock`. Combines all child blocks of type `block_name` as children of a single ListBLock which is a child of the parent `StreamBlock`.
+-   [](stream_children_to_stream_block_operation): operates on the value of a `StreamBlock`. Note that `block_names` here is a list of block types and not a single block type unlike `block_name` in the previous operation. Combines each child block of a type in `block_names` as children of a single `StreamBlock` which is a child of the parent `StreamBlock`.
+-   [](stream_children_to_struct_block_operation): moves each `StreamBlock` child of the given type inside a new `StructBlock`
 
 A new `StructBlock` will be created as a child of the parent `StreamBlock` for each child block of the given type, and then that child block will be moved from the parent `StreamBlock`'s children inside the new `StructBlock` as a child of that `StructBlock`.
 
@@ -476,7 +475,7 @@ Block ids are not preserved here since the new blocks are structurally different
 
 #### Other operations
 
-- [](alter_block_value_operation)
+-   [](alter_block_value_operation)
 
 (custom_streamfield_migration_operations)=
 
@@ -496,7 +495,7 @@ class MyBlockOperation(BaseBlockOperation):
         super().__init__()
         # we will need to keep the length as an attribute of the operation
         self.length = length
-        
+
     def apply(self, block_value):
         # block value is the string value of the CharBlock
         new_block_value = block_value[:self.length]

docs/reference/streamfield/data_migrations.md

@@ -2,7 +2,7 @@
 
 # StreamField data migration reference
 
-## wagtail.blocks.migrations.migrate\_operation
+## wagtail.blocks.migrations.migrate_operation
 
 ### MigrateStreamData
 
@@ -28,14 +28,14 @@ MigrateStreamData constructor
 
 **Arguments**:
 
-- `app_name` _str_ - Name of the app.
-- `model_name` _str_ - Name of the model.
-- `field_name` _str_ - Name of the `StreamField`.
-- `operations_and_block_paths` _List[Tuple[operation, str]]_ - List of operations and the block paths to apply them to.
-- `revisions_from` _datetime, optional_ - Only revisions created from this date onwards will be updated. Passing `None` updates all revisions. Defaults to `None`. Note that live and latest revisions will be updated regardless of what value this takes.
-- `chunk_size` _int, optional_ - chunk size for `queryset.iterator` and `bulk_update`.
-  Defaults to 1024.
-- `**kwargs` - atomic, elidable, hints for superclass `RunPython` can be given
+-   `app_name` _str_ - Name of the app.
+-   `model_name` _str_ - Name of the model.
+-   `field_name` _str_ - Name of the `StreamField`.
+-   `operations_and_block_paths` _List[Tuple[operation, str]]_ - List of operations and the block paths to apply them to.
+-   `revisions_from` _datetime, optional_ - Only revisions created from this date onwards will be updated. Passing `None` updates all revisions. Defaults to `None`. Note that live and latest revisions will be updated regardless of what value this takes.
+-   `chunk_size` _int, optional_ - chunk size for `queryset.iterator` and `bulk_update`.
+    Defaults to 1024.
+-   `**kwargs` - atomic, elidable, hints for superclass `RunPython` can be given
 
 **Example**:
 
@@ -69,11 +69,10 @@ Renames all `StreamBlock` children of the given type
 
 The `block_path_str` when using this operation should point to the parent `StreamBlock` which contains the blocks to be renamed, not the block being renamed.
 
-
 **Attributes**:
 
-- `old_name` _str_ - name of the child block type to be renamed
-- `new_name` _str_ - new name to rename to
+-   `old_name` _str_ - name of the child block type to be renamed
+-   `new_name` _str_ - new name to rename to
 
 (rename_struct_children_operation)=
 
@@ -91,8 +90,8 @@ The `block_path_str` when using this operation should point to the parent `Struc
 
 **Attributes**:
 
-- `old_name` _str_ - name of the child block type to be renamed
-- `new_name` _str_ - new name to rename to
+-   `old_name` _str_ - name of the child block type to be renamed
+-   `new_name` _str_ - new name to rename to
 
 (remove_stream_children_operation)=
 
@@ -108,10 +107,9 @@ Removes all `StreamBlock` children of the given type
 
 The `block_path_str` when using this operation should point to the parent `StreamBlock` which contains the blocks to be removed, not the block being removed.
 
-
 **Attributes**:
 
-- `name` _str_ - name of the child block type to be removed
+-   `name` _str_ - name of the child block type to be removed
 
 (remove_struct_children_operation)=
 
@@ -127,10 +125,9 @@ Removes all `StructBlock` children of the given type
 
 The `block_path_str` when using this operation should point to the parent `StructBlock` which contains the blocks to be removed, not the block being removed.
 
-
 **Attributes**:
 
-- `name` _str_ - name of the child block type to be removed
+-   `name` _str_ - name of the child block type to be removed
 
 (stream_children_to_list_block_operation)=
 
@@ -146,11 +143,10 @@ Combines `StreamBlock` children of the given type into a new `ListBlock`
 
 The `block_path_str` when using this operation should point to the parent `StreamBlock` which contains the blocks to be combined, not the child block itself.
 
-
 **Attributes**:
 
-- `block_name` _str_ - name of the child block type to be combined
-- `list_block_name` _str_ - name of the new `ListBlock` type
+-   `block_name` _str_ - name of the child block type to be combined
+-   `list_block_name` _str_ - name of the new `ListBlock` type
 
 (stream_children_to_stream_block_operation)=
 
@@ -166,11 +162,10 @@ Combines `StreamBlock` children of the given types into a new `StreamBlock`
 
 The `block_path_str` when using this operation should point to the parent `StreamBlock` which contains the blocks to be combined, not the child block itself.
 
-
 **Attributes**:
 
-- `block_names` _[str]_ - names of the child block types to be combined
-- `stream_block_name` _str_ - name of the new `StreamBlock` type
+-   `block_names` _[str]_ - names of the child block types to be combined
+-   `stream_block_name` _str_ - name of the new `StreamBlock` type
 
 (alter_block_value_operation)=
 
@@ -184,7 +179,7 @@ Alters the value of each block to the given value
 
 **Attributes**:
 
-- `new_value`: new value to change to
+-   `new_value`: new value to change to
 
 (stream_children_to_struct_block_operation)=
 
@@ -236,13 +231,13 @@ Our altered stream data would look like this:
 
 **Notes**:
 
-- The `block_path_str` when using this operation should point to the parent `StreamBlock` which contains the blocks to be combined, not the child block itself.
-- Block ids are not preserved here since the new blocks are structurally different than the previous blocks.
+-   The `block_path_str` when using this operation should point to the parent `StreamBlock` which contains the blocks to be combined, not the child block itself.
+-   Block ids are not preserved here since the new blocks are structurally different than the previous blocks.
 
 **Attributes**:
 
-- `block_names` _str_ - names of the child block types to be combined
-- `struct_block_name` _str_ - name of the new `StructBlock` type
+-   `block_names` _str_ - names of the child block types to be combined
+-   `struct_block_name` _str_ - name of the new `StructBlock` type
 
 ## wagtail.blocks.migrations.utils
 
@@ -254,7 +249,7 @@ class InvalidBlockDefError(Exception)
 
 Exception for invalid block definitions
 
-#### map\_block\_value
+#### map_block_value
 
 ```python
 def map_block_value(block_value, block_def, block_path, operation, **kwargs)
@@ -264,16 +259,16 @@ Maps the value of a block.
 
 **Arguments**:
 
-- `block_value`: The value of the block. This would be a list or dict of children for structural blocks.
-- `block_def`: The definition of the block.
-- `block_path`: A `"."` separated list of names of the blocks from the current block (not included) to the nested block of which the value will be passed to the operation.
-- `operation`: An Operation class instance (extends `BaseBlockOperation`), which has an `apply` method for mapping values.
+-   `block_value`: The value of the block. This would be a list or dict of children for structural blocks.
+-   `block_def`: The definition of the block.
+-   `block_path`: A `"."` separated list of names of the blocks from the current block (not included) to the nested block of which the value will be passed to the operation.
+-   `operation`: An Operation class instance (extends `BaseBlockOperation`), which has an `apply` method for mapping values.
 
 **Returns**:
 
 Transformed value
 
-#### map\_struct\_block\_value
+#### map_struct_block_value
 
 ```python
 def map_struct_block_value(struct_block_value, block_def, block_path,
@@ -284,15 +279,15 @@ Maps each child block in a `StructBlock` value.
 
 **Arguments**:
 
-- `stream_block_value`: The value of the `StructBlock`, a dict of child blocks
-- `block_def`: The definition of the `StructBlock`
-- `block_path`: A `"."` separated list of names of the blocks from the current block (not included) to the nested block of which the value will be passed to the operation.
+-   `stream_block_value`: The value of the `StructBlock`, a dict of child blocks
+-   `block_def`: The definition of the `StructBlock`
+-   `block_path`: A `"."` separated list of names of the blocks from the current block (not included) to the nested block of which the value will be passed to the operation.
 
 **Returns**:
 
-- mapped_value: The value of the `StructBlock` after transforming its children.
+-   mapped_value: The value of the `StructBlock` after transforming its children.
 
-#### map\_list\_block\_value
+#### map_list_block_value
 
 ```python
 def map_list_block_value(list_block_value, block_def, block_path, **kwargs)
@@ -302,15 +297,15 @@ Maps each child block in a `ListBlock` value.
 
 **Arguments**:
 
-- `stream_block_value`: The value of the `ListBlock`, a list of child blocks
-- `block_def`: The definition of the `ListBlock`
-- `block_path`: A `"."` separated list of names of the blocks from the current block (not included) to the nested block of which the value will be passed to the operation.
+-   `stream_block_value`: The value of the `ListBlock`, a list of child blocks
+-   `block_def`: The definition of the `ListBlock`
+-   `block_path`: A `"."` separated list of names of the blocks from the current block (not included) to the nested block of which the value will be passed to the operation.
 
 **Returns**:
 
-- mapped_value: The value of the `ListBlock` after transforming all the children.
+-   mapped_value: The value of the `ListBlock` after transforming all the children.
 
-#### apply\_changes\_to\_raw\_data
+#### apply_changes_to_raw_data
 
 ```python
 def apply_changes_to_raw_data(raw_data, block_path_str, operation, streamfield,
@@ -321,10 +316,10 @@ Applies changes to raw stream data
 
 **Arguments**:
 
-- `raw_data`: The current stream data (a list of top level blocks)
-- `block_path_str`: A `"."` separated list of names of the blocks from the top level block to the nested block of which the value will be passed to the operation.
-- `operation`: A subclass of `operations.BaseBlockOperation`. It will have the `apply` method for applying changes to the matching block values.
-- `streamfield`: The `StreamField` for which data is being migrated. This is used to get the definitions of the blocks.
+-   `raw_data`: The current stream data (a list of top level blocks)
+-   `block_path_str`: A `"."` separated list of names of the blocks from the top level block to the nested block of which the value will be passed to the operation.
+-   `operation`: A subclass of `operations.BaseBlockOperation`. It will have the `apply` method for applying changes to the matching block values.
+-   `streamfield`: The `StreamField` for which data is being migrated. This is used to get the definitions of the blocks.
 
 **Returns**:
 
@@ -340,8 +335,9 @@ block_name = str
 ```
 
 A block path is either:
-- the empty string, in which case the operation should be applied to the top-level stream; or
-- a `"."` (period) separated sequence of block names, where block names are the names given to the blocks in the `StreamField` definition.
+
+-   the empty string, in which case the operation should be applied to the top-level stream; or
+-   a `"."` (period) separated sequence of block names, where block names are the names given to the blocks in the `StreamField` definition.
 
 Block names are the values associated with the `"type"` keys in the stream data's dictionary structures. As such, traversing or selecting `ListBlock` members requires the use of the `"item"` block name.
 

docs/releases/4.2.md

@@ -133,7 +133,6 @@ If these are used within packages or customisations they will need to be updated
 | `tab_nav_link`      | `{% include 'wagtailadmin/shared/tabs/tab_nav_link.html' with classname="..." %}`                      | `{% include 'wagtailadmin/shared/tabs/tab_nav_link.html' with classes="..." %}`                      |
 | `side_panel_button` | `{% include 'wagtailadmin/shared/side_panels/includes/side_panel_button.html' with classname="..." %}` | `{% include 'wagtailadmin/shared/side_panels/includes/side_panel_button.html' with classes="..." %}` |
 
-
 ### `InlinePanel` JavaScript function is now a class
 
 The (internal, undocumented) `InlinePanel` JavaScript function, used to initialise client-side behaviour for inline panels, has been converted to a class. Any user code that calls this function should now replace `InlinePanel(...)` calls with `new InlinePanel(...)`. Additionally, child form controls are now initialised automatically, and so it is no longer necessary to call `initChildControls`, `updateChildCount`, `updateMoveButtonDisabledStates` or `updateAddButtonState`.