Hi,
We are happy to announce a new leap of GToolkit Documenter, the tool for
manipulating live documents directly in the development environment:
https://github.com/feenkcom/gtoolkit-documenter
Documenter is part of the second generation GToolkit project, it is based on
Bloc and works with the latest Pillar. It is mainly developed by Juraj Kubelka.
Attached you can see a preview of how documents look like:
At its core it offers a live editor for manipulating Pillar documents. The
interaction happens seamlessly directly in the text editor, and it can be
combined with different types of previews to serve several classes of use cases:
• code documentation
• tutorials
• interactive data notebook
Code documentation
----
Documenter complements the GToolkit Examples engine to redefine code
documentation. When practicing example-driven development, examples get written
as part of the typical development. Once examples exist, they can be quickly
put together in a document to form documentation. For example, the linked
picture shows the comment of a class containing a visual explanation:
https://twitter.com/feenkcom/status/973899862482866176
You can see a live example of documentation by inspecting the following snippet:
GtDocumenter editorForText: BrToggleExamples comment.
Tutorials:
----
Documenter offers a new experience of writing tutorials for Pharo by enabling
the creation and embedding of Epicea change sessions directly in the document.
For example, take a look at the following animation:
https://twitter.com/feenkcom/status/999975333972541440
The document shows a method on top, and a change preview at the bottom showing
both the code and the associated diff to the state from the image. Applying the
change updates both the change view (no more diff), and method preview. This
speeds up significantly the process of going through a tutorial. Furthermore,
given that now the document shows the diff to the current image, the reader can
safely explore alternative scenario and come back to the tutorial at any time
without losing the overview.
The size of the preview can also be adjusted live:
https://twitter.com/feenkcom/status/1001152789874167808
https://twitter.com/feenkcom/status/1001407762285375490
You can see a live tutorial by inspecting:
IceRepository repositoriesLocation / 'feenkcom'/ 'gtoolkit-examples' /
'doc' / 'tutorial' / 'examples-tutorial.pillar’.
Interactive data notebook:
----
A Documenter document can also be used as an interactive notebook. Internally
it essentially acts as a playground:
• it supports defining variables in code snippets, and
• the execution of code shows an embedded inspector.
For example:
https://twitter.com/feenkcom/status/996310432225820672
https://twitter.com/feenkcom/status/1002851190475026432
An example, can be seen by inspecting:
IceRepository repositoriesLocation / 'feenkcom'/ 'gtoolkit' / 'doc' /
'gtoolkit' / 'gtoolkit.pillar'.
As always, please do let us know what you think.
Enjoy,
The feenk team
--
www.tudorgirba.com
www.feenk.com
"If you can't say why something is relevant,
it probably isn't."
