Jump to content

Topic on Project:Village Pump

Api documentation bot

11
Krinkle (talkcontribs)

Hi,

Just a quick notice, letting you know I'm currently working on a bot that get's documentation from the PHP classes (required rights, must be posted, parameter optional/required + description, examples etc.) into wikitext and saving to a wiki page.

Zak originally created something for this (example), but the source code remains unpublished and the format has changed a lot since then.

Roughly what I've got / aiming for (about 50% done)

  • Extract module name/class pairs from $mainApi = new ApiMain
  • Loop over and instantiate it: $module = new $class( $mainApi, $name );
  • Buid a documentation page in wikitext format: new ApiDoc4Wikitext( $module );
    • {{API-head}} with parameter values from getModulePrefix, mustBePosted etc.
    • Parameter section build with a function based on makeHelpMsgParameters but in wikitext format
    • Examples section based on array from getExamples, which is then dissected into parts for {{ApiEx}}, followed by an http request to exampleurl+format=xmlfm and output cleaned up and unescaped and fed to result-parameter of {{ApiEx}}.
    • Categories
  • Either write wikitext to a file and let another bot save to wiki, or write a simple wikibot and save right away.

To be done:

  • Example section
  • Saving mechanism

Any ideas / existing code I can look at ?

John Vandenberg (talkcontribs)

The source code mentioned above is an empty svn folder. Is it hiding in an archived svn branch, or did it never see the light of day? This is now relatively easy to do with Pywikibot since I added a ParamInfo class. See API_talk:Main_page#Missing_documentation_pages for some basic code.

John Vandenberg (talkcontribs)

Does anyone know who Zak is? And/or where this prototype code might be?

P858snake (talkcontribs)

Zak was probably the contractor that the foundation hired a few years ago, Once his contact ended he didn't return.

MarkAHershberger (talkcontribs)

Zak hasn't been around for a while. I knew him when he was here (I had a chance to meet him in Gdansk) but since then he hasn't really been involved.

John Vandenberg (talkcontribs)

Thanks Peachey88 and Mark. Is his code lost? Can we contact him? phab:T31936 is related. I cant find much more about it.

MarkAHershberger (talkcontribs)

I sent him a message on FB. Let's see if he responds.

Zakgreant (talkcontribs)

Greetings All,

Any source code that remains in sitting in storage about 8000km from where I am at the moment. :-/

However, I'm happy to look at source code and otherwise pitch in some.

Cheers! --zak

Nemo bis (talkcontribs)

Note that ApiHelp can now be transcluded, see an example at Extension:Flow/API. I think SPage has plans to start/propose using this feature more widely once it gets possible to select content language à la {{TNT}} (currently it's only possible via interface language change, e.g. ).

John Vandenberg (talkcontribs)

So far, Special:ApiHelp is extremely ugly (but better than nothing), and the details on Extension:Flow/API are not provided by Special:ApiHelp - they are added by hand. Also there is one aspect of the documentation which can't be generated (currently): information about previous releases. i.e. when each module & parameter was added, deprecated, & removed. Sadly there is not a lot of care for wikis running anything but the bleeding edge.

{{API-head}} has been improved to include a link to the API help module, so the current help is easy to get to, and that template has been added to most of the existing API pages.

SPage (WMF) (talkcontribs)

My proposal is phab:T89318, John Vandenberg and RobinHood70 raise excellent points. We'll have this tension with any generated documentation, so I mention it in phab:T93026 "remove wiki documentation that duplicates generated documentation (tracking)."

"It gets rebuilt from scratch on every code change" is a feature and a bug :)

Reply to "Api documentation bot"