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>

docs/options api.md

@@ -85,6 +85,50 @@ class ExampleWorld(World):
     options: ExampleGameOptions
 ```
 
+### Option Documentation
+
+Options' [docstrings] are used as their user-facing documentation. They're displayed on the WebHost setup page when a
+user hovers over the yellow "(?)" icon, and included in the YAML templates generated for each game.
+
+[docstrings]: /docs/world%20api.md#docstrings
+
+The WebHost can display Option documentation either as plain text with all whitespace preserved (other than the base
+indentation), or as HTML generated from the standard Python [reStructuredText] format. Although plain text is the
+default for backwards compatibility, world authors are encouraged to write their Option documentation as
+reStructuredText and enable rich text rendering by setting `World.rich_text_options_doc = True`.
+
+[reStructuredText]: https://docutils.sourceforge.io/rst.html
+
+```python
+from worlds.AutoWorld import WebWorld
+
+
+class ExampleWebWorld(WebWorld):
+    # Render all this world's options as rich text.
+    rich_text_options_doc = True
+```
+
+You can set a single option to use rich or plain text by setting
+`Option.rich_text_doc`.
+
+```python
+from Options import Toggle, Range, Choice, PerGameCommonOptions
+
+
+class Difficulty(Choice):
+    """Sets overall game difficulty.
+
+    - **Easy:** All enemies die in one hit.
+    - **Normal:** Enemies and the player both have normal health bars.
+    - **Hard:** The player dies in one hit."""
+    display_name = "Difficulty"
+    rich_text_doc = True
+    option_easy = 0
+    option_normal = 1
+    option_hard = 2
+    default = 1
+```
+
 ### Option Groups
 Options may be categorized into groups for display on the WebHost. Option groups are displayed in the order specified
 by your world on the player-options and weighted-options pages. In the generated template files, there will be a comment

docs/world api.md

@@ -56,6 +56,12 @@ webhost:
 
 * `options_page` can be changed to a link instead of an AP-generated options page.
 
+* `rich_text_options_doc` controls whether [Option documentation] uses plain text (`False`) or rich text (`True`). It
+  defaults to `False`, but world authors are encouraged to set it to `True` for nicer-looking documentation that looks
+  good on both the WebHost and the YAML template.
+
+  [Option documentation]: /docs/options%20api.md#option-documentation
+
 * `theme` to be used for your game-specific AP pages. Available themes:
 
   | dirt                                       | grass (default)                             | grassFlowers                                       | ice                                       | jungle                                       | ocean                                       | partyTime                                       | stone                                       |