Dynamic Code in Library Documentation

[tajmone]

In order to ensure that library excerpts, code examples and their transcripts provided in the documentation will always mirror the current status of the libraries and latest ALAN compiler, we need to adopt the "Dynamic Examples and Transcripts" approach described in the Dynamic Examples article on the ALAN Docs Wiki.

This technique has been successfully adopted for quite some time in the StdLib project (see AnssiR66/AlanStdLib#82), as well as in the Beginner's Guide in the ALAN Docs project.

The main challenge here is to implement it via Rake, whereas so far this has been handled via Bash scripts (and SED) tailored to the needs of each document.

Ideally, we'd like to create a "universal" Ruby module for Rake that simplifies adopting this approach in any repository, but this might require some careful thinking because this techniques also requires:

• Adding AsciiDoc region-tag comments to ALAN sources and solution files (so they leak into the transcripts).
• Sanitizing the library and documentation sources before including them in the final distribution package (currently done via SED to strip away lines with region tags, as well as operating AsciiDoc formatting operation on transcripts before their inclusion in the AsciiDoc sources).
• Including the examples sources and their transcripts among the Rake dependencies for the documentation tasks, as well as having to add to transcripts as file tasks that need to be rebuild when their solution files or ALAN source (and library dependencies) change.

So, there's quite some research and trial work to be done before we can come up with a reusable Ruby/Rake module that could be shared efficiently with all ALAN projects. We'll probably have to define some standard conventions to be adopted by projects who wish to use this system, and to created highly customizable tasks via task parameters or Ruby methods parameters that are flexible enough to handle to different use cases.

Also, in order for project that are already using this system, we'll also need to provide a task for handling "package deployment", i.e. being able to create sanitized copies of the ALAN source in some destination folder (usually ignoring files that begin with underscore, which are reserved only for internal documentation use, and not intended for end users).