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

nex3 · 2024-06-11T04:58:49Z

What is this fixing or adding?

This allows Options to use the standard Python documentation format,
while producing much nicer-looking documentation in the WebView with
things like emphasis, lists, and so on.

While this behavior is on by default for new worlds, this also (at
@NewSoupVi's suggestion) adds a list of worlds that are opted into the
old "plain text" behavior. World authors can remove their worlds from
this list and update their Option documentation at their leisure.

HTML Tooltips

This also updates the tooltip infrastructure to support full HTML
tooltips, structured like so:

<div class="tooltip-container">
  (?)
  <div class="tooltip">Tooltip contents</div>
</div>

Plain text tooltips continue to work using the data-tooltip
attribute.

How was this tested?

I updated the Lingo documentation to use the new behavior, and
verified that other worlds' output doesn't change.

If this makes graphical changes, please attach screenshots.

Old look:

New look:

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.

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.

black-sliver · 2024-06-11T10:05:09Z

worlds/legacy_world_features.py

+# These worlds still use the old-style plain text Option docstrings. All other
+# worlds' Option docstrings are parsed as reStructuredText (the standard Python
+# docstring format) and rendered as HTML in the WebHost.
+for world_name in [


This breaks APWorlds. Please don't do this. Let the world opt in.

Imo breaking something purely visual for an apworld during AP's 0.# days, especially when apworld don't usually worry about being displayed on WebHost (cause how would they), needs to be okay

However, with Phar's alternate suggestion of how to implement this, I'm now on board with this being opt in. Just saying right now that I disagree with your philisophy in general and it will probably come up again in the future :P

Considering the long-term goal is decoupling worlds from core, I'm against adding anything that adds special privileges to worlds currently in the core repo (it also can't be edited easily from outside the apworld, if one of these world authors releases an updated apworld that would get placed in a webhost).

So regardless of what is decided (breaking existing APworlds or not), I am firmly against this file existing.

To give some background here, this was intended as a combined solution for two problems:

This change shouldn't break the rendering for existing core worlds.

It's infeasible to update existing core worlds in-place because doing so would require a review from every world maintainer.

APWorlds could still easily keep the old behavior by adding plain_text_doc = True to their options (or plain_text_options_doc = True to their World). The idea isn't so much to give special privileges to core worlds as to work around how difficult it would be to treat them the same as APWorlds.

All that said, it sounds like the consensus is that the core maintainers prefer this to be opt-out. I worry that's not the right call in the long-term when plain text option docs provide no benefits other than backwards-compatibility, but I'll bow to your decision and make the change.

black-sliver · 2024-06-11T10:20:11Z

WebHostLib/options.py

+    return publish_parts(text, writer_name='html', settings=None, settings_overrides={
+        'output_encoding': 'unicode'
+    })['body']


We probably want to avoid raw html for several reasons

text = """.. raw:: html <script>alert('pwned')</script>""" publish_parts(text, writer_name="html", settings=None, settings_overrides={"output_encoding": "unicode"})["body"]

returns "<script>alert('pwned')</script>"

Security may be a concern, since the option export could be "safe" (i.e. jsonworlds), but even if it wasn't, we don't want to have people put raw html there to work around issues instead of fixing them in core.

Fortunately this is an easy fix 🙂

ThePhar · 2024-06-11T13:33:42Z

Options.py

@@ -126,6 +126,23 @@ class Option(typing.Generic[T], metaclass=AssembleOptions):
    # can be weighted between selections
    supports_weighting = True

+    plain_text_doc = False


Rather than attach this to the Option class itself, wouldn't it make more sense to make this an attribute on WebWorld itself that applies to all options?

I don't see a reason why anyone migrating to reST formatting wouldn't just update all their doccomments, and depending on which becomes default (plain text should be default imo), if a dev decides to use the other, they'll have to set it on every option class.

This is such a better suggestion than what I've been suggesting holy damn

Yeah I think I'm now on board with this over my initial suggestion, and at that point, I think it's much better if this feature is opt-in than opt-out

worlds/lingo/options.py

Options.py

hatkirby

Overall looks great from the Lingo side! I found two minor typos but otherwise I think this is a good change.

worlds/lingo/options.py

NewSoupVi · 2024-06-11T15:37:34Z

I am now more on board with Phar's (honestly way better) suggestion of making this an attribute of WebWorld, and at that point, it's so easy to opt into that I'm in agreement with Black Sliver that it should be opt-in.

ThePhar · 2024-06-11T22:39:26Z

Oh, and if it wasn't mentioned elsewhere already, whatever the final API is proposed to look like, should also be documented in the world api documentation as well.

docs/options api.md

LegendaryLinux · 2024-06-13T16:30:40Z

I'm also on board with the opt-in method via WebWorld. I'll give the code some closer scrutiny tonight.

docs/options api.md

LegendaryLinux · 2024-06-13T17:06:11Z

I went ahead and looked at the code and it looks good, save for the documentation reference. I'll double check the styles later tonight since I'm not at my desktop computer right now.

LegendaryLinux · 2024-06-13T21:54:39Z

Okay, this is approved pending the update to the documentation.
I did cause a small merge conflict by merging #3513, but that should be easy to fix.

docs/options api.md

Options.py

Co-authored-by: Doug Hoskisson <[email protected]>

…n the WebView (ArchipelagoMW#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 <[email protected]> * Update Options.py Co-authored-by: Doug Hoskisson <[email protected]> --------- Co-authored-by: Chris Wilson <[email protected]> Co-authored-by: Doug Hoskisson <[email protected]>

nex3 added 3 commits June 10, 2024 21:08

Render option documentation as reStructuredText in the WebView

a181959

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

6dbb90a

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

7f0dbc3

github-actions bot added affects: core Issues/PRs that touch core and may need additional validation. affects: webhost Issues/PRs that touch webhost and may need additional validation. waiting-on: peer-review Issue/PR has not been reviewed by enough people yet. labels Jun 11, 2024

ThePhar added the waiting-on: world-maintainer Issue/PR is waiting for feedback or approval by the maintainer of a world. label Jun 11, 2024

ThePhar changed the title ~~Render option documentation as reStructuredText in the WebView~~ WebHost/Core/Lingo: Render option documentation as reStructuredText in the WebView Jun 11, 2024

ThePhar added is: documentation Improvements or additions to documentation. is: enhancement Issues requesting new features or pull requests implementing new features. labels Jun 11, 2024

LegendaryLinux self-assigned this Jun 11, 2024

black-sliver reviewed Jun 11, 2024

View reviewed changes

ScipioWright added the waiting-on: author Issue/PR is waiting for feedback or changes from its author. label Jun 11, 2024

ThePhar reviewed Jun 11, 2024

View reviewed changes

Exempt-Medic added waiting-on: author Issue/PR is waiting for feedback or changes from its author. and removed waiting-on: author Issue/PR is waiting for feedback or changes from its author. labels Jun 11, 2024

hatkirby suggested changes Jun 11, 2024

View reviewed changes

worlds/lingo/options.py Outdated Show resolved Hide resolved

worlds/lingo/options.py Outdated Show resolved Hide resolved

ScipioWright removed the waiting-on: world-maintainer Issue/PR is waiting for feedback or approval by the maintainer of a world. label Jun 11, 2024

nex3 added 4 commits June 11, 2024 19:34

Disable raw and file insertion RST directives

657fb26

Update doc comments per code review

9b3d739

Make rich text docs opt-in

181aaec

Put rich_text_options_doc on WebWorld

daea045

nex3 force-pushed the fancy-option-docs branch from a5305df to daea045 Compare June 12, 2024 03:43

Document rich text API

11f80af

nex3 requested review from ThePhar, NewSoupVi and black-sliver June 12, 2024 03:49

nex3 requested a review from hatkirby June 12, 2024 03:49

beauxq reviewed Jun 12, 2024

View reviewed changes

docs/options api.md Outdated Show resolved Hide resolved

LegendaryLinux reviewed Jun 13, 2024

View reviewed changes

docs/options api.md Outdated Show resolved Hide resolved

nex3 added 2 commits June 13, 2024 22:25

Code review

9f8fbfe

Merge remote-tracking branch 'origin/main' into fancy-option-docs

218524f

beauxq reviewed Jun 14, 2024

View reviewed changes

docs/options api.md Outdated Show resolved Hide resolved

beauxq reviewed Jun 14, 2024

View reviewed changes

Options.py Outdated Show resolved Hide resolved

LegendaryLinux and others added 2 commits June 14, 2024 18:51

Update docs/options api.md

e07d1fc

Co-authored-by: Doug Hoskisson <[email protected]>

Update Options.py

90b97bf

Co-authored-by: Doug Hoskisson <[email protected]>

LegendaryLinux approved these changes Jun 14, 2024

View reviewed changes

LegendaryLinux merged commit c61505b into ArchipelagoMW:main Jun 14, 2024
14 checks passed

nex3 deleted the fancy-option-docs branch June 14, 2024 23:02

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

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

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

nex3 commented Jun 11, 2024 •

edited

Loading

black-sliver Jun 11, 2024

NewSoupVi Jun 11, 2024

NewSoupVi Jun 11, 2024 •

edited

Loading

ThePhar Jun 11, 2024

nex3 Jun 12, 2024

black-sliver Jun 11, 2024

nex3 Jun 12, 2024

ThePhar Jun 11, 2024

NewSoupVi Jun 11, 2024 •

edited

Loading

hatkirby left a comment

NewSoupVi commented Jun 11, 2024 •

edited

Loading

ThePhar commented Jun 11, 2024

LegendaryLinux commented Jun 13, 2024

LegendaryLinux commented Jun 13, 2024 •

edited

Loading

LegendaryLinux commented Jun 13, 2024 •

edited

Loading

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

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

Conversation

nex3 commented Jun 11, 2024 • edited Loading

What is this fixing or adding?

HTML Tooltips

How was this tested?

If this makes graphical changes, please attach screenshots.

black-sliver Jun 11, 2024

Choose a reason for hiding this comment

NewSoupVi Jun 11, 2024

Choose a reason for hiding this comment

NewSoupVi Jun 11, 2024 • edited Loading

Choose a reason for hiding this comment

ThePhar Jun 11, 2024

Choose a reason for hiding this comment

nex3 Jun 12, 2024

Choose a reason for hiding this comment

black-sliver Jun 11, 2024

Choose a reason for hiding this comment

nex3 Jun 12, 2024

Choose a reason for hiding this comment

ThePhar Jun 11, 2024

Choose a reason for hiding this comment

NewSoupVi Jun 11, 2024 • edited Loading

Choose a reason for hiding this comment

hatkirby left a comment

Choose a reason for hiding this comment

NewSoupVi commented Jun 11, 2024 • edited Loading

ThePhar commented Jun 11, 2024

LegendaryLinux commented Jun 13, 2024

LegendaryLinux commented Jun 13, 2024 • edited Loading

LegendaryLinux commented Jun 13, 2024 • edited Loading

nex3 commented Jun 11, 2024 •

edited

Loading

NewSoupVi Jun 11, 2024 •

edited

Loading

NewSoupVi Jun 11, 2024 •

edited

Loading

NewSoupVi commented Jun 11, 2024 •

edited

Loading

LegendaryLinux commented Jun 13, 2024 •

edited

Loading

LegendaryLinux commented Jun 13, 2024 •

edited

Loading