handbook version 2

[kimrhh]

This issue is meant as a placeholder for a discussion on how to improve the current handbook

[kimrhh]

Let me see if I can get this rolling :)

My ideas for a better handbook would be:

• The handbook should generally try to answer "How do I ... ?" questions
• currently, the only "how do I ... ?" it really answers is how to set up a machine for building
  • for this step, we need to think about how we make a user build some kind of "hello world" so it can be verified they are good to go. So far we had the idea of maintaining example manifest(s) like the rpi one, but that requires significant work/ressources to do properly. Perhaps we can do something else, like just make them build a demo-image and look at that output?
  • this section needs to have a real-quick-start using our docker setup, the manual setup should still be kept.
• a section walking through an example build should be added. Explaining what is going on high-level, directories, phases etc.
• the main "how do I ..." that is lacking in my opinion is:
  • How do I create a new BSP?
    • configuration
      • what is a machine?
      • what is a distro?
    • what is an SDK?
  • How do I update an existing recipe?
  • How do I make a new recipe?

The handbook should try hard to avoid duplicating information present (maybe not yet) in the Core reference manual. E.g. while the handbook should give an example of tasks you would typically do, Core Ref. Man. should describe all the possibilities

[prevasprtr]

I think the first chapter of the handbook should contain nothing but

1. install docker
2. clone oe lite
3. copy local.conf.sample to local.conf
4. oe-bake machine
5. git branch

With these 5 steps you got something working and a platform to continue working from
The second chapter would be how to create a BSP

Third chapter
How to add my stuff - recipe

Fourth chapter
How to push my stuff to OE-lite / my origin

Advanced chapters could be
Chapter X The wonders of USE_FLAGS
Chapter X The magic of the already existing OE Lite flags MACHINE_* DISTRO_* COMPATIBLE_* etc
Chapter X mirrors
Chapter X HOW TO if not using docker
Chapters x .. y everything else forgotten above

[KimBoendergaard]

This is merely a comment to the existing manual than a suggestion to new content or new structure:
The first section - describes several ways to install bakery on 'your host' and then lists 4 items.
But in reality I think there are just two ways: Install from source or use your hosts 'package installer system.
The latter we then describe for two distributions: Ubuntu and Exherbo

Regarding the 'source method' I think the difference is whether you 'install it' or just use the downloaded source from where it is unpacked. It could be written, I think ,so it becomes more clear what's the difference in the two sections.

Another issue with section "Install Bakery" is the 'Install additional tools" being dumped in between the sections describing how to install Bakery. It is just mentioned to be required tools to run OE-lite bakery and can just as well be listed after installation of oe-bakery - or be a separate section coming before.

And like already mentioned: If oe-lite.org has a docker image ready for use we should point at that too

[KimBoendergaard]

Personally I'd prefer to favour git for git operations and oe for baking. I.e. drop stuff like oe clone in the manual

[KimBoendergaard]

Bunch of examples use oe-lite.org in URL's

[cvt-romowind]

I want to compile the handbook itself.
I did a clone:
git clone https://github.com/oe-lite/handbook.git
If I then want to build html it complains about sphinx-build not installed. Could you provide a small README.md file in the handbook.git repo with prerequisites for the install (e.g. what packages to install).

Also in previous version of the handbook there was a make all option. This rule seems to have been removed.

[kimrhh]

@cvt-romowind there is now a README :)

[kimrhh]

Thanks to @Villemoes there is now a huge additional section in the handbook about recipe writing, let us know what you think about it