Addressing comments from Jakob on the book

[amal-ghamdi]

Description:

Update the book to address comments from @jakobsj provided in #57

comments are copied and processed here:

Needed now

• [x] Split simplest BIP in bare bones (for concepts) and extended version (directors cut) with elaborate (comment by @amal-ghamdi, editing the long version is captured in #50 )
• [x] Order of chapters 1,2, … A, B, …? What is numbered by numbers, what by letters? State this. Probably change to simple numbering only numbers. (comment by @amal-ghamdi, done in another PR, chapters are only numbered now #47)
• [x] Is chapter B and B01, B02, B03 related? (comment by @amal-ghamdi, not related. updated in #47. chapters are only numbered now, and notebooks starting with B.. are renamed)
• [x] Do not need to organize material in the order that it be covered in Edinburgh. (good point, taken into account)
• [x] keep in mind the ability to design training plan using selected, non-consecutive sections (good point, taken into account)
• [x] Plans for chapter 2, 3? These are now partially redundant with other material.(comment by @amal-ghamdi, I think by now redundancy are reduced to reasonably close to minimum #47)
• [x] Add a section for the License of the book, preferably the section title is visible on the left menu
• [x] Add reference to other Licenses when there is an exception (e.g. )
• [x] Try executing (CIL, FEniCS) notebooks locally and incorporate them in the book, and let jupyter-book execute the rest. (done in another PR #44 )
• [x] Add comments at the beginning of CIL/FEniCS/PyTorch notebooks that they are executed locally, and the user need to download it and execute it in their own machine after they set up the environment
• [x] Chapter 1 startpage has chapter learning objectives (https://amal-ghamdi.github.io/CUQI-Book-test/chapter01/chapter01.html), suggest to add a sentence or two before the learning objective explaining what the chapter is about.

easy

• [x] Title of minibook: Remove "Welcome" etc from title, to make it very clear what title is and make it stand out. "Welcome" can be said in a sentence below. (comment by @amal-ghamdi, done in PR #47 )
• [x] Remove references to 02975 course

could wait (moved to #73)

• ~Chapter 1 page: State explicitly that these are learning objectives. And use consistent format for learning objective for all chapters.~
• ~Then other chapters have empty startpages eg chapter 2 would benefit from also having a short intro and chapter learning objectives added: https://amal-ghamdi.github.io/CUQI-Book-test/chapter02/chapter02.html~
• ~Consider splitting long pages into multiple shorter (e.g. separate install out from the long overview page). Two reasons for this. One: Long pages can be overwhelming. Two: Makes it easier to find, since each shorter page will appear in the menu on the left. Another example is Five little stories. They make a nice package, but page is very long. Better split into five pages?~
• ~The five little stories are really great as it nicely conveys insights about different samplers. I wonder if it would be beneficial to organize as five separate, shorter files, to keep more manageable and allow navigating them in menu?~
• ~Some titles long, look confusing eg chap 3 Sampling with CUQIpy: Two target … Short concise titles will make menu make clearly structured. (addressed partially #47)~
• ~Consider using Subtitle numbers e.g 3.1, 3.2 for parts of chapters/pages, to help organize and make it easy to refer to specific material by section number rather than only by a string heading.~
• ~I hadn't noticed the colours used for section and subsection headings and didn't realise colour had significance. Can see it is useful in the menu on the right for overview. Suggest to make the colours more distinct.~
• ~remove subheaders (e.g. 1.1., 1.2.) from the notebook content section at the beginning of the notebook and keep only the main headers (e.g. 1., 2., 3.) (partially addressed)~

DoD:

• [ ] The book is updated to address comments above (processed from #57)
• [ ] The updates are reviewed and merged

[amal-ghamdi]

@jakobsj, would you please review the DoD, I organized the comments from you into three groups. The top group I would like to address today along with #53 in one PR. Thank you. Also feel free to suggest moving the comments along the sections (needed now, easy, can wait)

[jakobsj]

@amal-ghamdi Looks good, approved. (one can always consider if there are other ways. The items are nicely split according to priority like this and will stay together for overview. On the other hand the issue can not be closed as done when only the "needed" ones are done, because the "can wait" ones are also kept here. But let's keep it like this and just focus on getting them done according to priority).

[amal-ghamdi]

@jakobsj , DoD updated based on the discussion today. remaining issues moved to #73