Merge branch 'flv0-contributing-toxhelp'

CONTRIBUTING.asciidoc

@@ -89,21 +89,39 @@ Checkers
 qutebrowser uses http://tox.readthedocs.org/en/latest/[tox] to run its
 unittests and several linters/checkers.
 
-Currently, the following tools will be invoked when you run `tox`:
+Currently, following tox environments are available:
 
-* Unit tests using https://www.pytest.org[pytest].
+* Tests using https://www.pytest.org[pytest]:
-* https://pypi.python.org/pypi/pyflakes[pyflakes] via https://pypi.python.org/pypi/pytest-flakes[pytest-flakes]
+  - `py34`: Run pytest for python-3.4.
-* https://pypi.python.org/pypi/pep8[pep8] via https://pypi.python.org/pypi/pytest-pep8[pytest-pep8]
+  - `py35`: Run pytest for python-3.5.
-* https://pypi.python.org/pypi/mccabe[mccabe] via https://pypi.python.org/pypi/pytest-mccabe[pytest-mccabe]
+  - `py34-cov`: Run pytest for python-3.4 with code coverage report.
-* https://github.com/GreenSteam/pep257/[pep257]
+  - `py35-cov`: Run pytest for python-3.4 with code coverage report.
-* http://pylint.org/[pylint]
+* `flake8`: Run https://pypi.python.org/pypi/flake8[flake8] checks:
-* https://pypi.python.org/pypi/pyroma/[pyroma]
+                https://pypi.python.org/pypi/pyflakes[pyflakes],
-* https://github.com/mgedmin/check-manifest[check-manifest]
+                https://pypi.python.org/pypi/pep8[pep8],
-* `scripts/misc_checks.py` which checks for the following things:
+                https://pypi.python.org/pypi/mccabe[mccabe]
+* `vulture`: Run https://pypi.python.org/pypi/vulture[vulture] to find
+  unused code portions.
+* `pylint`: Run http://pylint.org/[pylint] static code analysis.
+* `pydocstyle`: Check
+  https://www.python.org/dev/peps/pep-0257/[PEP257] compliance with
+  https://github.com/PyCQA/pydocstyle[pydocstyle]
+* `pyroma`: Check packaging practices with
+  https://pypi.python.org/pypi/pyroma/[pyroma]
+* `eslint`: Run http://eslint.org/[ESLint] javascript checker.
+* `check-manifest`: Check MANIFEST.in completeness with
+  https://github.com/mgedmin/check-manifest[check-manifest]
+* `mkvenv`: Bootstrap a virtualenv for testing.
+* `misc`: Run `scripts/misc_checks.py` to check for:
     - untracked git files
     - VCS conflict markers
+    - common spelling mistakes
+
+The default test suite is run with `tox`, the list of default
+environments is obtained with `tox -l` .
 
 Please make sure the checks run without any warnings on your new contributions.
+
 There's of course the possibility of false-positives, and the following
 techniques are useful to handle these:
 
@@ -122,6 +140,31 @@ smallest scope which makes sense. Most of the time, this will be line scope.
 * If you really think a check shouldn't be done globally as it yields a lot of
 false-positives, let me know! I'm still tweaking the parameters.
 
+
+Running Specific Tests
+~~~~~~~~~~~~~~~~~~~~~~
+
+While you are developing you often don't want to run the full test
+suite each time.
+
+Specific test environments can be run with `tox -e <envlist>`.
+
+Additional parameters can be passed to the test scripts by separating
+them from `tox` arguments with `--`.
+
+Examples:
+
+----
+# run only pytest tests which failed in last run:
+tox -e py35 -- --lf
+
+# run only the integration feature tests:
+tox -e py35 -- tests/integration/features
+
+# run everything with undo in the generated name, based on the scenario text
+tox -e py35 -- tests/integration/features/test_tabs.py -k undo
+----
+
 Profiling
 ~~~~~~~~~
 
@@ -246,22 +289,22 @@ When using Qt objects, two issues must be taken care of:
 * Methods of Qt objects report their status by using their return values,
 instead of using exceptions.
 +
-If a function gets or returns a Qt object which
+If a function gets or returns a Qt object which has an `.isValid()`
-has an `.isValid()` method such as `QUrl` or `QModelIndex`, there's a helper
+method such as `QUrl` or `QModelIndex`, there's a helper function
-function `ensure_valid` in `qutebrowser.utils.qt` which should get called on
+`ensure_valid` in `qutebrowser.utils.qtutils` which should get called
-all such objects. It will raise `qutebrowser.utils.qt.QtValueError` if the
+on all such objects. It will raise
-value is not valid.
+`qutebrowser.utils.qtutils.QtValueError` if the value is not valid.
 +
 If a function returns something else on error, the return value should
 carefully be checked.
 
-* Methods of Qt objects have certain maximum values, based on their underlying
+* Methods of Qt objects have certain maximum values, based on their
-C++ types.
+underlying C++ types.
 +
-When passing a numeric parameter to a Qt function, all numbers should be
+When passing a numeric parameter to a Qt function, all numbers should
-range-checked using `qutebrowser.utils.check_overflow`, or passing a value
+be range-checked using `qutebrowser.qtutils.check_overflow`, or
-which is too large should be avoided by other means (e.g. by setting a maximum
+passing a value which is too large should be avoided by other means
-value for a config object).
+(e.g. by setting a maximum value for a config object).
 
 [[object-registry]]
 The object registry
@@ -363,9 +406,9 @@ then gets passed as the `self` parameter to the handler. The `scope` argument
 selects which object registry (global, per-tab, etc.) to use.  See the
 <<object-registry,object registry>> section for details.
 
-There are also other arguments to customize the way the command is registered,
+There are also other arguments to customize the way the command is
-see the class documentation for `register` in `qutebrowser.commands.utils` for
+registered, see the class documentation for `register` in
-details.
+`qutebrowser.commands.cmdutils` for details.
 
 The types of the function arguments are inferred based on their default values,
 e.g. an argument `foo=True` will be converted to a flag `-f`/`--foo` in

README.asciidoc

@@ -151,8 +151,8 @@ Contributors, sorted by the number of commits in descending order:
 * Joel Torstensson
 * Felix Van der Jeugt
 * Claude
-* meles5
 * Patric Schmitz
+* meles5
 * Artur Shaik
 * Nathan Isom
 * Austin Anderson

doc/help/index.asciidoc

@@ -12,6 +12,7 @@ The following help pages are currently available:
 * link:commands.html[Documentation of commands]
 * link:settings.html[Documentation of settings]
 * link:userscripts.html[How to write userscripts]
+* link:CONTRIBUTING.html[Contributing to qutebrowser]
 
 Getting help
 ------------

scripts/asciidoc2html.py

@@ -43,6 +43,7 @@ class AsciiDoc:
     FILES = [
         ('FAQ.asciidoc', 'qutebrowser/html/doc/FAQ.html'),
         ('CHANGELOG.asciidoc', 'qutebrowser/html/doc/CHANGELOG.html'),
+        ('CONTRIBUTING.asciidoc', 'qutebrowser/html/doc/CONTRIBUTING.html'),
         ('doc/quickstart.asciidoc', 'qutebrowser/html/doc/quickstart.html'),
         ('doc/userscripts.asciidoc', 'qutebrowser/html/doc/userscripts.html'),
     ]