{"action":"created","issue":{"url":"https://api.github.com/repos/CISecurity/OVALRepo/issues/16","labels_url":"https://api.github.com/repos/CISecurity/OVALRepo/issues/16/labels{/name}","comments_url":"https://api.github.com/repos/CISecurity/OVALRepo/issues/16/comments","events_url":"https://api.github.com/repos/CISecurity/OVALRepo/issues/16/events","html_url":"https://github.com/CISecurity/OVALRepo/issues/16","id":94313126,"number":16,"title":"API Documentation Generation","user":{"login":"GunnarEngelbach","id":13241056,"avatar_url":"https://avatars.githubusercontent.com/u/13241056?v=3","gravatar_id":"","url":"https://api.github.com/users/GunnarEngelbach","html_url":"https://github.com/GunnarEngelbach","followers_url":"https://api.github.com/users/GunnarEngelbach/followers","following_url":"https://api.github.com/users/GunnarEngelbach/following{/other_user}","gists_url":"https://api.github.com/users/GunnarEngelbach/gists{/gist_id}","starred_url":"https://api.github.com/users/GunnarEngelbach/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/GunnarEngelbach/subscriptions","organizations_url":"https://api.github.com/users/GunnarEngelbach/orgs","repos_url":"https://api.github.com/users/GunnarEngelbach/repos","events_url":"https://api.github.com/users/GunnarEngelbach/events{/privacy}","received_events_url":"https://api.github.com/users/GunnarEngelbach/received_events","type":"User","site_admin":false},"labels":[],"state":"open","locked":false,"assignee":null,"milestone":null,"comments":1,"created_at":"2015-07-10T14:08:12Z","updated_at":"2015-07-10T15:06:58Z","closed_at":null,"body":"I thought it would be helpful to take advantage of the doc strings in the script files to generate API documentation, so I started looking into that.\r\n\r\nSimply using pydoc -w should suffice, but I tried that against the existing source and all files returned an error message about not having doc strings -- which, to my manual examination, they do, so this is likely user error.\r\n\r\nStill,  Sphinx (http://sphinx-doc.org/) comes highly recommended for this usage, but I have not yet taken the time to get that set up and working.\r\n\r\nDoes anybody else have opinions or suggestions?"},"comment":{"url":"https://api.github.com/repos/CISecurity/OVALRepo/issues/comments/120431463","html_url":"https://github.com/CISecurity/OVALRepo/issues/16#issuecomment-120431463","issue_url":"https://api.github.com/repos/CISecurity/OVALRepo/issues/16","id":120431463,"user":{"login":"DavidRies","id":728508,"avatar_url":"https://avatars.githubusercontent.com/u/728508?v=3","gravatar_id":"","url":"https://api.github.com/users/DavidRies","html_url":"https://github.com/DavidRies","followers_url":"https://api.github.com/users/DavidRies/followers","following_url":"https://api.github.com/users/DavidRies/following{/other_user}","gists_url":"https://api.github.com/users/DavidRies/gists{/gist_id}","starred_url":"https://api.github.com/users/DavidRies/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/DavidRies/subscriptions","organizations_url":"https://api.github.com/users/DavidRies/orgs","repos_url":"https://api.github.com/users/DavidRies/repos","events_url":"https://api.github.com/users/DavidRies/events{/privacy}","received_events_url":"https://api.github.com/users/DavidRies/received_events","type":"User","site_admin":false},"created_at":"2015-07-10T15:06:58Z","updated_at":"2015-07-10T15:06:58Z","body":"Sphinx does look good, but I've never used any of these. It's more than possible that the initial doc strings I added aren't formatted in a \"pythonic\" way. Happy to revise if that turns out to be the case.\r\n\r\nI'm not sure what we need in terms of documentation, but perhaps we don't need real API/Code docs? I think script developers can look at the code comments.\r\n\r\nFor script users (content contributors and content consumers), I think they'll just use the executable scripts and not the lib_*.py scripts. If that's the case, maybe we just needs docs for the executable scripts?\r\n\r\nIf so, they all have command line help. Maybe all we need is a good readme that explains for each executable script:\r\n- what it's used for\r\n- gives some examples\r\n- tells you how to access CLI help for more details\r\n\r\nWDYT?"}}