While considering adding syntax highlighting to the format=jsonfm output
of the API, I noticed the hackishness of the current API help page
system[1] and started working on a replacement that generates a "[...] a
fully-HTML version of the help message"[2] while remaining
fully compatible with existing extensions.
I propose moving API help to a new special page Special:ApiHelp, which
would run a few preg_replace operations and then the parser on
individual portions of the documentation to format them as HTML. The
combined output for all modules would be cached in memcached as in the
old ApiHelp class.
Here are a few questions about the best way to implement this:
1. Some members of ApiBase I need access to are marked "protected", yet
special pages have to subclass SpecialPage, not ApiBase. Which of
these possible solutions is least hackish?
(a) Generating the help page in an API module and then making
an internal API request to execute that module when accessing
the special page. The special page would show the result.
(b) Internally calling action=paraminfo, individually requesting
information on each API module to avoid encountering API limits.
This would avoid duplicating lines 183-200 and 223-227 of
includes/api/ApiParamInfo.php .
(c) Adding an "allmodules" option to action=paraminfo, which would
only be allowed for internal requests because I am unsure of how
to cache the result.[3]
This would have the same advantage as option (b).
2. In bug 26681[1], Sam Reed suggested moving ApiHelp out of core.
I disagree. One of the main uses of the API is for coding bots
and user scripts, which are a quicker and more convenient way to
automate wiki processes than extensions that a server admin must
install. Having accurate, easy-to-read documentation specific to
the MediaWiki version and set of extensions is extremely useful
when coding a bot or user script. So does API help really not
belong in core?
3. Special:ApiHelp would need about ten CSS rules to display properly.
Is creating a separate ResourceLoader module the norm in
this situation?
4. To fit as many parameters on screen as possible, Special:ApiHelp
would use a tabular layout similar to the current text-based output
format. Is there any advantage to using definition lists over tables
(or vice-versa), keeping in mind that CSS can style the definition
list to appear in two columns?
5. Certain "tags" can apply to modules (i.e. "Read",
"Write",
"Must POST", "Can generate"), which will go in the module's
heading.
Therefore, I need to reduce the tags' font size to that of the
body text similar to .editsection. Is there a good alternative to
copying the .editsection code for each skin (or just using the
percentages for Vector), given the limitations of CSS?
I would greatly appreciate your input.
[1]:
https://bugzilla.wikimedia.org/show_bug.cgi?id=26681
[2]: quoted from includes/api/ApiFormatBase.php
[3]:
https://bugzilla.wikimedia.org/show_bug.cgi?id=26680
--
Wikipedia user PleaseStand
http://en.wikipedia.org/wiki/User:PleaseStand