Use :linenos: for examples in defaults/main.yml to mark them as examples.

[ypid]

@drybjed noted that giving examples in defaults/main.yml can be confusing because in the rendered output, their markup looks exactly the same as the default value. Proposed fix:

Use :linenos: for examples causing them to be rendered with line numbers. Consider:

# .. envvar:: owncloud__run_occ_global_commands
#
# Global list of :command:`occ` commands to run.
# It can be used to enable apps, add users and more which can be useful when
# deploying ownCloud.
#
# Refer to the `official ownCloud Dokumentation <https://doc.owncloud.org/server/9.0/admin_manual/configuration_server/occ_command.html>`__ for details.
#
# Examples:
#
# .. code-block:: yaml
#   :linenos:
#
#   owncloud__run_occ_global_commands
#
#     ## Requires: php5-ldap
#     - command: 'app:enable user_ldap'
#
#     - command: 'app:enable external'
#
#     ## Requires: php5-libsmbclient
#     - command: 'app:enable files_external'
#
#     ## Create an additional admin account.
#     - command: 'user:add --password-from-env --display-name="Administrator" --group="admin" admin'
#       ## Does not work with ownCloud 8.0 or below so don’t run it there.
#       when: '{{ owncloud__release | version_compare("8.1", ">=") }}'
#       env:
#         OC_PASS: "{{ lookup('password', secret + '/credentials/' +
#                      ansible_fqdn + '/owncloud/admin/' + 'admin' +
#                      '/password length=' + owncloud__password_length) }}"
#
#     ## Create an regular user. Note that you probably want to use an existing
#     ## user database like LDAP.
#     - command: 'user:add --password-from-env --display-name="Normal user" user'
#       when: '{{ owncloud__release | version_compare("8.1", ">=") }}'
#       env:
#         OC_PASS: "{{ lookup('password', secret + '/credentials/' +
#                      ansible_fqdn + '/owncloud/users/' + 'user' +
#                      '/password length=' + owncloud__password_length) }}"
#
owncloud__run_occ_global_commands:
  ## Disable the updater because it does not work anyway with the way ownCloud
  ## is setup by this role using packages.
  ## Since ownCloud 9 it is called `updatenotification`.
  - command: 'app:disable updater'
    when: '{{ owncloud__release | version_compare("8.2", "<=") }}'

  # - command: 'app:disable documents'
  #   when: '{{ not owncloud__app_documents_enabled|bool }}'

Which renders to:

[drybjed]

Adding line numbers sounds like a good idea. With the above example, I would reorder it so that there's some text between the example and the "normal' code, it would probably be a better context "flow":

# .. envvar:: owncloud__run_occ_global_commands
#
# Global list of :command:`occ` commands to run.
# It can be used to enable apps, add users and more which can be useful when
# deploying ownCloud.
#
# Examples:
#
# .. code-block:: yaml
#   :linenos:
#
#   owncloud__run_occ_global_commands
#
#     ## Requires: php5-ldap
#     - command: 'app:enable user_ldap'
#
#     - command: 'app:enable external'
#
#     ## Requires: php5-libsmbclient
#     - command: 'app:enable files_external'
#
#     ## Create an additional admin account.
#     - command: 'user:add --password-from-env --display-name="Administrator" --group="admin" admin'
#       ## Does not work with ownCloud 8.0 or below so don’t run it there.
#       when: '{{ owncloud__release | version_compare("8.1", ">=") }}'
#       env:
#         OC_PASS: "{{ lookup('password', secret + '/credentials/' +
#                      ansible_fqdn + '/owncloud/admin/' + 'admin' +
#                      '/password length=' + owncloud__password_length) }}"
#
#     ## Create an regular user. Note that you probably want to use an existing
#     ## user database like LDAP.
#     - command: 'user:add --password-from-env --display-name="Normal user" user'
#       when: '{{ owncloud__release | version_compare("8.1", ">=") }}'
#       env:
#         OC_PASS: "{{ lookup('password', secret + '/credentials/' +
#                      ansible_fqdn + '/owncloud/users/' + 'user' +
#                      '/password length=' + owncloud__password_length) }}"
#
# Refer to the `official ownCloud Dokumentation <https://doc.owncloud.org/server/9.0/admin_manual/configuration_server/occ_command.html>`__ for details.
#
owncloud__run_occ_global_commands:
  ## Disable the updater because it does not work anyway with the way ownCloud
  ## is setup by this role using packages.
  ## Since ownCloud 9 it is called `updatenotification`.
  - command: 'app:disable updater'
    when: '{{ owncloud__release | version_compare("8.2", "<=") }}'

  # - command: 'app:disable documents'
  #   when: '{{ not owncloud__app_documents_enabled|bool }}'

[ypid]

With the above example, I would reorder it so that there's some text between the example and the "normal' code, it would probably be a better context "flow":

Thanks for mentioning it. You are right. My example was not the best as is I agree that adding some text is good practice which I follow for new examples.