%path = "participate" %kind = kinda["meta"] %level = 0
You need to know:
some HTML
some Python (with numpy and sympy)
possibly Javascript
basic understanding and working with the tools
If your are a little familiar with Linux, use it, possibly on a virtual machine
like virtualbox .
Then you can use git and other tools with less problems
(e.g. easy installation via package managers, symlinks supported,…).
But all the needed tools are also available for Windows and Mac.
Collaboration is done via github. Exercises contain Python code (also in the HTML templates), therefore handling them like code is appropriate. Reviews are necessary for safety reasons.
On your PC you will need
git (use msys git on Windows). Introduction
python with pip (Python 3 is not yet supported by Google Appengine)
doit (pip install doit)
pytest for testing (pip install pytest)
and optionally
sphinx if you want to use restructured text (rst)
(pip install sphinx).
latex (use miktex on Windows) for sphinx plugins (sphinxcontrib.tikz, sphinxcontrib.texfigure).
coverage (pip install coverage)
As browser Chrome has the best HTML5 support and a good debugging environment for Javascript.
For editing use your editor of choice. It should allow you to execute selected python code (pydev, vim).
Fork it on github.
Use your browser to create a fork of Mamchecker on github
On your local command prompt you
git cloneyour forked repository to a local folder (msys bash on Windows):git clone --recursive https://github.com/mamchecker/mamchecker.gitIf you didn’t use –recursive you have to additionally do git submodule update –init –recursive).
Add yourself as author.
Register yourself with an
author_idin the sources inauthors.yaml.default_lang: eninfluences thedoitcommands below.Create a folder (parallel to the existing
rfolder) named with your author id.
Add exercises. To see how easy that is, look at the examples in the existing r folder.
Add a folder in your authors folder and populate it with
__init__.py,en.html, … then edit. To do this usedoit; it generates the next id and uses it to create a folder (seenextids.yamlanddodo.py):
doit -kd. newwill add a folder, then you would manually add the files
doit -kd. problemadds a folder and__init__.pyand<default_lang>.html, adden.htmland possibly others manually. Remove__init__.py, if there is no code involved.
doit -kd. rstadds a folder and<default_lang>.rst. After editingdoit -kd. htmlwill convert rst files to html. Generated files start with a underscore. Sphinx generates e.g._en.htmlfromen.rst.
__init__.pymust provide the functionsgivenandcalcand optionallynorm,equal,pointsandnames(seefrom_pyinhlp.pyand examples in ther-folder).
<lang>.htmlis html and{{'{{}}'}}-enclosed or%-started python (SimpleTemplate) just for the one exercise. Also use the templategetorshowas done in the examples in ther-folder. The generated HTML will be enclosed in a<div>(seeincinutil.py).
<lang>.rstcan use the rolesinlfor inlining andlnkto reference (seeinl.pyand look for examples in ther-folder).At the beginning of the language file have the following lines, where
<kind>is one the language specific kind strings inkind.py
levelmust be last and means years starting from elementary school (1, 2, …)
- for
<lang>.rst:: .. raw:: html%path = “path/to/create/a/hierarchical/order”%kind = kinda[“<kind>”]%level = 0<!– html –>.. role:: asis(raw):format: html latex- for
<lang>.html:: %path = “path/to/create/a/hierarchical/order”%kind = kinda[“<kind>”]%level = 9From above the mamchecker folder (where app.yaml is) do
dev_appserver mamcheckerand test your exercise on the browser (http://localhost:8080/en/?<yourid>.<problemid>). Check different nonsense, almost correct and correct inputs.
Ready for commit.
doit -kd. initdbmust be executed to generateinitdb.py, which creates the content overview page. If you haverstfiles, dodoit -kd. htmlfirst.On your local command prompt in the mamchecker folder do
git status
git diff
git commit -am "what you did"
git pushto your github repository
There is a test script which you can start locally. In your command prompt where
dodo.pyis do:
doit test.This tests more than is needed, if you only added an exercise. But do it, if you have made other changes in code.
Add your contribution to the main repository.
In the browser you create a pull request. This way all contributions come together.