Fixing documentation according to  Issue #362.

The documentation as it is right now produces a  CRITICAL: 'article' is
undefined
Adding context to the documentation for metadata

Giving a longer description Thanks to justin mayer for #995
fixing the inline code markup
fix: clear directory before generation of context

fixes #927
Replace get_populated_generator with setUpClass
More refactoring for test_generators

- list comprehensions for distill_articles/pages
- distill articles only once
- pep8
Refactor pelican_open using contextmanager