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
On 14.05.2012, 7:04 Kevin wrote:
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.
https://en.wikipedia.org/wiki/Special:ApiSandbox
On 05/14/2012 02:57 AM, Max Semenik wrote:
On 14.05.2012, 7:04 Kevin wrote:
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.
Are you suggesting the removal of the existing API help function from core and the introduction of these missing features into ApiSandbox: a clear, unambiguous "Must POST" indication, "Required" and "Deprecated" markers for parameters, and a way of viewing default parameter values?
Currently, Special:ApiSandbox only serves as a supplement to, not a direct replacement for the complete documentation page, and the documentation at MediaWiki.org will always be out of date or partially irrelevant to an older version of MediaWiki a particular wiki might run (along with the set of installed extensions).
Some API functionality is implemented in the form of specific parameters part of more general modules. For example, one can use action=query&meta=userinfo&uiprop=hasmsg to check for new messages, not the (potentially) confusingly similar meta=allmessages. I am thinking of users who have no prior knowledge of the API or of MediaWiki internals. If users are truly familiar with MediaWiki internals, they might as well just look at the PHP source code in Git.
Do you see a way that Special:ApiSandbox could accommodate a single-page view of all API modules, so that API users can more easily determine which parts of the API they need to use?
wikitech-l@lists.wikimedia.org