X Tutup
Skip to content

Fix doc formatting issue in @GlobalScope.log(), OS.shell_open(), JavaScriptBridge.is_js_buffer(), and Signal#117227

Open
EdwardChanCH wants to merge 1 commit intogodotengine:masterfrom
EdwardChanCH:fix_doc_globalscope_log
Open

Fix doc formatting issue in @GlobalScope.log(), OS.shell_open(), JavaScriptBridge.is_js_buffer(), and Signal#117227
EdwardChanCH wants to merge 1 commit intogodotengine:masterfrom
EdwardChanCH:fix_doc_globalscope_log

Conversation

@EdwardChanCH
Copy link
Contributor

@EdwardChanCH
Copy link
Contributor Author

In the future, maybe add a tip about not putting any BBCode formatting between [url] [/url] blocks?
https://docs.godotengine.org/en/latest/engine_details/class_reference/index.html

@Nintorch Nintorch added this to the 4.x milestone Mar 9, 2026
@AThousandShips AThousandShips changed the title Fixed doc formatting issue in @GlobalScope.log() Fix doc formatting issue in @GlobalScope.log() Mar 9, 2026
Copy link
Member

@bruvzg bruvzg left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's showing correctly in the built-in docs, and it is valid for HTML tags, so it's likely RST generator bug.

Image

@EdwardChanCH
Copy link
Contributor Author

I will try fixing the RST generator bug.

@EdwardChanCH
Copy link
Contributor Author

EdwardChanCH commented Mar 9, 2026

It turns out that RST cannot parse nested inline formatting (without using some workarounds):
https://docutils.sourceforge.io/FAQ.html#is-nested-inline-markup-possible

Here would be my "fix" if RST has nested inline formatting:

godot/doc/tools/make_rst.py

Lines 2282 to 2283 in a1eaac8

link_title = text[endq_pos + 1 : endurl_pos]
tag_text = make_link(url_target, link_title)

# New code:
link_title = text[endq_pos + 1 : endurl_pos]
    for invalid_nested_tag in ["url"]: # Use this if RST has nested inline formatting.
        if link_title.find(invalid_nested_tag) != -1:
            print_error(
                f"{state.current_class}.xml: Invalid link title for [url]: found a nested {invalid_nested_tag} tag before [/url] in {context_name}.",
                state,
            )
            break
formatted_link_title = format_text_block(link_title, context, state)
tag_text = make_link(url_target, formatted_link_title)

@EdwardChanCH EdwardChanCH changed the title Fix doc formatting issue in @GlobalScope.log() Fix doc formatting issue in @GlobalScope.log(), OS.shell_open(), JavaScriptBridge.is_js_buffer() Mar 9, 2026
@EdwardChanCH EdwardChanCH marked this pull request as draft March 9, 2026 22:57
@EdwardChanCH EdwardChanCH force-pushed the fix_doc_globalscope_log branch from 5b89d42 to ba13d56 Compare March 10, 2026 04:33
@EdwardChanCH
Copy link
Contributor Author

EdwardChanCH commented Mar 10, 2026

Found 4 more formatting issues related to nested tags: godotengine/godot-docs#11834
Also tested that all nested tags will have the same issue, e.g. [i][b]text[/b][/i] becomes **text**.

I can think of 3 ways to deal with this issue:

  1. Remove all existing nested tags and add warnings, which is possible since currently there are only 5 problematic nested tags in the entire doc.
  2. Remove the inner nested tags only for RST output, which is similar to option 1, but the online doc will differ from the offline doc.
  3. Use replace or this workaround, which requires a lot of effort and still has some edge cases.

My new commit implemented option 1.

@EdwardChanCH EdwardChanCH force-pushed the fix_doc_globalscope_log branch 4 times, most recently from 46ad71b to 4650f07 Compare March 10, 2026 05:19
@EdwardChanCH EdwardChanCH force-pushed the fix_doc_globalscope_log branch from 4650f07 to 04da573 Compare March 10, 2026 05:25
@EdwardChanCH EdwardChanCH marked this pull request as ready for review March 10, 2026 05:27
@EdwardChanCH EdwardChanCH requested a review from a team as a code owner March 10, 2026 05:27
@EdwardChanCH EdwardChanCH changed the title Fix doc formatting issue in @GlobalScope.log(), OS.shell_open(), JavaScriptBridge.is_js_buffer() Fix doc formatting issue in @GlobalScope.log(), OS.shell_open(), JavaScriptBridge.is_js_buffer(), and Signal Mar 10, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Formatting issue in @GlobalScope.log(), OS.shell_open(), JavaScriptBridge.is_js_buffer(), and Signal

3 participants

X Tutup