1726440 - Styled links are all broken in Web IDL source docs

Status: RESOLVED FIXED

(Core :: DOM: Bindings (WebIDL), defect)

Description

[Kagami Rosylight [:saschanaz] (they/them)]

https://firefox-source-docs.mozilla.org/dom/webIdlBindings/

Texts are rendered like:

All WebIDL files should be placed in `dom/webidl https://searchfox.org/mozilla-central/source/dom/webidl/`__ and added to the list in the moz.build file in that directory.

Which is just wrong.

I'm not sure how to fix that in reStructuredText format, and I'm not sure what value is there to keep that format when Markdown support is already there in source docs.

How about converting it to Markdown?

Comment 1

[Edgar Chen [:edgar]]

Per https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#gotchas, reStructuredText doesn't support nested inline markup. It seems like it doesn't support a mix of inline markup and hyperlink, either.
I have no opinion on converting it to Markdown. What do you think, :peterv?

Comment 2

[Peter Van der Beken [:peterv]]

Yeah, reStructuredText doesn't have an easy way to support that as far as I could find (see https://docutils.sourceforge.io/FAQ.html#is-nested-inline-markup-possible). I didn't remove the broken formatting, because the original formatting had some value and I was hoping a solution would turn up eventually.

I'm not opposed to converting to Markdown, although I think all the other documentation in dom already uses reStructuredText. So it seems like the value that Markdown would bring isn't exactly overwhelming either.

Comment 3

[Kagami Rosylight [:saschanaz] (they/them)]

Attachment: Bug 1726440 - Convert IDL Bindings docs to Markdown

First converted by pandoc index.rst -o index.md -t gfm, formatted by Prettier with --prose-wrap=always, and then did some manual fix for the broken links and the C++ reflection table.

Comment 4

[Peter Van der Beken [:peterv]]

Attachment: WIP: Bug 1726440 - Convert IDL Bindings docs to Markdown

First converted with pandoc index.rst -o index.md -t gfm, did some manual fix for the broken links and the C++ reflection table, and then formatted with Prettier by --prose-wrap=always.

Comment 5

[Kagami Rosylight [:saschanaz] (they/them)]

(In reply to Peter Van der Beken [:peterv] from comment #4)

Created attachment 9238299 [details]
WIP: Bug 1726440 - Convert IDL Bindings docs to Markdown

First converted with pandoc index.rst -o index.md -t gfm, did some manual fix for the broken links and the C++ reflection table, and then formatted with Prettier by --prose-wrap=always.

Thank you for doing that for me!

Comment 6

[Sylvestre Ledru [:Sylvestre]]

I think it is possible. See:

https://firefox-source-docs.mozilla.org/code-quality/index.html
https://firefox-source-docs.mozilla.org/_sources/code-quality/index.rst.txt

Comment 7

[Kagami Rosylight [:saschanaz] (they/them)]

Sorry, I don't see which part of it uses styled links, could you point the line number? (specifically this kind of style.)

Comment 8

[Sylvestre Ledru [:Sylvestre]]

Sorry, I misunderstood. I parsed "in table".

Comment 9

[Anne (:annevk)]

Kagami, it seems this might have gotten lost, but also seems worthwhile to finish?

Comment 10

[Kagami Rosylight [:saschanaz] (they/them)]

I'll try splitting the patch since it includes something more than conversion e.g. assigning proper language for code blocks and removing redundant section ids.

And probably applying prettier also can be a separate step.

Comment 11

[Edgar Chen [:edgar]]

Set S3 as this doesn't affect firefox users.

Comment 12

[Kagami Rosylight [:saschanaz] (they/them)]

Attachment: Bug 1726440 - Part 1: Remove unused rst references r=peterv

Those ids were generated by MDN but nothing really uses them.

Depends on D127656

Comment 13

[Kagami Rosylight [:saschanaz] (they/them)]

Attachment: Bug 1726440 - Part 2: Assign proper languages to code directives r=peterv

Depends on D127688

Comment 14

[Kagami Rosylight [:saschanaz] (they/them)]

Attachment: Bug 1726440 - Part 3: Fix some typo r=peterv

Depends on D127689

Comment 15

[Kagami Rosylight [:saschanaz] (they/them)]

Attachment: Bug 1726440 - Part 4-2: Migrate to Markdown r=peterv

Depends on D127690

Comment 16

[Kagami Rosylight [:saschanaz] (they/them)]

Attachment: Bug 1726440 - Part 4-1: Rename from .rst to .md r=peterv

Comment 17

[Pulsebot]

Pushed by [e-mail]:
https://hg.mozilla.org/integration/autoland/rev/41c92a7c3667
Part 1: Remove unused rst references r=peterv DONTBUILD
https://hg.mozilla.org/integration/autoland/rev/3bf9463f2fa4
Part 2: Assign proper languages to code directives r=peterv DONTBUILD
https://hg.mozilla.org/integration/autoland/rev/140a93caa8a3
Part 3: Fix some typo r=peterv DONTBUILD
https://hg.mozilla.org/integration/autoland/rev/e379fb6e91d2
Part 4-1: Rename from .rst to .md r=peterv DONTBUILD
https://hg.mozilla.org/integration/autoland/rev/e8d7db0d2ca4
Part 4-2: Migrate to Markdown r=peterv DONTBUILD

Comment 18

[Narcis Beleuzu [:NarcisB]]

https://hg.mozilla.org/mozilla-central/rev/41c92a7c3667
https://hg.mozilla.org/mozilla-central/rev/3bf9463f2fa4
https://hg.mozilla.org/mozilla-central/rev/140a93caa8a3
https://hg.mozilla.org/mozilla-central/rev/e379fb6e91d2
https://hg.mozilla.org/mozilla-central/rev/e8d7db0d2ca4