Closed Bug 1726440 Opened 3 months ago Closed 1 month ago

Styled links are all broken in Web IDL source docs

Categories

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

defect

Tracking

()

RESOLVED FIXED
95 Branch
Tracking Status
firefox95 --- fixed

People

(Reporter: saschanaz, Assigned: saschanaz)

References

(Blocks 1 open bug)

Details

Attachments

(5 files, 2 obsolete files)

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?

Flags: needinfo?(echen)

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?

Flags: needinfo?(echen) → needinfo?(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.

Flags: needinfo?(peterv)

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.

Assignee: nobody → krosylight
Attachment #9237090 - Attachment description: WIP: Bug 1726440 - Convert IDL Bindings docs to Markdown → Bug 1726440 - Convert IDL Bindings docs to Markdown
Status: NEW → ASSIGNED

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.

(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!

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

Flags: needinfo?(sledru)

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

Flags: needinfo?(sledru)

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

Flags: needinfo?(krosylight)

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.

Flags: needinfo?(krosylight)

Set S3 as this doesn't affect firefox users.

Severity: -- → S3

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

Depends on D127656

Depends on D127689

Depends on D127690

Attachment #9244591 - Attachment description: WIP: Bug 1726440 - Part 1: Remove unused rst references → Bug 1726440 - Part 1: Remove unused rst references r=peterv
Attachment #9244592 - Attachment description: WIP: Bug 1726440 - Part 2: Assign proper languages to code directives → Bug 1726440 - Part 2: Assign proper languages to code directives r=peterv
Attachment #9244593 - Attachment description: WIP: Bug 1726440 - Part 3: Fix some typo → Bug 1726440 - Part 3: Fix some typo r=peterv
Attachment #9244594 - Attachment description: WIP: Bug 1726440 - Part 4: Migrate to Markdown → Bug 1726440 - Part 4: Migrate to Markdown r=peterv
Attachment #9238299 - Attachment is obsolete: true
Attachment #9237090 - Attachment is obsolete: true
Attachment #9244594 - Attachment description: Bug 1726440 - Part 4: Migrate to Markdown r=peterv → Bug 1726440 - Part 4-2: Migrate to Markdown r=peterv
Pushed by krosylight@mozilla.com:
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
Blocks: 1739989
You need to log in before you can comment on or make changes to this bug.