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
Merge pull request #995 from karlcow/master

Fixing documentation according to  Issue #362.