Last modified: 2014-11-02 16:03:23 UTC
Re: https://www.mediawiki.org/w/api.php The help output is really long, which is great for in-browser search, but sometimes I want to point a person to a specific section. It'd be nice to have HTML anchors in the help output of the MediaWiki Web API. For example, I'd like to be able to link to the "* meta=globaluserinfo (gui) *" section. Without HTML anchors (such as <span id="foo">bar</span>), pointing someone to a specific portion of the help output is difficult.
I'm sure this is a dupe... Of something that might've been WONTFIX'd or similar...
(In reply to Sam Reed (reedy) from comment #1) Perhaps you're thinking of bug 19721 (found via bug 26990)? I'd forgotten about bug 19721. I still think anchors would be helpful in the full Web API help output, but as an alternate idea, I'd accept including _links_ to the module-specific help pages from the main help page next to each module.
There has been some discussion (although I don't remember if any of it was public rather than just people talking to me) about reworking the default auto-generated help page to be actual HTML rather than the weird HTML/text/XML hybrid that it is now. The general idea would be that the landing page would give some general information and list the action modules as links somehow or other, and clicking the link for one would give you the help for just that module (and something like action=query would have the same setup for its submodules). There would also be a one-huge-page mode for printing or Ctrl-F searching. This would, of course, probably require some changes to the architecture of the existing API modules, to the point where it's probably something of a big project. And for maximum benefit it would ideally be integrated into i18n of the API so the help could be generated in non-English languages, which is itself a big project. These sorts of API-related projects may be my next project to work on.
action=help accepts a modules param, so you can choose one or more modules to link to (but you have already found the bug for that). That should be enough. For example: https://www.mediawiki.org/w/api.php?modules=tokens|query+info
(In reply to Brad Jorsch from comment #3) > There has been some discussion (although I don't remember if any of it was > public rather than just people talking to me) about reworking the default > auto-generated help page to be actual HTML rather than the weird > HTML/text/XML hybrid that it is now. *nod* Though I wonder how much of this would overlap with [[mw:API:Main page]] and [[mw:Special:ApiSandbox]]. There are definitely plenty of good ideas to consider and explore here. (In reply to db from comment #4) > That should be enough. > > For example: > https://www.mediawiki.org/w/api.php?modules=tokens|query+info I think this currently has very poor discoverability. I think we can improve the API user experience by adding anchor links and/or links to module-specific help pages in the current weird HTML/text/XML hybrid output, at least as an interim solution. If the whole output gets rewritten, this enhancement request will likely become moot.
(In reply to MZMcBride from comment #5) > *nod* Though I wonder how much of this would overlap with [[mw:API:Main > page]] There is some overlap. But I'm not considering changing the information available via api.php, just improving the formatting. So api.php would remain more of a programmer's quick reference while [[mw:API:Main page]] would remain more in-depth with explained examples.
Wording, 1.) Add id to the title of the modules to be anchored. 2.) Do we just need id or hyperlinks too? I would like to work on this can someone please assign me?
(In reply to kishanio from comment #7) > I would like to work on this can someone please assign me? You don't need to be assigned to a bug to be able to work on it. A comment on the bug is sufficient
Change 132734 had a related patch set uploaded by Kishanio: Add anchors to MediaWiki Web API help output https://gerrit.wikimedia.org/r/132734
WRT Brad Jorsch comment on gerrit, I need to put some identifier in to map actions & format in ApiFormatBase.php & hyperlink it. Right now we are using '*' to bold things and likewise i used % for format && %% for action. I don't why i picked it. But somehow foolishly with same thought it just breaks things in requests like api.php?action=parse&text=%25%25foo&title=Foo&prop=wikitext. Any thoughts on same?
(In reply to kishanio from comment #10) > Any thoughts on same? Not really. The best solution is as I outlined in comment 3, but that's far from an "easy" bug since it requires major architectural changes throughout the API classes.
(In reply to Brad Jorsch from comment #11) > Not really. The best solution is as I outlined in comment 3, but that's far > from an "easy" bug since it requires major architectural changes throughout > the API classes. In that case i'll remove keyword "easy" so no other newbies misinterpret it and start working on it. I'll keep following this space so later whenever you decide to work on it i can contribute as well.
Change 154355 had a related patch set uploaded by MarkTraceur: Add help links to API documentation page https://gerrit.wikimedia.org/r/154355
Change 160798 had a related patch set uploaded by Anomie: API: HTMLize and internationalize the help, add Special:ApiHelp https://gerrit.wikimedia.org/r/160798
Change 154355 abandoned by MarkTraceur: Add help links to API documentation page Reason: My gosh, the new format is nice. Happily abandoning. https://gerrit.wikimedia.org/r/154355
Change 160798 merged by jenkins-bot: API: HTMLize and internationalize the help, add Special:ApiHelp https://gerrit.wikimedia.org/r/160798
Change 132734 abandoned by Reedy: Add anchors to MediaWiki Web API help output Reason: I guess this really isn't needed anymore after the API help rewrite... https://gerrit.wikimedia.org/r/132734
