Page MenuHomePhabricator
Create Task
Maniphest T318785

Broken links in Wikibase Doxygen Docs (doc.wikimedia.org/Wikibase)
Closed, ResolvedPublic
Actions

Description

  • A change to the releng/doxygen container image updated Doxygen to 1.9.1.
  • Doxygen 1.9.0 changed how files and anchors are referenced internally (see issue). Previously, a dash (-) in a filename would remain in the internal reference. Since 1.9.0, a dash (and other special characters) are converted to an underscore (_).
  • This has cause a lot of the @ref links to no longer work. For example, in the root of the topics section you can see a list where some links are working (because they only contain underscores (_)) and some are broken (due to still including a dash (-)).
  • There are also @subpage links that are broken causing a cluttered sidebar. For example, the Wikibase DataBridge page should be nested under the Wikibase Client page (according to the source) but instead is shown in the sidebar directly under the Wikibase root
  • This comment on the Doxygen issue recommends that we don't rely on the internal references created by Doxygen (the ones starting with md_) but instead use an explicit @anchor or Header Id Attributes
  • NOTE: the documentation for the Wikibase docs states that using Header Id Attributes was explicitly not used so that we wouldn't have to manually maintain them.
    • Also, as Header Id Attributes is a Doxygen specific syntax and appear on the same line as the markdown headers, other markdown viewers (e.g. GitHub) will render the Ids in large bold font with the header.

Details

SubjectRepoBranchLines +/-
WIP: DOC: Use filename.md or filepath.md instead of header idsmediawiki/extensions/Wikibasemaster+265 -196
DOC: Permanent fix for broken doxygen linksmediawiki/extensions/Wikibasemaster+334 -218
DOC: Quick fix doxygen referencesmediawiki/extensions/Wikibasemaster+46 -46
DOC: Other improvementsmediawiki/extensions/Wikibasemaster+36 -29
DOC: Update Doxygen documentation.md pagemediawiki/extensions/Wikibasemaster+32 -9
DOC: Fix doxygen config filemediawiki/extensions/Wikibasemaster+3 -2
Customize query in gerrit

Related Objects

Event Timeline

Ollie.Shotton_WMDE created this task.Sep 28 2022, 8:54 AM
Restricted Application added a subscriber: Aklapper. · View Herald TranscriptSep 28 2022, 8:54 AM
Maintenance_bot added a project: Wikidata.Sep 28 2022, 9:31 AM
gerritbot added a comment.Sep 28 2022, 11:21 AM

Change 836169 had a related patch set uploaded (by Ollie Shotton; author: Ollie Shotton):

[mediawiki/extensions/Wikibase@master] DOC: Fix doxygen config file

https://gerrit.wikimedia.org/r/836169

gerritbot added a project: Patch-For-Review.Sep 28 2022, 11:21 AM

Change 836170 had a related patch set uploaded (by Ollie Shotton; author: Ollie Shotton):

[mediawiki/extensions/Wikibase@master] DOC: Update Doxygen documentation.md page

https://gerrit.wikimedia.org/r/836170

gerritbot added a comment.Sep 28 2022, 11:21 AM

Change 836171 had a related patch set uploaded (by Ollie Shotton; author: Ollie Shotton):

[mediawiki/extensions/Wikibase@master] DOC: Other improvements

https://gerrit.wikimedia.org/r/836171

gerritbot added a comment.Sep 28 2022, 11:21 AM

Change 836172 had a related patch set uploaded (by Ollie Shotton; author: Ollie Shotton):

[mediawiki/extensions/Wikibase@master] DOC: Quick fix doxygen references

https://gerrit.wikimedia.org/r/836172

gerritbot added a comment.Sep 28 2022, 11:23 AM

Change 836173 had a related patch set uploaded (by Ollie Shotton; author: Ollie Shotton):

[mediawiki/extensions/Wikibase@master] DOC: Permanent fix for broken doxygen links

https://gerrit.wikimedia.org/r/836173

gerritbot added a comment.Sep 29 2022, 10:51 AM

Change 836169 merged by jenkins-bot:

[mediawiki/extensions/Wikibase@master] DOC: Fix doxygen config file

https://gerrit.wikimedia.org/r/836169

gerritbot added a comment.Sep 29 2022, 10:57 AM

Change 836170 merged by jenkins-bot:

[mediawiki/extensions/Wikibase@master] DOC: Update Doxygen documentation.md page

https://gerrit.wikimedia.org/r/836170

ReleaseTaggerBot added a project: MW-1.40-notes (1.40.0-wmf.4; 2022-10-03).Sep 29 2022, 11:00 AM
gerritbot added a comment.Sep 29 2022, 11:00 AM

Change 836171 merged by jenkins-bot:

[mediawiki/extensions/Wikibase@master] DOC: Other improvements

https://gerrit.wikimedia.org/r/836171

Ollie.Shotton_WMDE claimed this task.Sep 30 2022, 9:05 AM
Ollie.Shotton_WMDE moved this task from Non Product to Sprint 14 on the Wikibase Product Platform (v1) board.
Ollie.Shotton_WMDE edited projects, added Wikibase Product Platform (v1) (Sprint 14); removed Wikibase Product Platform (v1).
Ollie.Shotton_WMDE moved this task from To Do to Doing on the Wikibase Product Platform (v1) (Sprint 14) board.
gerritbot added a comment.Sep 30 2022, 4:19 PM

Change 836172 abandoned by Ollie Shotton:

[mediawiki/extensions/Wikibase@master] DOC: Quick fix doxygen references

Reason:

in favour of I239bda61246f9e6181fe2c632ded05e7260d4602

https://gerrit.wikimedia.org/r/836172

Ollie.Shotton_WMDE moved this task from Doing to Peer Review on the Wikibase Product Platform (v1) (Sprint 14) board.Sep 30 2022, 4:36 PM
Ollie.Shotton_WMDE moved this task from Inbox to Sorted Team PP on the [DEPRECATED] wdwb-tech board.
gerritbot added a comment.Oct 4 2022, 12:51 PM

Change 836173 merged by jenkins-bot:

[mediawiki/extensions/Wikibase@master] DOC: Permanent fix for broken doxygen links

https://gerrit.wikimedia.org/r/836173

Ollie.Shotton_WMDE moved this task from Peer Review to Done on the Wikibase Product Platform (v1) (Sprint 14) board.Oct 4 2022, 12:56 PM
Maintenance_bot removed a project: Patch-For-Review.Oct 4 2022, 1:30 PM
WMDE-leszek closed this task as Resolved.Oct 14 2022, 12:57 PM
Push-f subscribed.Oct 30 2022, 6:35 AM

I think this change broke a bunch of links that lived outside of the documenation (e.g. on www.mediawiki.org). I fixed a couple of them but I am not sure if these are all because the MediaWiki search for "md_doc" did not seem to find everything.

In the future please try to preserve old links.

Ollie.Shotton_WMDE added a comment.Nov 1 2022, 11:41 AM

Sorry, thanks for fixing the links!

Ollie.Shotton_WMDE added a comment.EditedNov 2 2022, 4:53 PM

Searches that reveal more broken links:

gerritbot added a comment.Nov 10 2022, 12:47 PM

Change 855559 had a related patch set uploaded (by Ollie Shotton; author: Ollie Shotton):

[mediawiki/extensions/Wikibase@master] WIP: DOC: Use filename.md or filepath.md instead of header ids

https://gerrit.wikimedia.org/r/855559

gerritbot added a project: Patch-For-Review.Nov 10 2022, 12:47 PM
gerritbot added a comment.Nov 10 2022, 1:21 PM

Change 855559 abandoned by Ollie Shotton:

[mediawiki/extensions/Wikibase@master] WIP: DOC: Use filename.md or filepath.md instead of header ids

Reason:

https://gerrit.wikimedia.org/r/855559

Ollie.Shotton_WMDE merged a task: T307503: Fix Wikibase docs on doc.wikimedia.org.Feb 6 2023, 9:20 AM
Ollie.Shotton_WMDE added a subscriber: Addshore.
Maintenance_bot removed a project: Patch-For-Review.Feb 6 2023, 9:30 AM
Content licensed under Creative Commons Attribution-ShareAlike (CC BY-SA) 4.0 unless otherwise noted; code licensed under GNU General Public License (GPL) 2.0 or later and other open source licenses. By using this site, you agree to the Terms of Use, Privacy Policy, and Code of Conduct. · Wikimedia Foundation · Privacy Policy · Code of Conduct · Terms of Use · Disclaimer · CC-BY-SA · GPL · Credits