There are one to two main branches of the bot:
- The master code is implemented at https://tools.wmflabs.org/citations/, and is intended for public use.
- When needed, the development branch is intended for major restructuring and testing, and is implemented at https://tools.wmflabs.org/citations-dev/ .
This is some basic documentation about what this bot is and how some of the parts connect.
This is more properly a bot-gadget-tool combination. The parts are:
- DOIBot, found in index.html (web frontend) and process_page.php (information is POSTed to this and it does the citation expansion; backend). This automatically posts a new page revision with expanded citations and thus requires a bot account. All activity takes place on Tool Labs.
- Citation expander (:en:Mediawiki:Gadget-citations.js) + gadgetapi.php. This is comprises an Ajax front-end in the on-wiki gadget and a PHP backend API.
- Generate template creates the wiki reference given an identifier (for example given a doi: https://tools.wmflabs.org/citations/generate_template.php?doi=10.1109/SCAM.2013.6648183)
Bugs and requested changes are listed here: https://en.wikipedia.org/wiki/User_talk:Citation_bot .
Basic structure of a Citation bot script:
- define configuration constants
- require
setup.php
, which will set up the rest of the needed functions - use Page functions to fetch/expand/post the page's text
A quick tour of the main files:
constants.php
: constants definedWikipediaBot.php
: functions to facilitate HTTP access to the Wikipedia API.DOItools.php
: defines text/name functionssetup.php
: sets up needed functions, requires most of the other files listed hereexpandFns.php
: a variety of functionsapiFunctions.php
: sets up needed functions for expanding pmid/doi/etc
Class files:
Page.php
: Represents an individual page to expand citations on. Key methods arePage::get_text_from()
,Page::expand_text()
, andPage::write()
.Template.php
: most of the actual expansion happens here.Template::add_if_new()
is generally (but not always) used to add parameters to the updated template;Template::tidy()
cleans up the template, but may add parameters as well and have side effects.Comment.php
: Handles comments, nokwiki, etc. tagsParameter.php
: contains information about template parameter names, values, and metadata, and methods to parse template parameters.
Constants and definitions should be provided in constants.php
.
Classes should be in individual files. The code is generally written densely.
Beware assignments in conditionals, one-line if
/foreach
/else
statements,
and action taking place through method calls that take place in assignments or equality checks.
Also beware the difference between else if
and elseif
.
The bot requires PHP >= 5.6.
To run the bot from a new environment, you will need to create an env.php
file (if one doesn't already exist) that sets the needed authentication tokens as environment variables. To do this, you can rename env.php.example
to env.php
, set the variables in the file, and then make sure the file is not world readable or writable:
chmod o-rwx env.php
To run the bot as a webservice from WMF Tool Forge:
become citations[-dev]
webservice stop
webservice --backend=kubernetes start
Or for testing in the shell:
webservice --backend=kubernetes shell
Before entering the k8s shell, it may be necessary to install phpunit (as wget is not available in the k8s shell):
wget https://phar.phpunit.de/phpunit-5.phar
webservice --backend=kubernetes shell
php phpunit-5.phar --bootstrap setup.php tests/phpunit/TemplateTest.php
The bot accesses an instance of the Zotero translation server.
This can be updated by maintainers logging on to Toolforge, then entering the commands
become translation-server
npm update
webservice restart