New features: rendering self-standing comments and key-value in docs

[erplus]

It would be nice to have consecutive features in this plugin:

1. self-standing comments (most important): rendering docs not only from comments found directly above a key. Seems there is no option to generate such text (i didn't find in examples).
2. key-value: rendering in docs not only key with comment but key and value with comment. There should be some kind of switch/mark as a choose if we want generateonly key or key and whole value in docs (for backward compability).

Examples of idea

1. self-standing comments
   yaml:

---
###
# mycomment
mykey: myvalue

###
# self-standing comment

otherkey: othervalue

rendered doc:

mykey

    mycomment

self-standing comment

2. key-value (4x# as delimiter, but i think there could be better options)
   yaml:

####
# rendered comment with key and value
key1:
  - key1: value
    ####
    # rendered nested comment with key and value
    key2:
      key3: value
  - value
    ###
    # rendered comment with key
  - key1: value
    key3: value
key2:
  key1: value
  key2: value

rendered doc:

key1:
  - key1: value
    key2:
      key3: value
  - value

    rendered comment with key and value

key2:
  key3: value

    rendered nested comment with key and value

key1

    rendered comment with key

I would like to to use autoyaml in my ansible projects, but currently rendering only comments next to key in yaml is not enough.

What do you think about these features?
@Jakski

[Jakski]

1. Comments are rendered as items in definition list. It makes a free-standing comments hard to implement. While it would be easy to insert them before or after definition list, it would break the way we display documentation, if they interleave. You can insert custom content in rst files before or after autoyaml directive to achieve heading/footer effect in your documentation.
2. Key with values embedded in documentation sounds good, e.g.: for default values in Ansible projects. This feature is not yet available here, but you can temporarily use https://github.com/Jakski/sphinxcontrib-lookup-yaml until it's implemented.