Generic docs need reST

[waveform80]

Conversion of all docs to reST so that the generic docs can link easily with the rest of the docs.

I 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:

• There's an excess of methods in the inputs and outputs section - we can probably trim those down a bit
• 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)
• 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

Still, I figured I'd float the PR as it stands before pressing any further with it :)

[bennuttall]

I had a chat with someone last night who suggested we maintain both user docs and developer docs. We could use mkdocs and pythonhosted for user docs, and sphynx and readthedocs for developer docs.

I really want a set of simple documentation designed for kids and teachers which just lists the things you can do and how to do it. Perhaps the table layout I used isn't right - but let's find a way that works. I'm consulting with the edu team here.

[waveform80]

On a vaguely related topic, there's a few things to consider with regard to RTD vs pythonhosted.

• 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).
• 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).
• 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).

On 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.

There'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).

That 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).

Finally, 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).

On 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.

As 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 ;)

[bennuttall]

Ok let's just do it.

Dave - do you need to do anything to catch up to merge this?

I obviously don't want to have documentation in two different places, don't want them to disappear from pythonhosted (or stay as they are and get out of date), and don't want links to old pages to break.

I guess sphynx generates a folder containing the static site, so we could upload that to pythonhosted? However, the page URLs are different so perhaps the best thing is to just put "this page has moved" and link to the new place? I'm guessing we can't add custom rewrite rules to pythonhosted.

[waveform80]

Okay, this should now be complete (at least as far as migration is concerned): the RTD config has been pointed at this repo instead of my clone, I've added the Google Analytics code to the RTD config, and re-configured it to load the "latest" branch by default (once v1.1 is out I'll reconfigure that again for the 1.1 tag). If you want to do anything to redirect requests from pythonhosted over to RTD, it should now be safe to do so.

This'd also be a good time for people to have a trawl through the RTD docs and make sure I haven't made a complete pigs ear of anything. I've spent a good couple of hours trawling through the diff and picking over the final build but there's bound to be stuff I've missed so do let me know what I've broken!

Anyway, that's enough for me for tonight. Tomorrow I'll try and tackle the rest of the 1.1 list and see if I can get pins merged too (but that'll require some rebasing first).

[lurch]

http://gpiozero.readthedocs.org/en/latest/recipes.html#gpio-music-box needs to be updated to match http://pythonhosted.org/gpiozero/recipes/#gpio-music-box

And it looks like #120 and #117 need to be 're-applied' too.

[waveform80]

Ah, there we go - knew I'd missed some bits! I'll get these done in a mo.

[waveform80]

@bennuttall RTD doesn't seem to be auto-rebuilding on commits to this repo despite the fact I've pointed the RTD project at this repo. Can you check the repo settings and make sure the readthedocs hook is installed? It usually happens automatically these days but I get the feeling this may not happen automatically when a project's repo gets changed (I'd check it but collaborators don't get settings access). It's not that big of a deal as I can kick off a build manually but it'd be nice for the future in case I forget :)

[lurch]

I dunno if it's worth opening a separate issue for, but I guess the image at http://gpiozero.readthedocs.org/en/latest/recipes.html#motion-sensor would make more sense if it actually showed the LED connected too. Which then begs the question "why does that recipe have the LED on GPIO16, when most of the other recipes have the LED on GPIO17?".
Which then leads me to wonder if (for the sake of consistency) all the examples in the documentation should use the same components connected to the same GPIO pins (avoiding overlaps where possible), so that users following-along-at-home don't have to re-wire their breadboards or edit the code they're copying'n'pasting, when switching between different examples?

[waveform80]

Yeah, this was me messing around with the image placement. After reviewing the patch I wound up moving the images from the component API to the recipes section. The main reason for this is that, from my experience with the picamera docs no-one looks at API docs if they don't have to: everyone hits the recipes first (I assume because they're more immediately useful to them, or maybe just because they're first) so let's have the wiring diagrams up front with them.

A secondary (but considerably less important) reason is that the API docs are also (occasionally) accessed from Python's command line (help() and ipython's ?-suffix operator) which can't display images so they're a bit less useful there. That did mean tweaking some of the recipes to fit the images and in the case of the motion sensor one, it is missing the LED - I'm hoping we can correct this and fill out the other missing images in fairly short order (I've sent a list of images to Ben; hopefully we can have Sam rustle up some nice pics for them!)

On the suggestion of consistency between recipes: as far as possible that's a great idea (obviously in some places, like with add-on boards, we won't be able to manage that but wherever possible it's something we ought to try and stick to)!

[lurch]

Another small doc-related issue - the README on https://github.com/RPi-Distro/python-gpiozero now points at https://gpiozero.readthedocs.org/ but the URL at the very top of the page (next to the "A simple interface to everyday GPIO components used with Raspberry Pi" description) still points at http://pythonhosted.org/gpiozero/

[waveform80]

Doh! Good catch; @bennuttall - can you correct that?

[bennuttall]

Done!