pyboards docs: Put hardware/datasheet info under "General information about pyboard"

[pfalcon]

As mentioned and shown at #2578 (comment), pyboard docs inconsistent wrt to other port docs in that they put 3 headings of this doc: http://docs.micropython.org/en/latest/pyboard/pyboard/hardware/index.html as top-level chapters. That leads to pretty messy ToC. Instead, that information should go under "general information about board" like other ports do (well, like esp8266, the freshest, does).

If approved, should this be a PR or can be committed directly?

[dpgeorge]

I like having a separate page for hardware reference (schematics and datasheets), as opposed to the general info in "general information about board" which is more about how the board differs to other ones.

I think an easy fix is to just move pyboard/hardware/index.rst to pyboard/hardware.rst and treat it like general.rst / quickref.rst.

[pfalcon]

So, the problem which needs fixing here is that very particular info gets a toplevel heading in the ToC. And the way to fix it consistently across ports, and currently only pyboard port seems to have this issue. As the aim is to move it away from h1, it must be included in some other doc. And we already have nice consistent breakdown for each board, where board-specific info is presented via Quickref, General Info and Tutorial, and of these 3, General Info is the most suitable.

Then if you want to keep hardware.rst (as a file), I'm sure we can do it, but it would need to fit nicely in the general docs structure and ToC.

Just imagine - hardware info is of course important information for a user, but in MicroPython work, one unlikely will refer to it too often, instead e.g. library reference is expected to be such. Then no need for HW info to take a line in ToC which is always present to the user in the left pane. Instead, it only makes sense to teach users to seek any board-specific info in General Info section.

[pfalcon]

@dpgeorge : So, does this make sense?

[torwag]

Well,
the problem might be that the doc is not consistent already on a higher level,
unix and esp8266 are system ports
wipy and pyboard are board ports
From all of them pyboard is the only self-made board under control of MP resp. dpgeorge.

Don't get me wrong, I am all in for a consistent doc, the question is, should it already be on the port level and we call it Unix, ESP8266, STM32, CC3200
e.g. the wipy1 is afaik not even anymore on sale. Whereas CC3200 boards might be still around (just a guess).
Each of those could have a h1 entry in the docs "Supported boards" and from there people could set links to external projects or in case of the pyboard the hardware docs could be added.

I am aware that this might even require more rewriting and splitting of the docs, as right now board and uC features get sometimes mixed in the docs.

[dpgeorge]

@dpgeorge : So, does this make sense?

Yes, ok, sounds good. Then I guess that both "The pyboard hardware" and "Guide for the pyboard on Windows (PDF)" will go in the "General information about the pyboard" section, possibly as subpages in the end when more info is added, but for now can be a single page with subheadings.

BTW, one of the reasons the ToC is messy now is because hardware/index.rst has 3 h1's, when it should have just 1x h1 and then 3x h2's under that.

[dpgeorge]

This is now done.