Fix non-styled topics

source/_static/custom.css

@@ -20,3 +20,7 @@ html.dark {
 .admonition.admonition-tool {
     --icon-url: var(--icon-wrench-url);
 }
+
+.admonition.admonition-example {
+    --icon-url: var(--icon-lightbulb-url);
+}

source/conf.py

@@ -18,7 +18,11 @@
 import datetime
 import urllib.parse
 
+from docutils import nodes
+from docutils.parsers.rst.directives.admonitions import BaseAdmonition
+
 from sphinx.errors import ExtensionError
+from sphinx.writers.html5 import HTML5Translator
 
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
@@ -476,7 +480,37 @@ def add_page_assets(app, pagename, templatename, context, doctree):
         app.add_css_file(css_file)
 
 
+class ExampleAdmonition(BaseAdmonition):
+    """.. example:: [title]"""
+
+    node_class = nodes.admonition
+    required_arguments = 0
+    optional_arguments = 1
+    final_argument_whitespace = True
+
+    def run(self):
+        self.arguments = ['Example: ' + self.arguments[0] if self.arguments else 'Example']
+        self.options['class'] = ['admonition-example', *self.options.get('class', [])]
+        return super().run()
+
+
+class TopicHeadingTranslator(HTML5Translator):
+    """Renders topic titles as h4 instead of p"""
+
+    def visit_title(self, node):
+        if isinstance(node.parent, nodes.topic) and 'contents' not in node.parent['classes']:
+            self.body.append(self.starttag(node, 'h4', '', CLASS='topic-title'))
+            self.context.append('</h4>\n')
+            self.add_secnumber(node)
+            self.add_fignumber(node.parent)
+        else:
+            super().visit_title(node)
+
+
 def setup(app):
     app.add_css_file('icons.css')
+    app.add_directive('example', ExampleAdmonition)
     app.connect('builder-inited', build_icon_css)
     app.connect('html-page-context', add_page_assets)
+    app.set_translator('html', TopicHeadingTranslator)
+    app.set_translator('dirhtml', TopicHeadingTranslator)

source/usage/clipboard.rst

@@ -93,13 +93,15 @@ To save your current clipboard to file, use ``//schem save <filename>``.
 
 To load a saved schematic, use ``//schem load <filename>``.
 
-.. topic:: A note on schematic formats
+.. admonition:: A note on schematic formats
+    :class: note
 
     Before WorldEdit version 7 (corresponding to Minecraft 1.13), the files were saved with a ".schematic" file extension in a format that was compatible with many other software such as MCEdit, Redstone Simulator, and more. Unfortunately, the format wasn't suited for the new block format Mojang was migrating to, so a new format was devised - named the `Sponge schematic format <https://github.com/SpongePowered/Schematic-Specification>`_, using the extension ".schem".
 
     Note that WorldEdit can still import old ".schematic" files saved in older versions (or third party programs) through a legacy compatibility layer, but they can no longer be written to.
 
-.. topic:: Relative positions and schematics
+.. admonition:: Relative positions and schematics
+    :class: note
 
     Both the origin of the copy and your offset to the copy are saved with the file so that you can load it back later on and paste the copy at its original location or relative to you as if you had copied it. You should be familiar with how ``//copy`` and ``//paste`` store your relative position.
 
@@ -151,8 +153,8 @@ WorldEdit has an inbuilt way to easily share schematic files online.
 
 To share your current clipboard online, use ``//schem share``. You can also supply a name for the schematic, as well as an alternate upload destination and format using the ``//schem share [name] [destination] [format]`` syntax.
 
-.. topic:: Share destinations
+By default, WorldEdit uploads schematics to the `EngineHub Paste Service <https://paste.enginehub.org/>`_. Other plugins and mods can use the WorldEdit API to register new share destinations that you can upload to via the destination argument of the command.
 
-    By default, WorldEdit uploads schematics to the `EngineHub Paste Service <https://paste.enginehub.org/>`_. Other plugins and mods can use the WorldEdit API to register new share destinations that you can upload to via the destination argument of the command.
+.. warning::
 
-    It's important to note, that schematics shared to the EngineHub Paste Service will be deleted after one month. This service should only be used for short-term share links, not as a long-term download location.
+    Schematics shared to the EngineHub Paste Service will be deleted after one month. This service should only be used for short-term share links, not as a long-term download location.

source/usage/general/masks.rst

@@ -18,7 +18,7 @@ Combining Masks
 
 To get a mask which matches the *intersection* of multiple masks, use a space to separate them. The intersection will match when *all* of the given masks match.
 
-.. topic:: Example: Combining Masks
+.. example:: Combining Masks
 
     Replacing surface stone with dirt using a mask intersection::
 
@@ -38,7 +38,7 @@ The simplest of masks, the block mask matches one or more blocks or block states
 
 To match more than one block, separate each with a comma.
 
-.. topic:: Example: Using the block mask
+.. example:: Using the block mask
 
     Removing all oak fences from your selection::
 
@@ -53,7 +53,7 @@ Mask Negation
 
 The ``!`` symbol can be used to negate everything that comes after it. That is, it matches anything *not* matched by a different mask. Any other mask can follow this.
 
-.. topic:: Example: Negating a mask
+.. example:: Negating a mask
 
     Replace any block that isn't dirt, stone, or grass with stone::
 
@@ -80,7 +80,7 @@ Offset Mask
 
 Using ``>`` (overlay) or ``<`` (underlay) preceding another mask will match blocks that are above or below the other mask, respectively.
 
-.. topic:: Example: Offset masks
+.. example:: Offset masks
 
     Creating a layer of slabs above planks in your selection::
 
@@ -93,7 +93,7 @@ Using `~` preceding another mask will match blocks that are adjacent to the othe
 
 .. note:: Adjacency for the case of this mask is defined as being directly next to or above/below. Diagonal blocks do not match.
 
-.. topic:: Example: Adjacency masks
+.. example:: Adjacency masks
 
     Surrounding all mob spawners with glowstone::
 
@@ -118,7 +118,7 @@ Block Category Mask
 
 Block categories, or `tags <https://minecraft.wiki/w/Tag>`_ can also be used as masks. A category mask will match any block that is in that category. Just like the pattern, the syntax is `##<tag>`.
 
-.. topic:: Example: Block Category Masks
+.. example:: Block Category Masks
 
    Replacing all carpets with a layer of snow::
 
@@ -131,7 +131,7 @@ The noise mask can create random noise. Specifying ``%<percent>`` will match the
 
 .. note:: Make note of the syntax difference here; Unlike patterns, the % sign preceeds the desired percentage for this mask
 
-.. topic:: Example: Using the random noise mask
+.. example:: Using the random noise mask
 
     Randomly replacing 50% of your selection with stone::
 
@@ -144,7 +144,7 @@ Like the block mask, this mask matches block states. Unlike the block mask, you
 
 The state mask has two modes, lenient and strict. In lenient mode (``^[state=value,...]``, it will match any block that has the given block states equal the given value, *or* any block that does not even have those properties. In strict mode (``^=[state=value,...]``), it will *only* match blocks that have the block states equal to that value.
 
-.. topic:: Example: Using the block state mask
+.. example:: Using the block state mask
 
     Removing all closed door, gates, and trapdoors::
 
@@ -155,7 +155,7 @@ Expression Mask
 
 This mask can evaluate a mathematical expression upon each block. The mask starts with ``=`` and then must have an :doc:`expression <../other/expressions>` which can use the variables ``x``, ``y``, and ``z``. The mask will match if the expression returns a positive value.
 
-.. topic:: Example: Expression masks
+.. example:: Expression masks
 
     Only edit blocks below a certain y-level::
 

source/usage/general/patterns.rst

@@ -24,7 +24,7 @@ Instead of specifying a block type directly, you can use ``hand`` or ``offhand``
 
 The states and NBT can still be set when using these, as if it were a normal block type. A top-level merge occurs for both state and NBT, with the keys specified in the command taking precedence.
 
-.. topic:: Example: Single block patterns
+.. example:: Single block patterns
 
     Setting a selection to stone::
 
@@ -67,7 +67,7 @@ Random Pattern
 
 This pattern allows setting random blocks from any number of other patterns. The basic form is as simple as a comma-separated list of patterns, which will be chosen from evenly. You can also specify weights for each pattern with ``<x>%<pattern>``.
 
-.. topic:: Example:: Random Patterns
+.. example:: Random Patterns
 
     Setting a selection to different types of stone, equally distributed::
 
@@ -86,7 +86,7 @@ Random State Pattern
 
 Prefixing any block type with an asterisk (``*``) will randomly choose between all states for that block for each position.
 
-.. topic:: Example: Random State Pattern
+.. example:: Random State Pattern
 
     Setting oak logs facing in random directions::
 
@@ -97,7 +97,7 @@ Clipboard Pattern
 
 The ``#clipboard`` pattern will take blocks from your :doc:`clipboard <../clipboard>` in the same arrangement. This makes it easy to build one part of a repeating complicated pattern by hand, and then repeat it over and over. You can also offset the pattern by adding ``@[x,y,z]``.
 
-.. topic:: Example: Using the clipboard pattern
+.. example:: Using the clipboard pattern
 
     Replacing :ref:`all existing blocks <usage/general/masks:Existing block mask>` to your clipboard::
 
@@ -123,7 +123,7 @@ Type or State Applying Pattern
 
 This pattern, prefixed by ``^``, lets you set the type or states of a block without modifying everything else. This pattern will, for example, allow you to change a spiral staircase from oak to acacia without having to worry about the stairs facing in different directions and so on. You can either specify a block type (to change block type but not states, where applicable), or any number of states (to only change those states, where applicable).
 
-.. topic:: Example: Type/State Applying Patterns
+.. example:: Type/State Applying Patterns
 
     Replacing all oak stairs to acacia stairs, while maintaining orientation, etc::
 
@@ -148,7 +148,7 @@ This pattern allows setting random blocks within a block category, often referre
 
 The syntax for this pattern is ``##<tag name>``, which will randomly choose between the default state of all blocks in the category. You can also mix this with the random state pattern (``##*<tag name>``) to use all states, not just the defaults.
 
-.. topic:: Example: Block Category Pattern Usage
+.. example:: Block Category Pattern Usage
 
     Replacing all existing blocks with rainbow wool::
 
@@ -168,7 +168,7 @@ Sign Text
 
 You can set text on signs by separating it with a pipe symbol (``|``). Note that if the text has spaces, you must wrap the entire pattern in quotes ``""``.
 
-.. topic:: Example: Setting sign text
+.. example:: Setting sign text
 
     Simple Example::
 
@@ -183,7 +183,7 @@ Player Heads
 
 You can set the skin of a player head by specifying a username after the pipe symbol.
 
-.. topic:: Example: Setting a skin on a head
+.. example:: Setting a skin on a head
 
     .. code::
 
@@ -194,7 +194,7 @@ Mob Spawners
 
 You can set the type of mob to be spawned (again via the pipe symbol). Note that the name of the mob must be an `entity ID <https://minecraft.wiki/w/Java_Edition_data_values#Entities>`_. Prefixing `minecraft:` is optional, modded mobs must have a namespace.
 
-.. topic:: Example: Creating a squid spawner
+.. example:: Creating a squid spawner
 
     .. code::
 

source/usage/generation.rst

@@ -30,7 +30,7 @@ For elliptical cylinders, you can instead specify two radii: one for the east-we
     //cyl <pattern> <radiusEW>,<radiusNS> [height]
     //hcyl <pattern> <radiusEW>,<radiusNS> [height]
 
-.. topic:: Example: Creating cylinders and circles
+.. example:: Creating cylinders and circles
 
     Creating a filled glass cylinder of radius 5 and height 10::
 
@@ -130,7 +130,7 @@ The expression should return true (``> 0``) for blocks that are part of the shap
 Shape Examples
 --------------
 
-.. topic:: Example: Generating various shapes
+.. example:: Generating various shapes
 
     Torus of major radius 0.75 and minor radius 0.25::
 

source/usage/other/craftscripts.rst

@@ -58,7 +58,7 @@ All block editing in WorldEdit is done through an EditSession. This object handl
 
 Every time you call that method, you will get a new ``EditSession``, so be sure to keep one around. To set blocks, you will either need to provide a ``BlockState`` which is a combination of a block type and one or more states, or a ``BaseBlock``, which is a ``BlockState`` that may additionally have NBT data.
 
-.. topic:: Example: Setting a block to white wool
+.. example:: Setting a block to white wool
 
     ::
 
@@ -78,7 +78,7 @@ Arguments are passed in under the ``argv`` variable. If you need to check whethe
 
 The ``CraftScriptContext`` can to some basic argument parsing with ``CraftScriptContext#getBlock()``. You can also hook directly into WorldEdit's parsers via ``WorldEdit.getInstance().getPatternFactory()`` and ``.getMaskFactory()``.
 
-.. topic:: Example: Checking arguments
+.. example:: Checking arguments
 
     ::
 

source/usage/other/expressions.rst

@@ -97,30 +97,26 @@ Prefix
 
 These operators precede the expression they apply to.
 
-.. topic:: Prefix Operators
+.. csv-table::
+    :widths: 3, 15
 
-    .. csv-table::
-        :widths: 3, 15
-
-        ``-x``,(negation)
-        ``~x``,Bitwise complement (see bitwise binary operators)
-        ``!x``,Logical complement (see logical binary operators)
-        ``++x``,Pre-increment
-        ``--x``,Pre-decrement
+    ``-x``,(negation)
+    ``~x``,Bitwise complement (see bitwise binary operators)
+    ``!x``,Logical complement (see logical binary operators)
+    ``++x``,Pre-increment
+    ``--x``,Pre-decrement
 
 Postfix
 -------
 
 These operators succeed the expression they apply to.
 
-.. topic:: Postfix Operators
-
-    .. csv-table::
-        :widths: 3, 15
+.. csv-table::
+    :widths: 3, 15
 
-        ``x!``,Factorial
-        ``x++``,Post-increment
-        ``x--``,Post-decrement
+    ``x!``,Factorial
+    ``x++``,Post-increment
+    ``x--``,Post-decrement
 
 Ternary infix
 -------------
@@ -206,17 +202,15 @@ Functions
 Constants
 ~~~~~~~~~
 
-.. topic:: Constants
+The following constants are always available, and cannot be assigned.
 
-    The following constants are always available, and cannot be assigned.
-
-    .. csv-table::
-        :widths: 3, 6, 10
+.. csv-table::
+    :widths: 3, 6, 10
 
-        ``e``,2.7182818284590452354,The base of the natural logarithm
-        ``pi``,3.14159265358979323846,The ratio between circumference and diameter of a circle
-        ``true``,1,for boolean operations
-        ``false``,0,for boolean operations
+    ``e``,2.7182818284590452354,The base of the natural logarithm
+    ``pi``,3.14159265358979323846,The ratio between circumference and diameter of a circle
+    ``true``,1,for boolean operations
+    ``false``,0,for boolean operations
 
 Block Statements
 ~~~~~~~~~~~~~~~~