WebHost/Core/Lingo: Render option documentation as reStructuredText in the WebView (#3511)

* Render option documentation as reStructuredText in the WebView

This means that options can use the standard Python documentation
format, while producing much nicer-looking documentation in the
WebView with things like emphasis, lists, and so on.

* Opt existing worlds out of rich option docs

This avoids breaking the rendering of existing option docs which were
written with the old plain text rendering in mind, while also allowing
new options to default to the rich text rendering instead.

* Use reStructuredText formatting for Lingo Options docstrings

* Disable raw and file insertion RST directives

* Update doc comments per code review

* Make rich text docs opt-in

* Put rich_text_options_doc on WebWorld

* Document rich text API

* Code review

* Update docs/options api.md

Co-authored-by: Doug Hoskisson <beauxq@users.noreply.github.com>

* Update Options.py

Co-authored-by: Doug Hoskisson <beauxq@users.noreply.github.com>

---------

Co-authored-by: Chris Wilson <chris@legendserver.info>
Co-authored-by: Doug Hoskisson <beauxq@users.noreply.github.com>

2 files changed, 82 insertions, 39 deletions

@@ -16,6 +16,7 @@ from .regions import create_regions
 
 class LingoWebWorld(WebWorld):
     option_groups = lingo_option_groups
+    rich_text_options_doc = True
     theme = "grass"
     tutorials = [Tutorial(
         "Multiworld Setup Guide",
@@ -9,8 +9,12 @@ from .items import TRAP_ITEMS
 
 class ShuffleDoors(Choice):
     """If on, opening doors will require their respective "keys".
-    In "simple", doors are sorted into logical groups, which are all opened by receiving an item.
-    In "complex", the items are much more granular, and will usually only open a single door each."""
+
+    - **Simple:** Doors are sorted into logical groups, which are all opened by
+      receiving an item.
+    - **Complex:** The items are much more granular, and will usually only open
+      a single door each.
+    """
     display_name = "Shuffle Doors"
     option_none = 0
     option_simple = 1
@@ -19,24 +23,37 @@ class ShuffleDoors(Choice):
 
 class ProgressiveOrangeTower(DefaultOnToggle):
     """When "Shuffle Doors" is on, this setting governs the manner in which the Orange Tower floors open up.
-    If off, there is an item for each floor of the tower, and each floor's item is the only one needed to access that floor.
-    If on, there are six progressive items, which open up the tower from the bottom floor upward.
+
+    - **Off:** There is an item for each floor of the tower, and each floor's
+      item is the only one needed to access that floor.
+    - **On:** There are six progressive items, which open up the tower from the
+      bottom floor upward.
     """
     display_name = "Progressive Orange Tower"
 
 
 class ProgressiveColorful(DefaultOnToggle):
     """When "Shuffle Doors" is on "complex", this setting governs the manner in which The Colorful opens up.
-    If off, there is an item for each room of The Colorful, meaning that random rooms in the middle of the sequence can open up without giving you access to them.
-    If on, there are ten progressive items, which open up the sequence from White forward."""
+
+    - **Off:** There is an item for each room of The Colorful, meaning that
+      random rooms in the middle of the sequence can open up without giving you
+      access to them.
+    - **On:** There are ten progressive items, which open up the sequence from
+      White forward.
+    """
     display_name = "Progressive Colorful"
 
 
 class LocationChecks(Choice):
     """Determines what locations are available.
-    On "normal", there will be a location check for each panel set that would ordinarily open a door, as well as for achievement panels and a small handful of other panels.
-    On "reduced", many of the locations that are associated with opening doors are removed.
-    On "insanity", every individual panel in the game is a location check."""
+
+    - **Normal:** There will be a location check for each panel set that would
+      ordinarily open a door, as well as for achievement panels and a small
+      handful of other panels.
+    - **Reduced:** Many of the locations that are associated with opening doors
+      are removed.
+    - **Insanity:** Every individual panel in the game is a location check.
+    """
     display_name = "Location Checks"
     option_normal = 0
     option_reduced = 1
@@ -44,16 +61,20 @@ class LocationChecks(Choice):
 
 
 class ShuffleColors(DefaultOnToggle):
-    """
-    If on, an item is added to the pool for every puzzle color (besides White).
-    You will need to unlock the requisite colors in order to be able to solve puzzles of that color.
+    """If on, an item is added to the pool for every puzzle color (besides White).
+
+    You will need to unlock the requisite colors in order to be able to solve
+    puzzles of that color.
     """
     display_name = "Shuffle Colors"
 
 
 class ShufflePanels(Choice):
     """If on, the puzzles on each panel are randomized.
-    On "rearrange", the puzzles are the same as the ones in the base game, but are placed in different areas."""
+
+    On "rearrange", the puzzles are the same as the ones in the base game, but
+    are placed in different areas.
+    """
     display_name = "Shuffle Panels"
     option_none = 0
     option_rearrange = 1
@@ -66,22 +87,26 @@ class ShufflePaintings(Toggle):
 
 class EnablePilgrimage(Toggle):
     """Determines how the pilgrimage works.
-    If on, you are required to complete a pilgrimage in order to access the Pilgrim Antechamber.
-    If off, the pilgrimage will be deactivated, and the sun painting will be added to the pool, even if door shuffle is off."""
+
+    - **On:** You are required to complete a pilgrimage in order to access the
+      Pilgrim Antechamber.
+    - **Off:** The pilgrimage will be deactivated, and the sun painting will be
+      added to the pool, even if door shuffle is off.
+    """
     display_name = "Enable Pilgrimage"
 
 
 class PilgrimageAllowsRoofAccess(DefaultOnToggle):
-    """
-    If on, you may use the Crossroads roof access during a pilgrimage (and you may be expected to do so).
+    """If on, you may use the Crossroads roof access during a pilgrimage (and you may be expected to do so).
+
     Otherwise, pilgrimage will be deactivated when going up the stairs.
     """
     display_name = "Allow Roof Access for Pilgrimage"
 
 
 class PilgrimageAllowsPaintings(DefaultOnToggle):
-    """
-    If on, you may use paintings during a pilgrimage (and you may be expected to do so).
+    """If on, you may use paintings during a pilgrimage (and you may be expected to do so).
+
     Otherwise, pilgrimage will be deactivated when going through a painting.
     """
     display_name = "Allow Paintings for Pilgrimage"
@@ -89,11 +114,17 @@ class PilgrimageAllowsPaintings(DefaultOnToggle):
 
 class SunwarpAccess(Choice):
     """Determines how access to sunwarps works.
-    On "normal", all sunwarps are enabled from the start.
-    On "disabled", all sunwarps are disabled. Pilgrimage must be disabled when this is used.
-    On "unlock", sunwarps start off disabled, and all six activate once you receive an item.
-    On "individual", sunwarps start off disabled, and each has a corresponding item that unlocks it.
-    On "progressive", sunwarps start off disabled, and they unlock in order using a progressive item."""
+
+    - **Normal:** All sunwarps are enabled from the start.
+    - **Disabled:** All sunwarps are disabled. Pilgrimage must be disabled when
+      this is used.
+    - **Unlock:** Sunwarps start off disabled, and all six activate once you
+      receive an item.
+    - **Individual:** Sunwarps start off disabled, and each has a corresponding
+      item that unlocks it.
+    - **Progressive:** Sunwarps start off disabled, and they unlock in order
+      using a progressive item.
+    """
     display_name = "Sunwarp Access"
     option_normal = 0
     option_disabled = 1
@@ -109,10 +140,16 @@ class ShuffleSunwarps(Toggle):
 
 class VictoryCondition(Choice):
     """Change the victory condition.
-    On "the_end", the goal is to solve THE END at the top of the tower.
-    On "the_master", the goal is to solve THE MASTER at the top of the tower, after getting the number of achievements specified in the Mastery Achievements option.
-    On "level_2", the goal is to solve LEVEL 2 in the second room, after solving the number of panels specified in the Level 2 Requirement option.
-    On "pilgrimage", the goal is to solve PILGRIM in the Pilgrim Antechamber, typically after performing a Pilgrimage."""
+
+    - **The End:** the goal is to solve THE END at the top of the tower.
+    - **The Master:** The goal is to solve THE MASTER at the top of the tower,
+      after getting the number of achievements specified in the Mastery
+      Achievements option.
+    - **Level 2:** The goal is to solve LEVEL 2 in the second room, after
+      solving the number of panels specified in the Level 2 Requirement option.
+    - **Pilgrimage:** The goal is to solve PILGRIM in the Pilgrim Antechamber,
+      typically after performing a Pilgrimage.
+    """
     display_name = "Victory Condition"
     option_the_end = 0
     option_the_master = 1
@@ -122,9 +159,12 @@ class VictoryCondition(Choice):
 
 class MasteryAchievements(Range):
     """The number of achievements required to unlock THE MASTER.
-    In the base game, 21 achievements are needed.
-    If you include The Scientific and The Unchallenged, which are in the base game but are not counted for mastery, 23 would be required.
-    If you include the custom achievement (The Wanderer), 24 would be required.
+
+    - In the base game, 21 achievements are needed.
+    - If you include The Scientific and The Unchallenged, which are in the base
+      game but are not counted for mastery, 23 would be required.
+    - If you include the custom achievement (The Wanderer), 24 would be
+      required.
     """
     display_name = "Mastery Achievements"
     range_start = 1
@@ -134,9 +174,10 @@ class MasteryAchievements(Range):
 
 class Level2Requirement(Range):
     """The number of panel solves required to unlock LEVEL 2.
-    In the base game, 223 are needed.
-    Note that this count includes ANOTHER TRY.
-    When set to 1, the panel hunt is disabled, and you can access LEVEL 2 for free.
+
+    In the base game, 223 are needed. Note that this count includes ANOTHER TRY.
+    When set to 1, the panel hunt is disabled, and you can access LEVEL 2 for
+    free.
     """
     display_name = "Level 2 Requirement"
     range_start = 1
@@ -145,9 +186,10 @@ class Level2Requirement(Range):
 
 
 class EarlyColorHallways(Toggle):
-    """
-    When on, a painting warp to the color hallways area will appear in the starting room.
-    This lets you avoid being trapped in the starting room for long periods of time when door shuffle is on.
+    """When on, a painting warp to the color hallways area will appear in the starting room.
+
+    This lets you avoid being trapped in the starting room for long periods of
+    time when door shuffle is on.
     """
     display_name = "Early Color Hallways"
 
@@ -161,8 +203,8 @@ class TrapPercentage(Range):
 
 
 class TrapWeights(OptionDict):
-    """
-    Specify the distribution of traps that should be placed into the pool.
+    """Specify the distribution of traps that should be placed into the pool.
+
     If you don't want a specific type of trap, set the weight to zero.
     """
     display_name = "Trap Weights"