We have content that lives in git that we want to appear in wiki pages:
=== Documentation in git
- [[ https://github.com/wikimedia/mediawiki/tree/master/docs | core/docs ]] files
- 23 text files
- many are actually wikitext or Markdown-ish despite no extension or .txt extension ({T116690})
- hooks.txt is a special case, T93043 and now {T115388}
- some HTML bits in [[ https://github.com/wikimedia/mediawiki/tree/master/docs/uidesign | docs/html ]]
- also proposal to keep [[https://www.mediawiki.org/wiki/Category:Architectural_modules_of_MediaWiki | architectural module docs]] in git and publish to wiki
- extension markdowndoc files
- mostly README.md files ([[https://github.com/wikimedia/mediawiki-extensions-MassMessage/blob/master/README.md | sample]]) whose information is duplicated on the extension's page on mw.org.
- others, e.g. [[ https://github.com/wikimedia/mediawiki-extensions-ContentTranslation/blob/master/hooks.md | ContentTranslation/hooks.md ]]
- plus some .txt files , mostly `hooks.txt`
- [[ https://github.com/wikimedia/mediawiki-extensions-Wikibase/tree/master/docs | extensions/WIikibase/docs ]] has five big .wiki files (e.g. [[ https://phabricator.wikimedia.org/diffusion/EWBA/browse/master/docs/ | lua.wiki]] is manually copied to [[ https://www.mediawiki.org/wiki/Extension:Wikibase_Client/Lua | WikiExtension:Wikibase Client/Lua ]]) plus summaries.txt
- The three opening paragraphs of https://doc.wikimedia.org/oojs-ui/master/js/#!/api/OO.ui.Toolbar (generated from [[/diffusion/GOJU/browse/master/src/Toolbar.js | Toolbar.js]]) and https://www.mediawiki.org/wiki/OOjs_UI/Toolbars were identical and are now drifting apart.
- because github renders a subset of wiki markup when viewing //path/file//`.wiki` or //file//`.mediawiki`, developers are creating [[ https://github.com/wikimedia/mediawiki-extensions-MobileFrontend/blob/master/CREDITS.mediawiki | CREDITS.mediawiki ]], [[ https://github.com/wikimedia/mediawiki#readme | README.mediawiki ]], etc.
=== Sample code from git
- [[ https://github.com/wikimedia/mediawiki-extensions-examples | extensions/examples ]] source code
- production code that demonstrates something useful
-- e.g. [[ https://www.mediawiki.org/wiki/API:Calling_internally | PHP Api request ]] has code from Extension:WikiLove
-- e.g. [[ https://www.mediawiki.org/wiki/HTMLForm/tutorial2 | HTMLForm/tutorial2 ]] has code from ??
= Minimum viable product
# Develop an extension such that4 existing wiki page can transclude latest content from git using some syntax, probably like [[ https://www.mediawiki.org/wiki/Extension:Git2Pages| Git2Page]]'s `{{snippet}}` parser function, with similar functionality.
# Using this editors can
- transclude wikitext into the page
- It can provide source code to the [[ https://www.mediawiki.org/wiki/Extension:SyntaxHighlight_GeSHi | <source>]] tag or parser function to transclude highlighted source code into the page.
# [[ https://www.mediawiki.org/wiki/Writing_an_extension_for_deployment | The extension is deployed on the production wiki ]] for mediawiki.org:
- caching strategy
- continuous integration
- security review
- etc.
=== Possible/desirable features
//After the MVP!//
- Alternative syntax?: develop a special page e.g. //Special:FromGit//, and transclude it in other pages, e.g. `{{[[Special:FromGit/`//project/git/path/path/to/file//`]]}}` (This is a similar approach to `{{Special:ApiHelp/query categoryinfo}}` which transcludes action API documentation.)
- Transcluded content is available to Lua modules to operate on, e.g. transform hooks.txt into something useful.
- //maybe// also push to wiki page using some kind of src->destWikiPage mapping file
- Don't require complicated Jenkins job builder-fu.
- Transcluded content appears in a tag or template that identifies source, so that users can edit the text around it.
- for simple transclusion MVP, simply invoke it from a wiki template similar to [[ https://www.mediawiki.org/wiki/Template:Api_help | Template:Api_help]]).
- Convert .txt,- Render Markdown files (e.g. .md and other formats to MediaWiki's brand of wikitextusing [[ https://michelf.ca/projects/php-markdown/ | PHP Markdown ]])
- Render .txt files with some minimal formatting (just the `<poem>` tag?)
- Render other formats if agreed (e.g. [[ http://johnmacfarlane.net/pandoc/try/ | pandoc ]]).
- Explore alternative syntax?: develop a special page e.g. //Special:FromGit//, and transclude that in other pages, e.g. `{{[[Special:FromGit/`//project/git/path/path/to/file//`]]}}` (This is a similar approach to `{{Special:ApiHelp/query categoryinfo}}` which transcludes action API documentation.)
For sample code, we need to transclude a snippets perparts of Git files into a wiki page ([[ https://www.mediawiki.org/wiki/HTMLForm/tutorial2 | see example]]), so we want:
- partial transclusion, of a namedgiven section. Git2pages' `{{snippet}}` parser function accepts beginning and ending line numbers:
- `{{#snippet:repository=mediawiki/extensions/examples | filename=examples/ContentAction/ContentAction.php |startline=24 |endline=36}}`
- Could also/instead identify starting and ending blocks; this would require developers to use annotations like `// begin name=simple-text-field`annotate files in git with something like `// begin name=`//simple-text-field// ... `// end name=`//simple-text-field// , and then in the parser tag wiki editors specify `{{#snippet: ... `// end name=|section=`//simple-text -field`//` }}
Probable non-features:
- Create sets of pages -- if you want that, probably publish HTML to http://doc.wikimedia.org
=== Prior art
- [[ https://www.mediawiki.org/wiki/Extension:Git2Pages | Extension:Git2Pages]] - execs `git clone` and other commands to create local files
- [[ https://www.mediawiki.org/wiki/Extension:GitHub | Extension:GitHub]] - issues API requests to https://raw.githubusercontent.com to get files. Pulls in 12,000 lines of composer libraries.
- https://www.mediawiki.org/wiki/Special:ApiHelp/query categoryinfo (transcludable)
- [[ https://www.mediawiki.org/wiki/Extension:Include | Extension:Include ]] - primitive single-file PHP extension simply issues `file_get_contents()` of a URI.
- [[ https://www.mediawiki.org/wiki/Requests_for_comment/Documentation_overhaul#Extension:DocBrowser | Extension:DocBrowser]] from documentation overhaul RFC??
== Information for #Possible-Tech-Projects
* Primary mentor: @Spage
* Co-mentor: @tgr
* Other mentors: @Ankitashukla //(optional, Phabricator username)//
* Skills: PHP, Git; familiarity with MediaWiki extensions helps but can be picked up on the go
* Estimated project time for a senior contributor: //(must be 2-3 weeks)// OK it's 2-3 weeks :-)
* Microtasks: {T114719}, {T115388} //(pick one or request another)//
== See also ==
* {T90432}