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