{"action":"created","issue":{"url":"https://api.github.com/repos/scour-project/scour/issues/112","repository_url":"https://api.github.com/repos/scour-project/scour","labels_url":"https://api.github.com/repos/scour-project/scour/issues/112/labels{/name}","comments_url":"https://api.github.com/repos/scour-project/scour/issues/112/comments","events_url":"https://api.github.com/repos/scour-project/scour/issues/112/events","html_url":"https://github.com/scour-project/scour/issues/112","id":177126493,"number":112,"title":"man page","user":{"login":"Eitot","id":15073177,"avatar_url":"https://avatars.githubusercontent.com/u/15073177?v=3","gravatar_id":"","url":"https://api.github.com/users/Eitot","html_url":"https://github.com/Eitot","followers_url":"https://api.github.com/users/Eitot/followers","following_url":"https://api.github.com/users/Eitot/following{/other_user}","gists_url":"https://api.github.com/users/Eitot/gists{/gist_id}","starred_url":"https://api.github.com/users/Eitot/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/Eitot/subscriptions","organizations_url":"https://api.github.com/users/Eitot/orgs","repos_url":"https://api.github.com/users/Eitot/repos","events_url":"https://api.github.com/users/Eitot/events{/privacy}","received_events_url":"https://api.github.com/users/Eitot/received_events","type":"User","site_admin":false},"labels":[{"url":"https://api.github.com/repos/scour-project/scour/labels/needs-discussion","name":"needs-discussion","color":"fbca04"}],"state":"open","locked":false,"assignee":null,"assignees":[],"milestone":null,"comments":2,"created_at":"2016-09-15T09:13:16Z","updated_at":"2016-09-16T05:44:35Z","closed_at":null,"body":"I’m so in the habit of checking `man` that I miss it for Scour. Some of the options in `--help` are not spelt out and a wee commentary for some options would be nice. An example section would also be useful and perhaps some niche options and the copyright stuff could be moved from `--help` to the man page.\r\n\r\nHow would you feel about adding one? I see that it is as easy as adding a `data_files` parameter to setup.py which installs the man page in the correct directory upon install with `pip`."},"comment":{"url":"https://api.github.com/repos/scour-project/scour/issues/comments/247522826","html_url":"https://github.com/scour-project/scour/issues/112#issuecomment-247522826","issue_url":"https://api.github.com/repos/scour-project/scour/issues/112","id":247522826,"user":{"login":"oberstet","id":233340,"avatar_url":"https://avatars.githubusercontent.com/u/233340?v=3","gravatar_id":"","url":"https://api.github.com/users/oberstet","html_url":"https://github.com/oberstet","followers_url":"https://api.github.com/users/oberstet/followers","following_url":"https://api.github.com/users/oberstet/following{/other_user}","gists_url":"https://api.github.com/users/oberstet/gists{/gist_id}","starred_url":"https://api.github.com/users/oberstet/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/oberstet/subscriptions","organizations_url":"https://api.github.com/users/oberstet/orgs","repos_url":"https://api.github.com/users/oberstet/repos","events_url":"https://api.github.com/users/oberstet/events{/privacy}","received_events_url":"https://api.github.com/users/oberstet/received_events","type":"User","site_admin":false},"created_at":"2016-09-16T05:44:35Z","updated_at":"2016-09-16T05:44:35Z","body":"Man pages are \"unusual\" for Python projects distributed via PyPI, and problematic, since they need to be installed into system directories. Sometimes, distro packagers add man pages when packaging Python stuff into deb/rpm etc., and that is \"ok\" (but not our task). \r\n\r\nI have strong opinions rgd distro packaging of Python stuff: it is plain wrong. Installing everything into the system/global Python is wrong - conflicting versions, interference between packages etc\r\n\r\nThat being said, I agree with @Eitot that `--help` should spell out all command line options, precisely and exhaustively. It sucks a little having to dig into source to get at the real stuff.\r\n\r\nAs a user, this would be my expectation of docs in general:\r\n\r\n* there should be a concise README in the repo that is duplicated to appear as the PyPI page. Contents: what is it? why/for what use? what license / where did it came from (history). pointers to: source code, changelog, issue tracker, how to get in touch (contacts), docs (readthedocs)\r\n* `--help`: concise, exhaustive command line usage/options\r\n* readthedocs: tutorial like .. use case oriented. should we officially support API based usage, that too (API reference)\r\n\r\nSphinx is great .. the way to go IMO. Hosting: RTD generated from Sphinx. This can be fully automated (we can have RTD integrated, and online docs will be automatically updated). RTD is the go to place looking for Python docs.\r\n\r\n---\r\n\r\nRgd CLI of Scour: currently we use `optparse` (Py stdlib). This is old, `argparse` (Py stdlib) is better and the new way. \r\n\r\n> Deprecated since version 2.7: The optparse module is deprecated and will not be developed further; development will continue with the argparse module.\r\n\r\nApart from argparse, we might also consider http://click.pocoo.org/. This can do very nice CLIs - though it would introduce a non-stdlib dep.\r\n"}}
{"actor":{"display_login":"oberstet"}}