%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 clone
your 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_id
in the sources inauthors.yaml
.default_lang: en
influences thedoit
commands below.Create a folder (parallel to the existing
r
folder) 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.yaml
anddodo.py
):
doit -kd. new
will add a folder, then you would manually add the files
doit -kd. problem
adds a folder and__init__.py
and<default_lang>.html
, adden.html
and possibly others manually. Remove__init__.py
, if there is no code involved.
doit -kd. rst
adds a folder and<default_lang>.rst
. After editingdoit -kd. html
will convert rst files to html. Generated files start with a underscore. Sphinx generates e.g._en.html
fromen.rst
.
__init__.py
must provide the functionsgiven
andcalc
and optionallynorm
,equal
,points
andnames
(seefrom_py
inhlp.py
and examples in ther
-folder).
<lang>.html
is html and{{'{{}}'}}
-enclosed or%
-started python (SimpleTemplate) just for the one exercise. Also use the templategetorshow
as done in the examples in ther
-folder. The generated HTML will be enclosed in a<div>
(seeinc
inutil.py
).
<lang>.rst
can use the rolesinl
for inlining andlnk
to reference (seeinl.py
and 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
level
must 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 mamchecker
and 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. initdb
must be executed to generateinitdb.py
, which creates the content overview page. If you haverst
files, dodoit -kd. html
first.On your local command prompt in the mamchecker folder do
git status
git diff
git commit -am "what you did"
git push
to your github repository
There is a test script which you can start locally. In your command prompt where
dodo.py
is 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.