documentation finished, tox command to build it, badge in README.rst

README.rst

@@ -4,6 +4,9 @@
 .. image:: https://img.shields.io/pypi/pyversions/pytest-logger.svg
     :target: https://pypi.python.org/pypi/pytest-logger
     :alt: Supported Python Versions
+.. image:: https://readthedocs.org/projects/pytest-logger/badge
+    :target: http://pytest-logger.readthedocs.io/en/latest
+    :alt: Documentation Status
 .. image:: https://coveralls.io/repos/github/aurzenligl/pytest-logger/badge.svg?branch=master
     :target: https://coveralls.io/github/aurzenligl/pytest-logger?branch=master
     :alt: Coverage Status
@@ -75,20 +78,20 @@ and expect output in terminal (if not captured)::
     $ py.test -s -v
     (...)
     test_something.py::test_one
-    00:00.001 foo: constructing session thing
-    00:00.001 foo: constructing testcase thing
-    00:00.002 foo: one executes
-    00:00.002 bar: this test does nothing aside from logging
+    00:00.001 inf foo: constructing session thing
+    00:00.001 inf foo: constructing testcase thing
+    00:00.002 inf foo: one executes
+    00:00.002 wrn bar: this test does nothing aside from logging
     PASSED
-    00:00.002 foo: destroying testcase thing
+    00:00.002 inf foo: destroying testcase thing
 
     test_something.py::test_two
-    00:00.000 foo: constructing testcase thing
-    00:00.000 foo: two executes
-    00:00.000 bar: neither does this
+    00:00.000 inf foo: constructing testcase thing
+    00:00.000 inf foo: two executes
+    00:00.000 wrn bar: neither does this
     PASSED
-    00:00.000 foo: destroying testcase thing
-    00:00.001 foo: destroying session thing
+    00:00.001 inf foo: destroying testcase thing
+    00:00.001 inf foo: destroying session thing
     (...)
 
 and - the same - in filesystem::

docs/index.rst

@@ -1,12 +1,15 @@
 pytest-logger
 ===================================
 
-The pytest-logger is a pytest plugin which handles logs emitted
-with Python's logging module. Logs are output to terminal or files
+The pytest-logger is a `pytest`_ plugin which handles logs emitted
+by Python's `logging`_ module. Logs are output to terminal or files
 in configurable manner.
 
 .. toctree::
    :maxdepth: 2
 
    overview
    usage
+
+.. _`pytest`: http://docs.pytest.org
+.. _`logging`: https://docs.python.org/2/library/logging.html

docs/overview.rst

@@ -1,4 +1,51 @@
 Overview
 ===================================
 
-todo
+Installation
+--------------------
+
+As simple as::
+
+	$ [sudo] pip install pytest-logger
+
+Project is hosted on github:
+
+	https://github.com/aurzenligl/pytest-logger
+
+Rationale
+--------------------
+
+I work with C++ application which logs copiously on its own and has multiple interfaces on which
+interesting events occur. Getting all this information as separate files in directory tree
+or filtered real-time logs proves to be invaluable in testing.
+
+Unfortunately, contemporary state of pytest and plugins doesn't allow to do this out-of-the-box:
+
+	- real-time output to terminal which doesn't mix with regular pytest output ('-v' or not)
+	- possibility to enable and set levels on per logger basis
+	- test session logs persistent in filesystem and partitioned in fine-grained manner
+	  (per testcase and per logger)
+
+Above problems require reacting on events such as session start, test start/teardown
+and inspecting some data stored by framework, e.g. test locations/names. This requires
+writing pytest plugin.
+
+Plugin has a hook API, which means that if user doesn't implement hooks, nothing happens,
+and if he does - any cmdline options and logging configuration logic may be envisioned.
+
+Contributing
+--------------------
+
+Contibutions are welcome!
+
+If you:
+
+    - find a bug in plugin,
+    - find important features missing,
+    - want to propose a new feature,
+    - or just like it,
+
+please write to `github issues`_ or let me know `via email`_.
+
+.. _`github issues`: https://github.com/aurzenligl/pytest-logger/issues
+.. _`via email`: https://github.com/aurzenligl

docs/usage.rst

@@ -31,6 +31,24 @@ File output is stored in logs directory (see `logs dir layout`_ and `link to log
 - see :py:meth:`LoggerHookspec.pytest_logger_stdoutloggers`
 - see :py:meth:`LoggerHookspec.pytest_logger_fileloggers`
 
+Things to note:
+
+    - **stdout capturing:** in order to see logs printed on terminal in real time
+      during test execution, you need to disable output capturing by ``-s`` switch.
+    - **default root level:** by default root logger (and all its children)
+      has warning level threshold set. This can filter logs regardless of handler levels
+      user gives via hooks. Be sure to set root logger level as NOTSET if you
+      don't want this to happen.
+    - **no handlers warning:** if log wouldn't get filtered, but there are no handlers
+      added to logger, `unwanted message`_ is printed. Add `NullHandler`_
+      to such loggers.
+    - **default logging config:** if root logger has no handlers, using module level
+      logging functions will setup basic logging config. It makes no sense in combintion
+      with this plugin. Be sure root logger has some handler (at least `NullHandler`_)
+      or just don't use these functions.
+    - **pytest-xdist:** stdout output is not printed to terminal in `pytest-xdist`_ runs.
+      File output works as in single process mode.
+
 .. _`logs dir layout`:
 
 The logs directory layout
@@ -120,6 +138,9 @@ API reference
               pytest_logger_logdirlink
 
 .. _`conftest.py`: http://docs.pytest.org/en/latest/writing_plugins.html#conftest-py
+.. _`unwanted message`: https://docs.python.org/2/howto/logging.html#what-happens-if-no-configuration-is-provided
+.. _`NullHandler`: https://docs.python.org/2/library/logging.handlers.html#logging.NullHandler
+.. _`pytest-xdist`: https://pypi.python.org/pypi/pytest-xdist
 .. _`basetemp`: http://doc.pytest.org/en/latest/tmpdir.html#the-default-base-temporary-directory
 .. _`nodeid`: http://docs.pytest.org/en/latest/writing_plugins.html#_pytest.main.Node.nodeid
 .. _`tmpdir`: http://docs.pytest.org/en/latest/tmpdir.html#the-tmpdir-fixture

tox.ini

@@ -1,7 +1,8 @@
 [tox]
 envlist =
     check,
-    {py27,py34,py35,pypy}-pytest{29,30}
+    {py27,py34,py35,pypy}-pytest{29,30},
+    docs
 
 [testenv]
 deps =
@@ -35,3 +36,11 @@ commands=
     coverage run --source=pytest_logger -m pytest tests
     coverage report -m
     sh -c 'if [ $COVERALLS_REPO_TOKEN ]; then coveralls; fi'
+
+[testenv:docs]
+changedir=docs
+deps=
+    sphinx
+    sphinx_rtd_theme
+commands=
+    sphinx-build -W -b html . _build