Prepare for teachbooks v0.2.0

[rlanzafame]

Should be only small changes related to external content and teachbooks package in general

Issue #132 created to make sure the way caching works is properly defined and assign it to @Tom-van-Woudenberg

[rlanzafame]

@Tom-van-Woudenberg I still miss a space dedicated to the teachbooks package and i think it would be good to include it in this PR since we will then be telling people to consider use of the external content feature which relies on teachbooks.

Can I add something general back in?

It won't be long, I think the key things it should do in the manual are:

1. point out that it exists
2. list the features that are incorporated in it
3. provide very simple guidance on how it should be used, and by whom (i.e., if you are using GH online don't worry, etc)
4. the feature button on a page where the feature is implemented in teachbooks can link back to the new description

I think it kind of makes sense as a subpage to the overview page, but I can also see it being a subsection on the overview page. What do you think?

[Tom-van-Woudenberg]

@Tom-van-Woudenberg I still miss a space dedicated to the teachbooks package and i think it would be good to include it in this PR since we will then be telling people to consider use of the external content feature which relies on teachbooks.

With #121 we effectively splitted the teachbooks package in the manual in it's different functionalities (which makes sense as it's part of the features part). That these features happen to be part of the teachbooks package might be a bit irrelevant for most readers.

Can I add something general back in?

If you feel there's a need for it, go ahead.

3. provide very simple guidance on how it should be used, and by whom (i.e., if you are using GH online don't worry, etc)

Isn't this already described at the pages of the individual features?

I think it kind of makes sense as a subpage to the overview page, but I can also see it being a subsection on the overview page. What do you think?

I don't immediately know where it should be placed. Maybe the best place would be the teachbooks readme itself (so not in the manual). I'm not that fond of a subpage of the overview page: I think it might be a confusing structure. Maybe the best place is indeed a subsection of the overview page, which would also allow us to explain the other types (what is a sphinx extension, iframe, got reusable action, etc.)

[rlanzafame]

@Tom-van-Woudenberg last commit is WIP so don't worry about content too much. just checking if you are ok with a teachbooks page at the end of the Part (instead of a subsection on overview page). this prevents the link from breaking. i think this is the best way forward since i can't think of a way to get the teachbooks.md page to build automatically without having it in the TOC and without messing with the autobuild command. there is in default JB the exclude pattern thing to NOT build pages...but in this case what i need is and include page. maybe an idea for a new future feature?

[Tom-van-Woudenberg]

teachbooks page at the end of the Part (instead of a subsection on overview page).

@rlanzafame, I'm not sure about whether it makes sense to place this as a separate page. For inexperienced users the feature part is now ordered based on functionalities, 'teachbooks python package' might be unexpected. Maybe we can place this as a chapter on the overview page (that's what I meant with subsection) and make a teachbooks-page under the current URL which just redirects to that chapter? I've created a separate pull request (to merge into this one) for it: #143

I think we have to accept that this URL is broken, as the broken URL is less important than a layout that makes sense for inexperienced users

[Tom-van-Woudenberg]

A few comments, see general comment on broken URL thing...

[Tom-van-Woudenberg]

We have never warned people about updates and relevant caching in the past for the other tools (which are no different in this perspective).

Maybe this warning shouldn't be in the manual, but only in the announcement on teachbooks.io. Or we could remove the warning after a week. I think it can be kinda complicated for some users and giving the explicit explanation might do more harm than good on these very-easy-to-implement feature pages

[Tom-van-Woudenberg]

'We do not expect it to cause issues with existing books, but if it does, you can use the following in your requirements file: teachbooks<0.2.0.' If we really don't expect it, couldn't we just leave this out?

[rlanzafame]

Good points, I'll adapt this and get back to you once I have a chance to read the stuff in #132