Vagrant

Minimal setup

This extension uses Mediawiki-Vagrant, and a complete setup can be made quite easily.

  1. Make sure you have Vagrant, etc, prepare a development directory, and move to that directory.
  2. Clone Mediawiki
git clone --recursive https://gerrit.wikimedia.org/r/mediawiki/vagrant .

3. Run setup.

./setup.sh

4. Enable the role for ModDoc. (See section “Role installation”.) This pulls inn the role for Scribunto, which pulls in additional roles.

vagrant roles enable moddoc

5. Start the instance.

vagrant up

6. Done.

This should create a working environment with phpmd, phpcs, and phpunit. An actual call would be composer unit. See scripts in composer.json for all calls.

Role installation

If the role is missing, that is puppet/modules/role/manifests/moddoc.pp can not be found, then create the files

# == Class: role::moddoc
# The ModDoc extension provides functionality to make human
# readable documentation for Lua modules, that is the Scribunto extension.
# Such documentation can be reused through a parser function.
class role::moddoc {
    include ::role::scribunto

    mediawiki::extension { 'ModDoc':
        remote   => 'https://github.com/jeblad/ModDoc.git',
        require  => Mediawiki::Extension['Scribunto'],
        composer => true,
    }

    mediawiki::import::text { 'VagrantRoleModDoc':
        source => 'puppet:///modules/role/moddoc/VagrantRoleModDoc.wiki',
    }
}

as puppet/modules/role/manifests/moddoc.pp, and

'''ModDoc''' is an extension that provides code documentation for Lua modules. This makes it possible to document code in a standardized reference format, to facilitate interactive and collaborative programming.

For a full Vagrant setup, see [https://jeblad.github.io/ModDoc/topics/vagrant.md.html the documentation].

== See also ==

* [[mw:Extension:ModDoc]] (Information)
* [[mw:Extension:ModDoc/Glossary]] (Terms and concepts)
* [https://github.com/jeblad/ModDoc Github: jeblad/ModDoc] (Code repository)
* [https://jeblad.github.io/ModDoc/ Jeblad: ModDoc] (Lua documentation)
* [https://translatewiki.net/wiki/Special:Translate/mwgithub-moddoc Translatewiki: mwgithub-moddoc] (Localization)

as puppet/modules/role/files/moddoc/VagrantRoleModDoc.wiki

Extended setup

Luarocks and ldoc

It is necessary to install luarocks and a few libs to recreate the generated docs.

  1. Install luarocks. This will pull in several additional packages, the most important is lua5.1.
sudo apt install luarocks

2. Install ldoc. This will pull in several additional packages, like penlight, markdown, and luafilesystem.

sudo luarocks install ldoc

3. Done.

This should make a working ldoc. An actual call would be composer ldoc.

Import of pages

A few pages for testing can be imported in the new instance.

  1. Open a terminal at the new Vagrant instance
vagrant ssh

2. Go to the ModDoc folder and import the pages.

cd /vagrant/mediawiki/extensions/ModDoc
composer import

3. Go to the mediawiki root, rebuild recent changes, and rebuild site stats.

cd /vagrant/mediawiki
php maintenance/rebuildrecentchanges.php
php maintenance/initSiteStats.php --update

4. Done

Resource allocations

Vagrant resources

It could be interesting to adjust the amount of memory and number of CPU cores used during testing. Such resource allocations are described on mw:MediaWiki-Vagrant#Adjust the resources allocated to the VM? Especially note the code snippet for ~/picklespace/Vagrantfile-extra.rb.

Vagrant.configure('2') do |config|
  config.vm.provider :virtualbox do |vb|
    # See http://www.virtualbox.org/manual/ch08.html for additional options.
    vb.customize ['modifyvm', :id, '--memory', '1536']
    vb.customize ['modifyvm', :id, '--cpus', '2']
  end
end

To restart the instance do vagrant reload.

If the memory is too low, then the test run in guest will end in a fork failed. When that happen, increase the memory until the test runs ok. With fastest it should be sufficient to set this around “1024”, and “1536” is enough. If it is set to high, then it seems like the test runs take more time. This could be due to garbage collection.

If the number of CPUs are increased beyond the actual number of cores, an increase in run time might be observed. When that happen, decrease the number of CPUs available to the vagrant instance.

Composer resources

There can be timeouts in the Vagrant guest instance during composer runs. To adjust for the increased time do something like

vagrant ssh
composer config --global process-timeout 900
generated by LDoc TESTING