module.run documentation issues

[boltronics]

Description of Issue/Question

According to https://docs.saltstack.com/en/latest/ref/states/all/salt.states.module.html#module-salt.states.module the new module.run syntax is:

fetch_out_of_band:
  module.run:
    git.fetch:
      - cwd: /path/to/my/repo
      - user: myuser
      - opts: '--all'

This example is incorrect. It should read:

fetch_out_of_band:
  module.run:
    - git.fetch:
      - cwd: /path/to/my/repo
      - user: myuser
      - opts: '--all'

All the other examples on that page also have the same error, which I found quite confusing.

That entire section doesn't read very well, as the old and new syntax formats are mixed together. It would be clearer if it was broken into sections with separate headings such as "The new way" and "The old way (supported until Oxygen)". It would also allow anyone new to module.run to simply skip the section on the old format.

Finally, I'd like to see a more complicated example. eg.

Remove appserver server from HAProxy host:
  module.run:
    - publish.publish:
      - tgt: 'rproxy*'
      - fun: haproxy_cmds.disable_server
      - arg: >-
          [
          'server=appserver',
          'backend=bk_appservers'
          ]
    - require_in:
      - git: Deploy code
    - onchanges_in:
      - module: Add appserver server to HAProxy host

I tried experimenting with a YAML list for arg, but it didn't work. This might save someone time.

Setup

N/A

Steps to Reproduce Issue

N/A

Versions Report

Applicable to the documentation in 2017.7.0+.

[Ch3LL]

@boltronics I don't think the new module.run is set by default. If i recall correctly to use the new syntax you would need to add an additional argument to your config. Is this accurate from your setup?

I completely agree we should add some examples to these docs for the new syntax but i don't think we want to do a clear removal of the old syntax because its still applicable i believe.

[boltronics]

@Ch3LL That is correct. I have added the documented use_superseded argument to my config.

I didn't mean to imply that the old syntax should be removed. I just think it's not very clear at a glance which examples are using which syntax, and it would be more readable if the two different approaches were split out under separate sub-headings or some such.

In case it wasn't clear, both are currently documented on that page to some degree.

[epcim]

This should be closed I guess.

[boltronics]

The examples are fixed, but it's still not as clear as it could/should be IMO.

For example, the first four examples use the new syntax. Then the documentation switches to giving an example of the old way. Initially the reader would think it's just a quick one-off example of something they don't really need to care about, but then it goes on for another five additional examples. At this point, the docs read "Another option is to use the new version of module.run" and give one final example using the new format again.

So it comes off as unclear which the user should use. On one hand the new format is introduced first, but then the old format is discussed so much that it could easily give rise to some doubts. The fact that the new format requires a configuration file change to work doesn't help matters.

Additionally the use_superseded syntax is documented right at the end - after spending so much time talking about the old format. I imagine some readers would get half way through and think "the rest of this document doesn't apply to me - I'm using the new format" and completely miss that little minion configuration section at the very end and then spend hours debugging why their states aren't working correctly.

At least the information is all there now and correct, but without the readability and clarity problems being addressed, I think this probably shouldn't have been closed so quickly.