{"action":"created","issue":{"url":"https://api.github.com/repos/ansible/ansible/issues/16579","repository_url":"https://api.github.com/repos/ansible/ansible","labels_url":"https://api.github.com/repos/ansible/ansible/issues/16579/labels{/name}","comments_url":"https://api.github.com/repos/ansible/ansible/issues/16579/comments","events_url":"https://api.github.com/repos/ansible/ansible/issues/16579/events","html_url":"https://github.com/ansible/ansible/issues/16579","id":163809764,"number":16579,"title":"Add built in documentation for playbooks/tasks","user":{"login":"alform","id":3426130,"avatar_url":"https://avatars.githubusercontent.com/u/3426130?v=3","gravatar_id":"","url":"https://api.github.com/users/alform","html_url":"https://github.com/alform","followers_url":"https://api.github.com/users/alform/followers","following_url":"https://api.github.com/users/alform/following{/other_user}","gists_url":"https://api.github.com/users/alform/gists{/gist_id}","starred_url":"https://api.github.com/users/alform/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/alform/subscriptions","organizations_url":"https://api.github.com/users/alform/orgs","repos_url":"https://api.github.com/users/alform/repos","events_url":"https://api.github.com/users/alform/events{/privacy}","received_events_url":"https://api.github.com/users/alform/received_events","type":"User","site_admin":false},"labels":[],"state":"open","locked":false,"assignee":null,"assignees":[],"milestone":null,"comments":1,"created_at":"2016-07-05T09:38:00Z","updated_at":"2016-07-05T13:57:40Z","closed_at":null,"body":"<!--- Verify first that your issue/request is not already reported in GitHub -->\r\n\r\n##### ISSUE TYPE\r\n<!--- Pick one below and delete the rest: -->\r\n - Feature Idea\r\n\r\n\r\n##### ANSIBLE VERSION\r\n<!--- Paste verbatim output from “ansible --version” between quotes below -->\r\n```\r\nALL\r\n```\r\n\r\n##### OS / ENVIRONMENT\r\n<!---\r\nMention the OS you are running Ansible from, and the OS you are\r\nmanaging, or say “N/A” for anything that is not platform-specific.\r\n-->\r\nN/A\r\n##### SUMMARY\r\n<!--- Explain the problem briefly -->\r\n\r\nThere is at present no way, short of the name field, or code comments, to document the operations and intended usage of a playbook/task/role. The name field, however, adds to the log verbosity and cannot easily be displayed without executing the playbook itself or reading the code - comments, on the other hand, require reading the source.\r\n\r\n##### STEPS TO REPRODUCE\r\n<!---\r\nFor bugs, show exactly how to reproduce the problem.\r\nFor new features, show how the feature would be used.\r\n-->\r\nFor playbooks/tasks(/vars?) add a --info/help/doc/man switch that will print verbatim the content of info/help/doc/man sections found in the relevant files, without execution.\r\n\r\n<!--- Paste example playbooks or commands between quotes below -->\r\n```\r\n $ ansible-playbook --help my-nifty-playbook.yml\r\n\r\n Play name Fubar\r\n Help: This play will foo all the bars found in  zork of every host. \r\n           The method used is as follows...\r\n\r\n      Task name frobnicate\r\n       Help: This task executes the preventive frobnication by issuing frobnicate zork commands against \r\n                 all relevant iinstances.\r\n\r\nYML:\r\n\r\n---\r\n- name: Fubar\r\n help: This play will foo all the bars found in  zork of every host. \r\n           The method used is as follows...\r\n\r\n  tasks:\r\n     - name: frobnicate\r\n       help:  This task executes the preventive frobnication by issuing frobnicate zork commands against \r\n                 all relevant iinstances.\r\n\r\n```\r\n\r\n<!--- You can also paste gist.github.com links for larger files -->\r\n\r\n##### EXPECTED RESULTS\r\n<!--- What did you expect to happen when running the steps above? -->\r\n\r\nCentralize and promote documentation of playbooks/tasks/roles...\r\n \r\n"},"comment":{"url":"https://api.github.com/repos/ansible/ansible/issues/comments/230485571","html_url":"https://github.com/ansible/ansible/issues/16579#issuecomment-230485571","issue_url":"https://api.github.com/repos/ansible/ansible/issues/16579","id":230485571,"user":{"login":"bcoca","id":836171,"avatar_url":"https://avatars.githubusercontent.com/u/836171?v=3","gravatar_id":"","url":"https://api.github.com/users/bcoca","html_url":"https://github.com/bcoca","followers_url":"https://api.github.com/users/bcoca/followers","following_url":"https://api.github.com/users/bcoca/following{/other_user}","gists_url":"https://api.github.com/users/bcoca/gists{/gist_id}","starred_url":"https://api.github.com/users/bcoca/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/bcoca/subscriptions","organizations_url":"https://api.github.com/users/bcoca/orgs","repos_url":"https://api.github.com/users/bcoca/repos","events_url":"https://api.github.com/users/bcoca/events{/privacy}","received_events_url":"https://api.github.com/users/bcoca/received_events","type":"User","site_admin":false},"created_at":"2016-07-05T13:57:40Z","updated_at":"2016-07-05T13:57:40Z","body":"I would probably add it to `ansible-doc` instead"}}
{"actor":{"display_login":"bcoca"}}