diff --git a/source/_icons/lightbulb.svg b/source/_icons/lightbulb.svg new file mode 100644 index 0000000..4bc455c --- /dev/null +++ b/source/_icons/lightbulb.svg @@ -0,0 +1,17 @@ + + + + + + diff --git a/source/_static/custom.css b/source/_static/custom.css index 8f5d215..8b82af7 100644 --- a/source/_static/custom.css +++ b/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); +} diff --git a/source/conf.py b/source/conf.py index bfb0c7b..3240bd0 100644 --- a/source/conf.py +++ b/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('\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) diff --git a/source/usage/clipboard.rst b/source/usage/clipboard.rst index 08e8f14..a8ff4af 100644 --- a/source/usage/clipboard.rst +++ b/source/usage/clipboard.rst @@ -93,13 +93,15 @@ To save your current clipboard to file, use ``//schem save ``. To load a saved schematic, use ``//schem load ``. -.. 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 `_, 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 `_. 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 `_. 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. diff --git a/source/usage/general/masks.rst b/source/usage/general/masks.rst index 79b3585..924eafc 100644 --- a/source/usage/general/masks.rst +++ b/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 `_ 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 `##`. -.. 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 ``%`` 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:: diff --git a/source/usage/general/patterns.rst b/source/usage/general/patterns.rst index eb49f52..2285d5f 100644 --- a/source/usage/general/patterns.rst +++ b/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 ``%``. -.. 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 ` 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 ``##``, which will randomly choose between the default state of all blocks in the category. You can also mix this with the random state pattern (``##*``) 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 `_. Prefixing `minecraft:` is optional, modded mobs must have a namespace. -.. topic:: Example: Creating a squid spawner +.. example:: Creating a squid spawner .. code:: diff --git a/source/usage/generation.rst b/source/usage/generation.rst index 0841d8a..aa018a6 100644 --- a/source/usage/generation.rst +++ b/source/usage/generation.rst @@ -30,7 +30,7 @@ For elliptical cylinders, you can instead specify two radii: one for the east-we //cyl , [height] //hcyl , [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:: diff --git a/source/usage/other/craftscripts.rst b/source/usage/other/craftscripts.rst index e56f667..7cf7e5e 100644 --- a/source/usage/other/craftscripts.rst +++ b/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 :: diff --git a/source/usage/other/expressions.rst b/source/usage/other/expressions.rst index 97eabcc..b748c90 100644 --- a/source/usage/other/expressions.rst +++ b/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 ~~~~~~~~~~~~~~~~ diff --git a/source/usage/regions/regionops.rst b/source/usage/regions/regionops.rst index ba206b1..5345274 100644 --- a/source/usage/regions/regionops.rst +++ b/source/usage/regions/regionops.rst @@ -13,7 +13,7 @@ Setting Blocks The most basic operation, the ``//set `` command allows you to set all blocks in your selection to a given pattern. -.. topic:: Example: Setting your selection +.. example:: Setting your selection A simple pattern:: @@ -30,7 +30,7 @@ If you don't want to set *all* the blocks in your selection, you can decide whic Note that you can omit the mask argument in the command - it will default to the :doc:`existing block mask <../general/masks>`. -.. topic:: Example: Replacing blocks in your selection +.. example:: Replacing blocks in your selection Replacing all non-air blocks with grass:: @@ -77,7 +77,7 @@ There are several flags available: * ``-e`` will also copy entities into each stacked area * ``-b`` will also copy biomes into each stacked area (you may need to re-join the world to see changes) -.. topic:: Some uses of the stack command +.. example:: Some uses of the stack command .. figure:: /images/selections/stack_bridge.jpg @@ -104,7 +104,7 @@ You can also use the ``-s`` flag to move your selection along with the blocks, s The move command also takes the same three flags as ``//stack``, ``-e`` to move entities, ``-b`` to copy biomes (source biomes unaffected), and ``-m `` to move only matching blocks. -.. topic:: Example: Using the move command +.. example:: Using the move command Moving the selection 2 blocks forward, leaving stone:: @@ -173,7 +173,7 @@ The expression should take the variables ``x``, ``y``, and ``z`` and change them By default, coordinates are normalized from -1 to 1 on each axis, from the min to max points of your selection. Using the ``-r`` flag will use raw world coordinates, while ``-o`` will use Minecraft coordinates scale offset to your placement position. -.. topic:: Example: Deforming regions +.. example:: Deforming regions Making bumpy terrain:: diff --git a/source/usage/regions/selections.rst b/source/usage/regions/selections.rst index 6e58e95..cf8e24d 100644 --- a/source/usage/regions/selections.rst +++ b/source/usage/regions/selections.rst @@ -108,7 +108,7 @@ You can also specify multiple directions separated by commas to expand in multip You can specify two numbers and the region will be expanded in two opposite directions simultaneously. -.. topic:: Example: Expanding upwards +.. example:: Expanding upwards .. figure:: /images/selections/expand_up.png :figclass: light-only @@ -132,7 +132,7 @@ Contracting the selection This command works similarly to ``//expand``, but instead contract. -.. topic:: Example: Contracting downwards +.. example:: Contracting downwards .. figure:: /images/selections/contract_down.png :figclass: light-only @@ -201,7 +201,7 @@ The ``-c`` flag operates on your clipboard instead of your selection. The ``-d`` flag separates by block states instead of just types. -.. topic:: Example: Block distribution output +.. example:: Block distribution output Only by block type:: diff --git a/source/usage/snapshots.rst b/source/usage/snapshots.rst index 480a164..93d7bbe 100644 --- a/source/usage/snapshots.rst +++ b/source/usage/snapshots.rst @@ -14,7 +14,7 @@ In order for WorldEdit to be able to read your backups, you will have to choose Once set, just toss either copies of your world folder or zipped copies of your world folder into your backup folder. An example of how you could lay out your backups folder is below. -.. topic:: Example: Possible structures of backup storage +.. example:: Possible structures of backup storage |f| ``backups/`` (this is the folder name in the config) |f| ``world/`` (this is the name of a world)