From 5c0eb246d468454de9e84dca0d08c813459a5a6d Mon Sep 17 00:00:00 2001 From: kali Date: Wed, 19 Dec 2012 07:45:02 +0900 Subject: documentation update! reSTructured (no pun intended) the sphinx docs, and trimmed README --- docs/dev/authors.rst | 0 docs/dev/environment.rst | 59 +++++++++++++++++++++++++++++++++++++ docs/dev/internals.rst | 12 ++++++++ docs/dev/internationalization.rst | 27 +++++++++++++++++ docs/dev/resources.rst | 14 +++++++++ docs/dev/tests.rst | 62 +++++++++++++++++++++++++++++++++++++++ docs/dev/todo.rst | 0 docs/dev/workflow.rst | 8 +++++ 8 files changed, 182 insertions(+) create mode 100644 docs/dev/authors.rst create mode 100644 docs/dev/environment.rst create mode 100644 docs/dev/internals.rst create mode 100644 docs/dev/internationalization.rst create mode 100644 docs/dev/resources.rst create mode 100644 docs/dev/tests.rst create mode 100644 docs/dev/todo.rst create mode 100644 docs/dev/workflow.rst (limited to 'docs/dev') diff --git a/docs/dev/authors.rst b/docs/dev/authors.rst new file mode 100644 index 00000000..e69de29b diff --git a/docs/dev/environment.rst b/docs/dev/environment.rst new file mode 100644 index 00000000..7eafcdea --- /dev/null +++ b/docs/dev/environment.rst @@ -0,0 +1,59 @@ +.. _environment: + +Setting up a Work Environment +============================== + +This document covers how to get an enviroment ready to contribute code to the LEAP Client. + +Base Dependencies +------------------ +Leap client depends on these libraries: + +* `python 2.6 or 2.7` +* `qt4` libraries (see also :ref:`Troubleshooting PyQt install ` about how to install inside your virtualenv) +* `libgnutls` +* `openvpn` + +.. _virtualenv: + +Working with virtualenv +----------------------- + +Intro to virtualenv +^^^^^^^^^^^^^^^^^^^ +Virtualenv blah blah + +Install python dependencies +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +You can install python dependencies with pip:: + + $ apt-get install python-pip python-dev libgnutls-dev + $ pip install -r pkg/requirements.pip + +.. _pyqtvirtualenv: + +Troubleshooting PyQt install inside a virtualenv +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +If you attempt to install PyQt inside a virtualenv using pip, it will fail because PyQt4 does not use the standard setup.py mechanism. + +As a workaround, you can run the following script after creating your virtualenv. It will symlink to your global PyQt installation (`this is the recommended way if you are running a debian-based system`):: + + $ pkg/postmkvenv.sh + +A second option if that does not work for you would be to install PyQt globally and pass the `--site-packages` option when you are creating your virtualenv:: + + $ apt-get install python-qt4 + $ virtualenv --site-packages . + +Or, if you prefer, you can also download the official PyQt tarball and execute `configure.py` in the root folder of their distribution, which generates a `Makefile`:: + + $ python configure.py + $ make && make install + + +Cloning the repo +---------------- + +`XXX` diff --git a/docs/dev/internals.rst b/docs/dev/internals.rst new file mode 100644 index 00000000..8bb19211 --- /dev/null +++ b/docs/dev/internals.rst @@ -0,0 +1,12 @@ +.. _internals: + +Internals +========= + +This section covers briefly the internal organization of the LEAP Client source tree. + +.. note:: + + very unfinished. + +`TBD` diff --git a/docs/dev/internationalization.rst b/docs/dev/internationalization.rst new file mode 100644 index 00000000..4e75739b --- /dev/null +++ b/docs/dev/internationalization.rst @@ -0,0 +1,27 @@ +.. _i18n: + +Internationalization +==================== + +This part of the documentation covers the localization and translation of LEAP Client. +Because we want to *bring fire to the people*, in as many countries and languages as possible. + +.. note:: + We should probably move the translators info to a top level section of the docs, and leave this + as internal/tech-savvy notes. + +Translate the Qt App +-------------------- + +.. note:: + ... unfinished + +`transifex `_ + +Translate the Documentation +--------------------------- + +.. note:: + ...unfinished + +`translating sphinx docs `_ diff --git a/docs/dev/resources.rst b/docs/dev/resources.rst new file mode 100644 index 00000000..7cfa2b70 --- /dev/null +++ b/docs/dev/resources.rst @@ -0,0 +1,14 @@ +.. _resources: + +PyQt Resource files +=================== + +Compiling resource/ui files +--------------------------- + +You should refresh resource/ui files every time you change an image or a resource/ui (.ui / .qc). From the root folder:: + + % make ui + % make resources + +As there are some tests to guard against unwanted resource updates, you will have to update the resource hash in those failing tests. diff --git a/docs/dev/tests.rst b/docs/dev/tests.rst new file mode 100644 index 00000000..7f5fbaaf --- /dev/null +++ b/docs/dev/tests.rst @@ -0,0 +1,62 @@ +.. _tests: + +Running and writing tests +========================= + +.. note:: + should include seeAlso to virtualenv + +This section covers the documentation about the tests for the LEAP Client code. +All patches should have tests for them ... + + +Testing dependencies +-------------------- + +have a look at ``pkg/test-requirements.pip`` +The ``./run_tests.sh`` command should install all of them in your virtualenv for you. + +If you prefer to install them system wide, this should do in a debian system:: + + $ apt-get install python-nose python-mock python-coverage + + +Running tests +------------- + +There is a convenience script at ``./run_tests.sh`` + +If you want to run specific tests, pass the (sub)module to nose:: + + $ nosetests leap.util + +or:: + + $ nosetests leap.util.tests.test_leap_argparse + +Hint: colorized output +^^^^^^^^^^^^^^^^^^^^^^ + +Install ``rednose`` locally, export the ``NOSE_REDNOSE`` variable, and give your eyes a rest :):: + + (leap_client)% pip install rednose + (leap_client)% export NOSE_REDNOSE=1 + +Testing all the supported python versions +----------------------------------------- + +For running testsuite against all the supported python versions (currently 2.6 and 2.7), run:: + + % tox -v + +Coverage reports +---------------- + +Pass the ``-c`` flat to the ``run_tests.sh`` script:: + + $ run_tests.sh -c + +Using ``coverage`` it will generate beautiful html reports that you can access pointing your browser to ``docs/covhtml/index.html`` + +.. note:: + The coverage reports will not be generated if all tests are not passing. diff --git a/docs/dev/todo.rst b/docs/dev/todo.rst new file mode 100644 index 00000000..e69de29b diff --git a/docs/dev/workflow.rst b/docs/dev/workflow.rst new file mode 100644 index 00000000..3f773712 --- /dev/null +++ b/docs/dev/workflow.rst @@ -0,0 +1,8 @@ +.. _workflow: + +Development Workflow +==================== + +This section documents the workflow that the LEAP project team follows and expects for the code contributions. + +XXX -- cgit v1.2.3