(10:31:38 AM) addshore: I dislike our docs on mw.org and generally find out of date docs every time I look somethingup
(10:32:01 AM) Reedy: greg-g: If the answer to docs is better autodocs, visibility of them etc... Rather than duping to mw.org It's gonna be relying on CI to get it published etc. Not saying your current team as is should be... It could be hire worthy
(10:32:05 AM) brion: yeah keeping wiki docs in sync with source is hell
(10:32:11 AM) brion: that's why i love doc comment generation
(10:32:18 AM) cscott-free: brion+1!
(10:32:31 AM) cscott-free: we should generate the mw docs on the $wgXXXX config variables from source somehow
(10:32:39 AM) addshore: brion: cscott Reedy also +1
(10:32:48 AM) cscott-free: the docs are great, but they are not in sync and there's nothing ensuring that new config vars get properly documented.
(10:33:02 AM) brion: cscott: that should actually not be difficult, doc comments on the vars already exist. should be able to expand them and extract from there
(10:33:03 AM) bawolff: Brion: we should make a third emmbed git into wikipage extension!
(10:33:04 AM) Reedy: Can we do it from https://doc.wikimedia.org/mediawiki-core/master/php/ ?
(10:33:12 AM) brion: :)
(10:33:19 AM) cscott-free: brion: yeah, but the existing mw docs are much larger than our current doc comments
(10:33:30 AM) cscott-free: there might be a readability issue if DefaultSettings.php suddenly grows 3x
(10:33:44 AM) cscott-free: we might need to split up DefaultSettings.php into multiple files or somesuch to keep it manageable.
Description
Event Timeline
This should definitely be doable, as mentioned in the chat transcript above. :) Recommend moving doc info from the wiki pages into the doc comments, then extracting them live from git into the page (or better yet, replace the pages with links to the live docs)
I did create such a piece of code some time ago, but didn’t take time to publish it. I publish it on GitHub in the next minutes -- don’t expect a clean code, it’s really hacky.
Code is there https://github.com/Seb35/mediawiki-config-schema and more importantly the extracted documentation is on https://gist.github.com/Seb35/1979f1a50fef76d0843decbc07035ef2.
There is really no reason Hook, DB table docs could not also be added to this
(and then deleted from mw.org)!!!!
Oh, that's even already possible with doxygen and... already there at doc.wikimedia.org:
https://doc.wikimedia.org/mediawiki-core/master/php/DefaultSettings_8php.html
It's just not showing up in the search.
But, it's already grouped, thanks to the code in DefaultSettings.php. Probably that is already good enough? :)