v0.3.0 - Block Maker

[pietroppeter]

Release notes (from changelog)

This release started with the aim of making the construction of custom blocks as easy as the construction of native blocks.
A wide refactoring of the codebase was required for this (#78)
and further adjustments were made along the way (#80, #81).
Some new blocks are introduced taking advantage of this (e.g. nbRawOutput, nbPython) (#80, #83).

Contributing to the codebase is made easier through introduction of proper testing (#80)
docs are now built in CI (#89, #90, #91) and deploy previews have been added (#92, #93).
Documentation has been updated to include all changes so far
and contextually the changelog has been updated (#103).

A big milestone is reached (#88) by introducing templates to add interactivity to documents
taking advantage of nim js backend (nbCodeToJs allows to incorporate javascript scripts in the document derived from nim code).
In particular templates to reduce boilerplate when developing karax based apps or
widgets are introduced (nbKaraxCode, karaxHtml).
Three new example documents are introduced for documenting this change (interactivity, counters, caesar).

Another major change is setting as default the CodeAsInSource introduced in 0.2.4
(a number of fixes are made: #105, #106, #108).

Most of these contributions are due to @HugoGranstrom
(thanks for all the awesome work on this ❤️) which joins @pietroppeter
as maintainer and co-creator of nimib! 🥳

List of detailed changes:

• refactoring of NbBlock type and rendering of blocks (Refactor nb blocks (fix #24) #78, fixes refactor rendering #24):
  • NbBlock type is completely refactored. Instead of having a kind with a fixed
    number of values, a block behaviour is specified by a command string
    which is set to the name of the command template used to create a block
    (e.g. nbCode, nbText, nbImage, ...) -
  • newNbBlock is now the main template to create a new block
  • Every block now has a context field and the rendering backend (either html or markdown)
    has a mechanism to retrieve a partial for every command.
  • as an additional mechanism to be able to perform other computations when rendering,
    a sequence of renderProcs can be assigned for every command (for a specific backend).
  • nimib / renders module completely refactored to take into account the above changes
  • some other accidental or not so welcome changes that happened during the refactoring:
    • sugar is now exported (accidental)
    • nb: NbDoc is mutated when rendered (unwelcome, will be changed later)
    • cannot use both Html and Md backend at the same time (unwelcome, will be changed later)
• logging has been improved (see changes in nimib.blocks.newNbBlock) (Refactor nb blocks (fix #24) #78)
• new main partial introduced (Refactor nb blocks (fix #24) #78)
• fixed cheatsheet document (Refactor nb blocks (fix #24) #78, fixes no html escaping in cheatsheet.nim #52)
• tests are added and ptest document is removed (Refactor nb blocks (fix #24) #78)
• aliases to minimize breaking changes that happened in 0.2 (nbDoc, nbBlock, nbHomeDir) are noew removed (Refactor nb blocks (fix #24) #78)
• added a new readCode: bool parameter to newNbBlock (with an overload that sets it as true) (A bit of everything related to v0.3 #80)
• new template nbRawOutput that renders raw html (A bit of everything related to v0.3 #80)
• new command nbClearOutput that removes output from last block processed (A bit of everything related to v0.3 #80)
• new templates for creating code blocks newNbCodeBlock and newNbSlimBlock
  for creating custom blocks and related changes (Release 0.3 #81):
  • newNbCodeBlock: captures source code of body
  • newNbSlimBlock: block without a body (and in particular no capture of source)
  • all nimib "native" blocks now use one of the two mechanism above
  • now nbText does NOT contain its source
  • new nbTextWithCode that does contain code source
• new example document files.nim, changed the rendering of nbFile
  (no more "writing file ..." only the name of file is added) (Release 0.3 #81)
• added loadNimibCfg proc that can be used for themes (used by nimibook) (Release 0.3 #81)
• added nbInitPython and nbPython templates to support running python in nimib documents using nimpy (nbPython #83)
  • md and fmd from nimib / boost now deprecated and replaced by hlMd and hlMdF
  • new hlPy and hlPyF in nimib / boost
• docs now are built in CI (Build docs in ci #89, Fix build docs in ci #90, Fix build docs in ci 2 #91)
  • sources of docs are now in folder docsrc
  • outputs are in docs
• add deploy preview through netlify (add netlify preview to CI #92, test and fix deploy pr preview #93)
• new templates to introduce interactivity in documents taking advantage of nim's javascript backend (Compiling nim to javascript #88)
  • nbCodeToJs: a block of nim code is compiled to javascript and added as a script to html file (and allows capturing of variables)
  • nbCodeToJsInit, addCodeToJs, addToDocAsJs: templates to allow splitting in multiple blocks the code in nbCodeToJs
  • nbCodeToJsShowSource: template to show the nim source of a nbCodeToJs block.
  • nbKaraxCode (with karaxHtml): template to create a karax app/widget with minimal boilerplate (based on nbCodeToJs)
  • new example document interactivity.nim: explains the basic of nbCodeToJs and related templates
  • new example document counters.nim: shows how to create counter widgets using nbCodeToJs
  • new example document caesar.nim: a caesar cipher app built using nbKaraxCode
  • new module nimib / jsutils to support the implementation of the above
• newId proc for NbDoc that gives a new incremental integer every time it is called (Compiling nim to javascript #88)
• CodeAsInSource is made default:
  • new nimibCodeFromAst flag to revert to old default
  • added a warning to nimibPreviewCodeAsInSource (now obsolete)
• various fixes to CodeAsInSource (Fix codeAsInSource #105, fix codeblocks starting with a block #106, fix newline at beginning of code block #108)
• changelog updated and separated from documentation (improving docs for v0.3 + fix markdown backend #103)
• updated documentation to include most recent changes (improving docs for v0.3 + fix markdown backend #103)
• turned off warning for unused imports in nimib.nim (improving docs for v0.3 + fix markdown backend #103)
• fix markdown backend, it was broken since html theme was overiding render backend (improving docs for v0.3 + fix markdown backend #103):
  • new nbInitMd to use markdown backend
  • new themes.noTheme for empty theme (used by nbInitMd)

Thanks to @metagn for improving our CI/nimble file! Every contribution counts!

Relevant examples of usage:

• nimislides: a new nimib theme that allows to create
  slides using reveal.js html presentation framework
• some posts in nblog are relevant example of new blocks and customization of nimib:
  • Making Diagrams using mermaid.js
  • Plotly in nimib

Following are the automatic release notes by Github

What's Changed

• Refactor nb blocks (fix refactor rendering #24) by @pietroppeter in Refactor nb blocks (fix #24) #78
• A bit of everything related to v0.3 by @HugoGranstrom in A bit of everything related to v0.3 #80
• replace nimble deps task with nimble install by @metagn in replace nimble deps task with nimble install #84
• Release 0.3 by @pietroppeter in Release 0.3 #81
• nbPython by @HugoGranstrom in nbPython #83
• Build docs in ci by @pietroppeter in Build docs in ci #89
• Fix build docs in ci by @pietroppeter in Fix build docs in ci #90
• Fix build docs in ci 2 by @pietroppeter in Fix build docs in ci 2 #91
• add netlify preview to CI by @pietroppeter in add netlify preview to CI #92
• test and fix deploy pr preview by @pietroppeter in test and fix deploy pr preview #93
• Compiling nim to javascript by @HugoGranstrom in Compiling nim to javascript #88
• make nimibPreviewCodeAsInSource the default and introduce flag nimibCodeFromAst for previous default, fix make nimibPreviewCodeAsInSource the default and add nimibCodeFromAst #94 by @pietroppeter in make nimibPreviewCodeAsInSource the default and introduce flag nimibCodeFromAst for previous default, fix #94 #96
• Fix codeAsInSource by @HugoGranstrom in Fix codeAsInSource #105
• fix codeblocks starting with a block by @HugoGranstrom in fix codeblocks starting with a block #106
• fix newline at beginning of code block by @HugoGranstrom in fix newline at beginning of code block #108
• improving docs for v0.3 + fix markdown backend by @pietroppeter in improving docs for v0.3 + fix markdown backend #103

New Contributors

• @metagn made their first contribution in replace nimble deps task with nimble install #84

Full Changelog: v0.2.4...v0.3.0

---

This discussion was created from the release v0.3.0 - Block Maker.

[pietroppeter]

very happy for the release and for @HugoGranstrom joining the team!

so, what's next? plan is:

• release a 0.3 nimibook:
  • add netlify PR preview nimibook#54
  • document recent changes and release 0.3 nimibook#51
• finalize update of scinim/getting-started to new release: Update to nimib 0.3 and nimibook 0.3 SciNim/getting-started#47 (comment)

after these I would like to:

• clean up a little bit the roadmap
• add a contribute.md (and possibly improve a bit more the docs), see: improve documentation (0.3.x) #110
• make a forum announcement post of 0.3. I never did a single announcement post of nimib, the closest I got was a mention for "this month in nim", I think 0.3 calls for it. Also because now nimib is in a much better place for getting contributions from others.

then the idea would be to enjoying the 0.3 and trying to add and improve stuff before breaking again and focusing more on creating blog posts and creating themes. Most of the priorities there will be set when updating the roadmap.

At some point it would be time to break again and the target is #111.
I would also take as a goal for 0.4 to move nimib and other nimib related stuff to a nimib organization (since I assume it will be a bit of a hassle I want to enjoy a little bit of peace before moving on to that).

Ah, the idea is also to use a little bit more this discussion forum, so let's hear it from all of you!

[HugoGranstrom]

I'm delighted to have the privilege to join the team :D Also using these discussion forums sounds like a great idea when there isn't a clear issue one can discuss in, like the general direction for the future as here. 👍

The plan sounds good, feel free to delegate specific tasks to me 😄

Enjoying it sounds like a good plan as well, it's summer after all 😎 🌞

And regarding announcements, now that 0.3 is released I should be able to announce nimiSlides formally as well. But I'll probably wait a few days after your's so the forum isn't bombarded with nimib news 🤣

[pietroppeter]

I think I will announce this nimib 0.3 soon on the forum, even if I have not completed the plan (which I will do when I have time). btw next two weeks I will be on holiday with limited internet reach (and no laptop)

[HugoGranstrom]

Go ahead, I'm still to start working on the announcement of nimiSlides so no stress. And have a really nice and relaxing holiday! 😄

[pietroppeter]

done: https://forum.nim-lang.org/t/9343#61336

[HugoGranstrom]

@pietroppeter You planned to do a NImConf talk about nimib if I recall correctly? Do you have a rough idea of what you want to cover? I'm tempted to do one on nimiSlides specifically, and its API and showcasing its feature in a more interactive way (show code and result in the same slide basically). I just don't want to steal any ideas you have planned for your talk, so might as well discuss this beforehand. I won't cover anything too nimib-specific like nbJsFromCode in any greater depth other than mentioning the typewriter effect is implemented in Nim using it. What are your thoughts?

[pietroppeter]

Hi, yes, I am planning to have a nimib talk about the recent changes. And I also wanted to hear from you. :)

The idea was to have:

• a brief recall of what nimib is about
• presenting all recent changes of 0.3, not going too much into details, mostly using examples
• discussing next steps, roadmap, possible contributions by others

Great that you are doing a presentation on nimislides.
And actually if you wanted to go into more details on the Js side or things you would be in a much better position than I am. :)

In fact one idea could be for you to join also on the nimib presentation, if you are interested. It might complicate a bit the managing on how to make it but it could be fun. Thoughts?

[HugoGranstrom]

The idea was to have:

That sounds like a good plan, it doesn't overlap very much at all with what I had planned :D

In fact one idea could be for you to join also on the nimib presentation, if you are interested. It might complicate a bit the managing on how to make it but it could be fun. Thoughts?

Ohhh, that would be an absolute honor! 🤯 It would require a bit of coordinating though, and figuring out how we want to practically record it. The easiest would be that we each record our own parts separately and then edit them together with a super cool transition. We would just have to make sure that the parts fit together. "And now I'll hand the presentation over to Hugo.", "Thanks Pietro, I'm Hugo Granström blabla", "And now back over to Pietro".
A more ambitious approach would be recording it together over Zoom of something, but I don't trust myself to be able to pull it off without a large number of retakes 🤣
It could be a combination as well, some part recorded together (intro perhaps?) and the rest separately.

I'm already getting stage-fright 😱 🙈

[pietroppeter]

It would require a bit of coordinating though

definitely! what if we try and have a chat some time this weekend? I will contact you on a private channel (mmh, discord?)

[HugoGranstrom]

Yes that sounds like a good plan 👍