Join GitHub today
GitHub is home to over 40 million developers working together to host and review code, manage projects, and build software together.
Sign upD2.14: Demonstrators: Interactive textbooks: Problems in Physics with Sage and Computational Mathematics for Engineering #39
Comments
This comment has been minimized.
This comment has been minimized.
Hello everyone! The link to the poll: https://framadate.org/tfuHjZgcSU8pHI45 |
This comment has been minimized.
This comment has been minimized.
I have read through the current file, made some minor editions and added some TODO's. Thanks much @fangohr and @marijanbeg for your more than timely contribution! |
This comment has been minimized.
This comment has been minimized.
Hi @marcinofulus, |
This comment has been minimized.
This comment has been minimized.
Salut @ocayrol, |
This comment has been minimized.
This comment has been minimized.
Hi,
I will be working on the report today. Out textbooks are being finished,
first 2 are on my github, the 3rd will appear in few days. There is mostly
work on text going on, while key ideas and code are already there.
BTW, I have "stolen" the bookbook idea from Hans, which is nicely simple
(originally I wanted to make rst/sphincs/ipynb combo).
mk
…On Sun, Aug 25, 2019 at 11:34 PM Nicolas M. Thiéry ***@***.***> wrote:
Hi @marcinofulus <https://github.com/marcinofulus>,
We urgently need your contribution: description of your textbook and
elements of discussion based on your experience, so that the report can
then be made into a single coherent whole.
What's your time line?
Thanks in advance,
—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub
<#39?email_source=notifications&email_token=AAJDC5UPUXSQV3TW6QFCV53QGL3HDA5CNFSM4BPHFDVKYY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOD5C4IDA#issuecomment-524665868>,
or mute the thread
<https://github.com/notifications/unsubscribe-auth/AAJDC5T265KODMJ2COSOYV3QGL3HDANCNFSM4BPHFDVA>
.
--
Head of Department of Computational Physics and Electronics
Institute of Physics
University of Silesia
ul. 75 Pułku Piechoty 1A
41-500 Chorzów, Poland
tel. +48 32 3497 612
http://icse.us.edu.pl
---------------------------
Linux: because rebooting is for adding new hardware.
|
This comment has been minimized.
This comment has been minimized.
I will be working on the report today.
Great, thanks!
Out textbooks are being finished, first 2 are on my github, the 3rd
will appear in few days. There is mostly work on text going on,
while key ideas and code are already there.
Cool; please add links from the abstract.
BTW, I have "stolen" the bookbook idea from Hans, which is nicely
simple (originally I wanted to make rst/sphincs/ipynb combo).
Ok! Definitely something that should be discussed in the section of
the report about authoring tools and their pros and cons.
|
This comment has been minimized.
This comment has been minimized.
Bringing here a piece of conversation from D2.9 #49: We should have add "interactive books" to our online use cases section, with references to all the interactive textbooks that we authored (and possibly others too). This would be a natural place to disseminate the discussions from this report: merits of interactive textbooks, available tools, best practices, etc. There are two options to achieve this:
It feels like the latter will make the information easier to discover for potential authors, and have some more chance to keep evolving later on (e.g. addition of more references? of an authoring tutorial? of a cookie-cutter?. What do you think? |
This comment has been minimized.
This comment has been minimized.
I am preparing a cookie-cutter with all problems and solution in book-book workflow |
This comment has been minimized.
This comment has been minimized.
Good morning @marcinofulus |
This comment has been minimized.
This comment has been minimized.
The abstract from D2.9 #49 is presumably a good starting point. |
This comment has been minimized.
This comment has been minimized.
I worked on cookie cutter now, and I will also write a short subsection on it. |
This comment has been minimized.
This comment has been minimized.
Ops - I just overlapped my push with your comments 29min ago. - |
This comment has been minimized.
This comment has been minimized.
No problem; this is bound to happen when 20 people are banging hard together:-) |
This comment has been minimized.
This comment has been minimized.
> about live cells in the HTML export
I did not try. It could be possible in principle, if all cells per
page are linked. But I like the idea that the whole notebook is
available in e.g. binder for running and in pdf for reading. Set of
notebooks is easier to maintain and extent - and it is the main
advantage of this solution.
Yes, for serious reading, live notebook (e.g. in binder) or pdf is
best. Having -- in addition -- a live HTML export is nice for the
casual reader that stumbles on one page and just wants to briefly try
out something.
(I am not sure what you mean by "all cells per page are linked". You
mean can be run with the same kernel?)
|
This comment has been minimized.
This comment has been minimized.
yes - usually in sagecells I tries to aviod dependences, notebooks on the contrary are considered generally to be a one program (by me I mean) |
This comment has been minimized.
This comment has been minimized.
Did you review 3rd perspective ? |
This comment has been minimized.
This comment has been minimized.
@nthiery I am handling todos now... |
This comment has been minimized.
This comment has been minimized.
@nthiery I am handling todos now...
Great. Let me know when done, and I'll review all at once.
I now see what you mean about linked cells. Yeah, this may influence
the style of writing indeed.
|
This comment has been minimized.
This comment has been minimized.
@nthiery was sagemath/sagemath:latest docker image done by ODK? |
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
I have updated https://github.com/OpenDreamKit/authoring_cookie_cutter, mentioned in - it implements workflow without notebook output cells in git (also no nbval). |
This comment has been minimized.
This comment has been minimized.
I have just reviewed the document, extracting an abstract in the github issue above. Altogether, it's very close to be ready. |
This comment has been minimized.
This comment has been minimized.
@ocayrol: please see if you could contribute some of your insight on the Sphinx vs Notebook authoring workflows: OpenDreamKit/WP2/D2.14/report.tex Line 374 in 7fa8f33 |
This comment has been minimized.
This comment has been minimized.
@marcinofulus: there are still a few questions from the original task that are not addressed in our report; see the github issue description above. Can you see what can be done? |
This comment has been minimized.
This comment has been minimized.
@IzabelaFaguet: please proofreading the whole text. |
This comment has been minimized.
This comment has been minimized.
I think that they are answered indirectly, but of course I will try to make it more direc. |
This comment has been minimized.
This comment has been minimized.
I added some direct answers to monograph questiom I think also that there is already answer on collaboration (github vs email to github operator;). |
This comment has been minimized.
This comment has been minimized.
@nthiery , I think that now questions are addressed. |
This comment has been minimized.
This comment has been minimized.
I made a few minor proofreading edits. |
This comment has been minimized.
This comment has been minimized.
@embray thanks!, |
This comment has been minimized.
This comment has been minimized.
Thanks @marcinofulus for the last touches. |
This comment has been minimized.
This comment has been minimized.
Well, almost; for some reason, it was due M47. Good enough :-) |
This comment has been minimized.
This comment has been minimized.
Good that I checked a last time my e-mail in my tent before going to sleep :-) @marcinofulus, @fangohr: thanks for the report which will be a useful read for future authors too. Four textbooks that is, while exploring and demonstrating ODK technologies; pretty cool! Thanks a lot for all the work; @marcinofulus: you'll congratulate all contributors in Silesia on my behalf. With a thought for Jan. I am looking forward a use case section on interactive text books! |
This comment has been minimized.
This comment has been minimized.
The use case section should mention jupyter-book as well (book authored in notebooks + markdown; export as static web site with Jekyll, with download links, in the work ThebeLab support, etc.). Originates from the Data 8 course. |
Interactive tools have always been an attractive tool in education, engaging the student to learn both by theory and by practice, to immediately test their understanding, and to explore around the material, all at their own pace.
In Task T2.9, we explored different approaches to authoring and distributing interactive textbooks using the Jupyter toolkit. In D2.9 (#49) we reported on the writing of two interactive books. There, the books were authored as structured text files in the ReST document format, and exported as interactive html pages or pdf, using the
Sphinx
documentation system and thesage-cell
interactive html page technology.For this deliverable, we proceeded with two additional interactive textbooks:
https://github.com/marcinofulus/Mechanics_with_SageMath
https://github.com/marcinofulus/Dynamical_Systems
https://github.com/marcinofulus/Transport_Processes
https://github.com/fangohr/introduction-to-python-for-computational-science-and-engineering
There we explored an alternative approach: the books were authored as collections of Jupyter notebooks, and exported as notebooks, html or pdf.
In this report, we set the stage by describing the benefits of (Jupyter-based) interactive textbooks from the learners and authors perspective, and review our two new interactive text books; we then discuss the workflows we explored, their relative merits, and some best practices to enhance quality and maintenability. We present a template abstracted away from our books that enables new authors to kick-start the writing of their own book. We conclude by highlighting the ease of distribution of interactive textbooks thanks to the Binder Virtual Environment. The table of contents of the two books is provided in the appendix.
Altogether, this demonstrates that the OpenDreamKit efforts, notably T4.1 (#69), T4.3 (#71), T4.6 (#74), and T4.8 (#76) contributed to lower barriers for including computations in science education while significantly improving the maintainability of such interactive materials by proper use of automated validation.