Page MenuHomePhabricator

Sprint: Prepare MediaWiki generated docs for easier writing of Markdown and misc clean up (Sept 2019)
Closed, ResolvedPublic

Description

We currently have:

  • Some text files in docs/ in the mediawiki-core repo that are only readable through Git file browsers which is fine for core patch contributors but not very discoverable or user friendly for extension developers and site admins (not versioned by MW release, not easily browsable or linkable from elsewhere).
  • Some markdown files in various places, also Git-only.
  • One markdown "Doxygen page" generated by a dummy PHP file (docs/doxygen_first_page.php). This is readable from https://doc.wikimedia.org.

After chatting with @apaskulin we decided to explore a bit into the direction of Doxygen pages, at least for the documentation we already have in Git, to make it easier to find and maintain.

I researched this before for ResourceLoader and for Hooks documentation pages, but never finished it. For this task, I'll try to dig up those past attempts and deliver the following:

  • Figure out a way to generate "Doxygen pages" from real Markdown files without having to put them inside a dummy PHP file with a big doc block.
  • Index one other markdown files as example.
  • Convert one text file to markdown as example and link to it from another one. Continues at T233244.

Event Timeline

Krinkle created this task.Sep 5 2019, 2:50 PM
Restricted Application added a subscriber: Aklapper. · View Herald TranscriptSep 5 2019, 2:50 PM
Krinkle added a comment.EditedSep 5 2019, 2:51 PM
From Gerrit

[mediawiki/core] docs: Remove unused PERL_PATH and unused file patterns from Doxyfile
https://gerrit.wikimedia.org/r/534541

From Gerrit

[mediawiki/core] docs: Convert doxygen_first_page.php to proper Markdown
https://gerrit.wikimedia.org/r/534542

From Gerrit

[mediawiki/core] docs: Remove unused Doxygen custom commands
https://gerrit.wikimedia.org/r/534544

Change 534624 had a related patch set uploaded (by Krinkle; owner: Krinkle):
[mediawiki/core@master] docs: Ignore .md from resources/lib in Doxyfile

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

Krinkle renamed this task from Get MediaWiki generated docs in shape for easier reading/writing of Markdown files. to Get MediaWiki generated docs in shape for easier reading/writing of Markdown files.Sep 5 2019, 2:54 PM

@hashar Do you remember why mwdocgen.php supports generating output in the Unix man page format? Was introduced in 3b8aa71cf8be (r101807). It's not a burden right now, but I'm looking to simplify this script and am thinking whether we should keep it or not.

Change 534631 had a related patch set uploaded (by Krinkle; owner: Krinkle):
[mediawiki/core@master] docs: Add support for @inheritDoc (alias for @inheritdoc)

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

Change 534632 had a related patch set uploaded (by Krinkle; owner: Krinkle):
[mediawiki/core@master] docs: Avoid Doxygen warnings for non-doc related tags

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

Change 534643 had a related patch set uploaded (by Krinkle; owner: Krinkle):
[mediawiki/core@master] docs: Factor out MWDoxygenFilter from mwdoc-filter.php with tests

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

Change 534631 merged by jenkins-bot:
[mediawiki/core@master] docs: Add support for @inheritDoc (alias for @inheritdoc)

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

Change 534632 merged by jenkins-bot:
[mediawiki/core@master] docs: Avoid Doxygen warnings for non-doc related tags

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

Change 534624 merged by jenkins-bot:
[mediawiki/core@master] docs: Ignore .md from resources/lib in Doxyfile

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

@hashar Do you remember why mwdocgen.php supports generating output in the Unix man page format? Was introduced in 3b8aa71cf8be (r101807). It's not a burden right now, but I'm looking to simplify this script and am thinking whether we should keep it or not.

I guess I have added support for man pages just for the sake of it. Albeit it is very handy to just man Title or man DefaultSettings.php, I would argue that probably nobody is using this feature. As such we should just dispose --generate-man I guess :-]

Change 534822 had a related patch set uploaded (by Krinkle; owner: Krinkle):
[mediawiki/core@master] docs: Remove GENERATE_MAN support from Doxyfile

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

Change 534822 merged by jenkins-bot:
[mediawiki/core@master] docs: Remove GENERATE_MAN support from Doxyfile

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

Change 534643 merged by jenkins-bot:
[mediawiki/core@master] docs: Factor out MWDoxygenFilter from mwdoc-filter.php with tests

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

Krinkle renamed this task from Get MediaWiki generated docs in shape for easier reading/writing of Markdown files to Sprint: Prepare MediaWiki generated docs for easier writing of Markdown and misc clean up (Sept 2019).Sep 9 2019, 6:00 PM

Change 535255 had a related patch set uploaded (by Krinkle; owner: Krinkle):
[mediawiki/core@master] Remove spurious @class tags in two files

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

Krinkle triaged this task as Medium priority.Sep 9 2019, 6:07 PM

Change 535255 merged by jenkins-bot:
[mediawiki/core@master] Remove spurious @class tags in two files

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

Krinkle claimed this task.Sep 9 2019, 7:59 PM
Gilles moved this task from Inbox to Doing on the Performance-Team board.Sep 9 2019, 8:03 PM

Change 536707 had a related patch set uploaded (by Krinkle; owner: Krinkle):
[mediawiki/core@master] docs: Disable GENERATE_TESTLIST and GENERATE_BUGLIST

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

Change 536708 had a related patch set uploaded (by Krinkle; owner: Krinkle):
[mediawiki/core@master] API: Add missing @ingroup API to a few Api-related classes

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

Change 536709 had a related patch set uploaded (by Krinkle; owner: Krinkle):
[mediawiki/core@master] actions: Rename Doxygen group from "Action done on pages" to "Actions"

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

Krinkle added a comment.EditedSep 14 2019, 12:28 AM
On Gerrit, @apaskulin submitted:

[mediawiki/core@master] docs: Exclude extra markdown files from Doxygen
https://gerrit.wikimedia.org/r/535684

This change also started excluding tests/ from indexing, which has sped up the overal time it takes to run Doxygen from 9 minutes to 5 minutes (ref):

Change 536707 merged by jenkins-bot:
[mediawiki/core@master] docs: Disable GENERATE_TESTLIST and GENERATE_BUGLIST

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

Change 536708 merged by jenkins-bot:
[mediawiki/core@master] API: Add missing @ingroup API to a few Api-related classes

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

Change 536743 had a related patch set uploaded (by Krinkle; owner: Krinkle):
[mediawiki/core@master] docs: Ignore extensions/ and skins/ in mwdocgen.php by default

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

Change 536709 merged by jenkins-bot:
[mediawiki/core@master] actions: Rename Doxygen group from "Action done on pages" to "Actions"

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

Change 537189 had a related patch set uploaded (by Krinkle; owner: Krinkle):
[integration/config@master] mediawiki-core-doxygen: Remove --no-extensions option to mwdocgen.php

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

Change 537189 merged by jenkins-bot:
[integration/config@master] mediawiki-core-doxygen: Remove --no-extensions option to mwdocgen.php

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

Change 536743 merged by jenkins-bot:
[mediawiki/core@master] docs: Ignore extensions/ and skins/ in mwdocgen.php by default

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