This is great. I think building HTML from source files is the way to go for dry reference material like this.
You need links both ways so people know the other format is available. The hooks.txt should say "The documentation at https://doc.wikimedia.org/mw-hooks/hooks_mainpage.htmlis regularly generated from the master branch of the gerrit repository."
If mediawiki.org's extension template linked "hooks in use" to this doc instead of mediawiki.org/Hooks:xyz pages then we could retire the latter pages and have less stuff to maintain. Except...
* It's sometimes useful that the Hooks pages are searchable along with the rest of the documentation on mediawiki.org.
* The mw.org hooks pages have additional information. E.g. comparing https://doc.wikimedia.org/mw-hooks/page_hooks_list.html#UserCreateForm and http://www.mediawiki.org/wiki/Manual:Hooks/UserCreateForm , the mw.org page has ** version = 1.6.0 ** source = SpecialUserlogin.php ** These categorize it as [Hooks added in MediaWiki 1.6.0] and [MediaWiki hooks included in SpecialUserlogin.php]
If we add this information to hooks.txt maybe there's a way doxygen can show the information and produce tables similar to the categories.
- The hooks are documented in a separate file (still docs/hooks.txt),
when we might want to have the doc near the wfRunHooks() call.
Hmm. On the one hand if they're all in one place it's easier to do cargo-cult pattern matching when adding new hook documentation. But if the doc is in the PHP near the wfRunHooks call it's more likely people will update it when making changes.
Now that we have mw.hook() in JavaScript we have a second universe of hooks to think about :)