[doc] describe development environment

[erikbgithub]

Problem

The current contributing.rst is merely a list of dos and don'ts. Neither does anybody want to read that nor does it really tell people how to develop for MONK. I feel that this page should mostly be a guide going step by step through installing the system requirements, creating the development environment, running the test suite and making a little change to MONK. Only in the end should be the rules and details for people who want to dive in more deeply or iif the team needs some arguments for decision making. But those cases are rare.

Solution

Create tutorial with git, virtualenv, test suite and use this issue as example for making a change to MONK.

Notes

• For reviewers:

  • the spell checking will be done after @toang is back from her holidays

  • to close this task you need to build the docs without warnings and errors with

    # somewhere in your filesystem
    somewhere$ git clone -b f-docs-devenv git@github.com:DFE/MONK
    somewhere$ cd MONK
    MONK$ virtualenv .
    MONK$ . bin/activate
    (MONK)MONK$ pip install sphinx
    ...
    (MONK)MONK$ python setup.py develop
    ...
    (MONK)MONK$ cd doc
    (MONK)doc$ make html
    (MONK)doc$ chromium-browser build/html/contributing.html
    # read if you can understand it in most cases -> ACK
    (MONK)doc$ deactivate
    doc$
    

• changes will be added with f-docs-devenv

[erikbgithub]

Changed the topic to reflect the real problem. It's mostly not about adding more lists with even more information. It's about giving the new user a guided tour through the dev process, that he can start to work more efficiently.

[erikbgithub]

can be reviewed.

[binschek]

"make html" does not work. 👎

(MONK)[binschek@cd-400-548 doc]$ make html
rm -rf build/html/*
rm -rf source/monk_tf.rst
rm -rf source/modules.rst
sphinx-apidoc -o source ../src/monk_tf
../src/monk_tf is not a directory.
make: *** [apidoc] Error 1
(MONK)[binschek@cd-400-548 doc]$ 

[binschek]

ACK

[DfePeterWinkler]

ACK