[yocto] Layer documentation for meta-raspberrypi

[Paul Barker]

On Mon, Dec 11, 2017 at 12:08 PM, Mirza Krak <mirza.krak at gmail.com> wrote:
> 2017-12-11 12:55 GMT+01:00 Paul Barker <pbarker at toganlabs.com>:
>> Hi all,
>>
>> As a quick announcement, the layer documentation for meta-raspberrypi
>> is now available on Read the Docs:
>> http://meta-raspberrypi.readthedocs.io/en/latest/
>>
>> The latest documentation is shown by default and covers the master
>> branch. Using the version box in the bottom right corner of the page
>> you can also switch to the rocko or pyro versions. This is
>> automatically updated whenever changes are pushed to the documentation
>> in meta-raspberrypi.
>>
>> Raspberry Pi seems to be a very common platform for newcomers to
>> OE/Yocto and so I think it's really important that this layer is well
>> documented and is easy to use. Please submit pull requests or open
>> bugs if you think any of the documentation can be improved.
>>
>> We use Sphinx (http://www.sphinx-doc.org/) plus Read the Docs
>> (https://readthedocs.org/) integration for this which I think is a
>> pretty good setup for layer documentation in general. If anyone wants
>> more details so they can do something similar for another layer then
>> please let me know!
>
> Great work and this will definitely be appreciated by all the
> meta-raspberrypi users.
>
> One little thing though, the current "theme" used which I assume is
> the default Sphinx theme is not optimal IMO.
>
> readthedocs does apply its own default theme [1] if you do not provide
> one in your custom conf which looks much better (that is the look that
> docs.readthedocs.io has) which is easier to read and navigate. I
> believe that most developers are familiar with it as many other
> projects that host documentation on readthedocs use this theme
> (including the Linux kernel and more).
>
> [1]. http://docs.readthedocs.io/en/latest/theme.html?highlight=theme
>

Thanks for the feedback. The conf.py file we're using is just what was
generated by sphinx-quickstart with minimal tweaks. It sets html_theme
which is obviously overriding the default for read the docs.

I think I should be able to get the right behaviour by commenting out
the html_theme setting completely. I'll give that a go and see what
happens.

Cheers,

-- 
Paul Barker
Togán Labs Ltd