{"action":"created","issue":{"url":"https://api.github.com/repos/RPi-Distro/python-gpiozero/issues/101","labels_url":"https://api.github.com/repos/RPi-Distro/python-gpiozero/issues/101/labels{/name}","comments_url":"https://api.github.com/repos/RPi-Distro/python-gpiozero/issues/101/comments","events_url":"https://api.github.com/repos/RPi-Distro/python-gpiozero/issues/101/events","html_url":"https://github.com/RPi-Distro/python-gpiozero/pull/101","id":115019872,"number":101,"title":"Generic docs need reST","user":{"login":"waveform80","id":1076190,"avatar_url":"https://avatars.githubusercontent.com/u/1076190?v=3","gravatar_id":"","url":"https://api.github.com/users/waveform80","html_url":"https://github.com/waveform80","followers_url":"https://api.github.com/users/waveform80/followers","following_url":"https://api.github.com/users/waveform80/following{/other_user}","gists_url":"https://api.github.com/users/waveform80/gists{/gist_id}","starred_url":"https://api.github.com/users/waveform80/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/waveform80/subscriptions","organizations_url":"https://api.github.com/users/waveform80/orgs","repos_url":"https://api.github.com/users/waveform80/repos","events_url":"https://api.github.com/users/waveform80/events{/privacy}","received_events_url":"https://api.github.com/users/waveform80/received_events","type":"User","site_admin":false},"labels":[],"state":"open","locked":false,"assignee":null,"milestone":null,"comments":2,"created_at":"2015-11-04T10:20:11Z","updated_at":"2015-11-04T12:04:56Z","closed_at":null,"pull_request":{"url":"https://api.github.com/repos/RPi-Distro/python-gpiozero/pulls/101","html_url":"https://github.com/RPi-Distro/python-gpiozero/pull/101","diff_url":"https://github.com/RPi-Distro/python-gpiozero/pull/101.diff","patch_url":"https://github.com/RPi-Distro/python-gpiozero/pull/101.patch"},"body":"Conversion of all docs to reST so that the generic docs can link easily with the rest of the docs.\r\n\r\nI realize this will be a rather controversial PR - please let me know if you want to discuss anything; I won't merge it myself! I also think there's several things that could be improved:\r\n\r\n* There's an excess of methods in the inputs and outputs section - we can probably trim those down a bit\r\n* I should probably split all the recipes out into their own python files and just \".. include\" them in the docs to enable easier testing (I've already done this in the [picraft docs] - makes things much easier to test when I want to tweak a recipe)\r\n* We might want to consider the \"alabaster\" theme which is rather nice - you can see examples of it in the [picraft docs], [requests docs], and [flask docs] - I've been considering it for the next version of picamera but I'm not sure yet\r\n\r\nStill, I figured I'd float the PR as it stands before pressing any further with it :)\r\n\r\n[picraft docs]: http://picraft.readthedocs.org/\r\n[requests docs]: http://docs.python-requests.org/\r\n[flask docs]: http://flask.pocoo.org/"},"comment":{"url":"https://api.github.com/repos/RPi-Distro/python-gpiozero/issues/comments/153700686","html_url":"https://github.com/RPi-Distro/python-gpiozero/pull/101#issuecomment-153700686","issue_url":"https://api.github.com/repos/RPi-Distro/python-gpiozero/issues/101","id":153700686,"user":{"login":"waveform80","id":1076190,"avatar_url":"https://avatars.githubusercontent.com/u/1076190?v=3","gravatar_id":"","url":"https://api.github.com/users/waveform80","html_url":"https://github.com/waveform80","followers_url":"https://api.github.com/users/waveform80/followers","following_url":"https://api.github.com/users/waveform80/following{/other_user}","gists_url":"https://api.github.com/users/waveform80/gists{/gist_id}","starred_url":"https://api.github.com/users/waveform80/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/waveform80/subscriptions","organizations_url":"https://api.github.com/users/waveform80/orgs","repos_url":"https://api.github.com/users/waveform80/repos","events_url":"https://api.github.com/users/waveform80/events{/privacy}","received_events_url":"https://api.github.com/users/waveform80/received_events","type":"User","site_admin":false},"created_at":"2015-11-04T12:04:56Z","updated_at":"2015-11-04T12:04:56Z","body":"On a vaguely related topic, there's a few things to consider with regard to RTD vs pythonhosted.\r\n\r\n* With RTD we get support for multi-version builds and the ability to specify the current default built (extremely useful when you want everyone to default to the current release of the docs, but you also want to serve the latest bleeding edge to those cloning from GitHub).\r\n\r\n* We also get PDF and Epub output. They're minority formats, sure, but definitely not unused. For example, Spence at the latest picademy immediately downloaded the gpiozero epub docs from my rtd build to browse on his iPad (this is another effective treatment for \"offline\" access to docs which is important to plenty of people in less-than-connected locales).\r\n\r\n* I haven't bunged the Google analytics settings in the RTD build yet, but I can do that if you want (didn't want to confuse the stats with stuff from two sites).\r\n\r\nOn your main point of simple docs for kids and teachers, if you've got pretty obviously named sections I don't think there's much of a problem. While there's plenty I could improve in the picamera docs, the \"Basic Recipes\" and \"Advanced Recipes\" sections have worked extremely well (based on e-mail feedback over the years). Everyone gravitates to \"Basic Recipes\" almost immediately and if they don't find what they're looking for there they either dip their toe into the advanced recipes or e-mail me.\r\n\r\nThere's probably something we could do along similar lines here. Firstly I do think the Recipes section ought to be moved up to the front. That's where everyone's going to want to start, and it actually serves as a decent \"quickstart\" section too (I'm more or less convinced I should remove \"quickstart\" from the picamera docs - no one ever seems to use it, and it's better covered elsewhere).\r\n\r\nThat can be followed by the input and output devices sections, and the board section. We *might* want to combine these into a \"basic devices\" section or something like that, but I don't think the current separation is bad. We certainly want to curate the list of methods and attributes in them though - they're a bit extensive in the current RTD build which includes *all* inherited members (I don't believe close() and closed need to be in there at all for example).\r\n\r\nFinally, follow that with generic devices. That really ought to be the last reference section because it's easily the most advanced (generally I like to order things in the manual simple -> complex, with administrivia like license and changelog last).\r\n\r\nOn the Notes section... That's an interesting one. I'd like the GPIO reference notes and pin layout image right up front - possibly at the start of the Recipes section or even in the README at the very front. The \"Keep your scripts running\" section ... hmmm, maybe a section somewhere in Recipes? The \"Importing from GPIO Zero section\" ought to be at the top of Recipes as it's basically step 1 in using the library.\r\n\r\nAs for the Programming Terms section ... I'm not sure why we're trying to teach basic programming concepts here (doesn't seem like the right place for it). Total beginners can happily use the library without understanding any of those terms based on copy'n'tweak of the recipes so if we were going to keep it anywhere I'd suggest putting it as a glossary at the end (no need to scare away anyone by shoving terminology like \"Context manager\" in their face before the Recipes ;)"}}