First of all: sorry if I post too much about these projects I do? I am just having lots of fun coding in Crystal 
So, what is Crycco? It’s a Crystal sort of reimplementation of Docco which is a literate programming tool.
For the under-50 crowd: Literate programming is the idea that instead of having two things: a program and its documentation, or even a program from which you extract documentation, you could extract the program from a narrative document
Perhaps the best way to explain this is to point you to Crycco’s website which is generated by processing Crycco’s sourcecode using Crycco 
9 Likes
Bro, I absolutely love this. I actually REALLY needed a tool like this for writing better explanations of software I’m using to teach someone Crystal. You definitely found a user today
Enjoy release 0.1.0!
It even has static binaries for down load
I like the literate programming. It’s hard to get a same file format serve for two different purposes. What do you think of this other approaches I describe next?
From what I can grasp you extract from the comments the content for the explanation, because the file is a valid crystal source.
Another alternative would be to make the files first an explanation (like markdown) and extract the crystal source from it. This will give you better tooling for documenting, but worst tooling for programming. Unless the compiler makes this file a first class citizen.
The crystal play supports using .md files directly. And each code section will be interpreted as its own crystal program. This is not enough for what you are trying to do but can be close in some cases.
When I was playing with icrystal last year I found that using (vscode/ python) notebooks can give you more flexibility than the playground. But still you have some restrictions. Each cell needs to be a self-contained statement. You can’t break class/method definitions.
Alloy supports actually this pretty well. You can load a Markdown file, and it will treat the concatenation of all alloy code blocks as the source file.
For a main crystal file this is easy to simulate. You can generate that. But with multi-files project is harder unless is backed in the compiler. And then you need to deal with tooling: formatting crystal code in markdown, showing errors with markdown location file information, etc.
It also supports extracting the code from a document using the --code option on a “literate” file.
For example if you have foo.cr.md it will consider it as a markdown file where indented blocks are crystal, and can generate either html or crystal source code.
And yes, nowadays, when tooling and IDEs are much more advanced than in the literate programming heyday (the 80s!!!) you are missing out on a lot of things when you go the “literate document with code” path instead of the “source code with comments” pathm which is why the latter approach is more common.
Notebooks seem to be an exception but they encourage a (IMHO) horrible programming style where the code is decomposed into a bazillion cells, and then (worst of all) executed out of order by randomly clicking on things, causing things to be hard to reproduce and impossible to debug.
Version 0.2.0 is out which is more or less feature complete for what I wanted.
It adds a sidebar with all the documents, it preserves the input’s folder structure and fixes some bugs in the CSS and HTML (like, the background doesn’t break when horizontal-scrolling anymore)
Static binaries in the GH release page which are totally self-contained, you don’t need templates or anything.
1 Like