Cookbook chapter 2 - Githubissues

jonathom commented 3 years ago

Chapter 2 is ready for review :tada:

Things that still need to be done:

[x] navigation to reach it via the website menu @m-mohr
[x] complete code check @jonathom
[x] squash PR @jonathom
[ ] Fix sidebar headings (go deeper, also into h3/h4) @m-mohr

Any opinions and reviews are very welcome!

m-mohr commented 3 years ago

Thanks, I'll look at this next week. I'm wondering though whether we should simply merge this with "chapter 1"?

jonathom commented 3 years ago

I'm wondering though whether we should simply merge this with "chapter 1"?

That's a hard question. While discoverability would improve, I think that having chapters is a good way to compartmentalize all the different functions and use cases that are flying around. Additionally, the examples sometimes reuse previous code, which I think becomes less clear with growing chapter size.

m-mohr commented 3 years ago

The issue is that the space in the menu is limited and I should not add multiple chapters into the menu.

It could still be two chapters in a single document, maybe? The TOC is generated anyway on the left side...

jonathom commented 3 years ago

so this isn't a didactic issue, it's a menu design issue :D do you want to revise now or after I merge the chapters? I will have to make some changes.

m-mohr commented 3 years ago

Yes, more or less. For now, I'd propose to make two chapters, but have them on the same page for now. Would be great if you could do it in this PR.

m-mohr commented 3 years ago

I just realized that the images are rather large (also for the urk image and some getting started images).

I think we should try to stick to a maximum of roughly 500kb per image. Maybe it's better to compress them all as JPEG files?

jonathom commented 3 years ago

Copy that. Will take care of it tomorrow.

m-mohr commented 3 years ago

Tested it with a getting started image: Reduced from 1,8 MB PNG to 0,3 MB JPEG with those settings:

Compressed the existing images, but not the ones in this PR.

Note to me: Squash this PR later to get rid of the large files in the git history.

m-mohr commented 3 years ago

Thanks, very well written (although I added a lot of comments about minor things).

jonathom commented 3 years ago

Now another issue with TOC arises: only one # heading is printed but there are three (openEO cookbook, chapter 1, chapter 2) and no #### level headings are included (so moving everything one # down excludes subsections).. anything we can do about this?

m-mohr commented 3 years ago

I think there's a config option, let me check...

m-mohr commented 3 years ago

Try to add this at the start of the markdown file:

---
sidebarDepth: 4
---

jonathom commented 3 years ago

doesn't seem to work. maybe because of local server instead of via web?

m-mohr commented 3 years ago

Seems we need to set another config option globally, I'll take care of it after merging.

m-mohr commented 3 years ago

Good work!

I've checked the images and they are not exceeding 100% of their size so it's fine if they show up larger as they don't upscale and get pixelated.
I could not get the headers working yet, either I did something wrong or our version doesn't support more levels yet. I'll open a separate issue to keep track as I'll likely not be able to solve it soon. See #49

jonathom commented 3 years ago

Thanks!

I was more concerned about the images for aesthetic reasons, as now they're a bit big, standing out more than I thought they would. But that's ok, took some getting used to.
Thanks for investigating

Open-EO / openeo.org

Cookbook chapter 2 #47