Allow to embed the output of the F# code about fsharp.formatting HOT 11 CLOSED

Hmm, that is quite some suggestion, I like the idea :-).

I was playing with some recent work of Dave Thomas (here) and I think this would actually be quite doable...

from fsharp.formatting.

As you know, I am interested in using/working on this so I can finally get rid of my horrible hack to generate FsCheck documentation with code output in it (I committed this horrible hack a while ago because I was changing the output format fairly frequently, and keeping the docs up to date was such a drag.)

Anyway I have skimmed the code and got the tests working etc, making small changes here and there, but haven't made a lot of progress besides coming up with an initial design, wondering what you think.

These are just what I see as the atomic building blocks - other things like inline output as in #62 can be built on top.

I'm introducing the define-eval command which indicates we can use its output somewhere. Also I'm introducing include-value to include the value of a snippet defined by define-eval, and include-output to include the output. Example:

(***define-output: pie ***)
let pi = 
    printf "Coffee"
    System.Math.PI

(** The value of pi is *)
(*** include-value: pi ***)
(** Maybe you'd like something else with that: *)
(*** include-output: pie ***)

Which would produce:

The value of pi is
3.14...
Maybe you'd like something else with that:
Coffee

I've checked that Foslyn allows you to disambiguate between value and output, so that should be fine. Also typically you probably want to show a snippet and its output right after each other, but commands for that could be built out of the above, I think.

Thoughts?

from fsharp.formatting.

This sounds great - if you had time to add this, that would be wonderful!

On the usage side, I like the idea of having (*** include-value: value-name ***) and (*** include-output: snippet_id ***). That's pretty much what I had in mind when thinking about this too. I see that this also means adding (*** define-eval: snippet ***) so that you can refer to snippets in the include-output command. So the design looks good to me!

As for the implementation, I did some initial refactoring to make this doable (in 8c3f90b). The idea is that markdown documents (defined in Markdown.fs) can now contain special markdown elements (namely MarkdownEmbedParagraphs and MarkdownEmbedSpans). These can contain additional information about formatted code snippets & inline code snippets (used currently), but they would be a good way to add special FSI evaluation commands (I think!).

Currently, the extensibility is used in Literate Document.fs to define LiterateParagraph - this captures various code snippets (formatted F# snippet, inline snippet in other language, hidden snippet, reference to earlier snippet for rearrangement). The document, with special literate extensions is produced in ParseScript.fs and ParseMarkdown.fs (which does not handle F# code snippets).

Once we have the AST, the transformations in Transformations.fs take care of removing all special elements and replace them with ordinary markdown or inline LaTeX/HTML.

I actually added Evaluation.fs with the idea of implementing the transformation that evaluates all F# code snippets (snippet by snippet) and then includes the output - so I guess this is where you could start (after adding the new block definitions to the AST).

from fsharp.formatting.

Great, that is very helpful.

Somehow in my initial exploration I found all the pieces except the crucial parseScriptFile method in ParseScript.fs, which seems to tie everything nicely together. Some pieces of the puzzle are falling in to place. Will keep you updated ;)

from fsharp.formatting.

Cool, let me know if you need any more help - GitHub has been spamming me a lot lately, so perhaps tweet me to make sure I reply soon :-)

from fsharp.formatting.

I have a first cut which seems to sort of work: https://github.com/kurtschelfthout/FSharp.Formatting/commit/0f266745ab3f32e598db25699a0ae23e7c266bc9

There is some work left - stuff I can think of:

• the whole unparse thing and evaluating in the Transformations file is not exactly pretty. However I currently don't see a good way to it without changing CodeFormat deeply. Am I missing something? I think it can be cleaned up a bit though.
• No Latex support, but should be easy.
• is putting pre around the output and the values good enough?
• evaluation needs to be opt-in explicitly, don't want anybody to fire the missiles accidentally while generating documentation.
• I need to do a bit more comprehensive testing, wanted to start converting part of FsCheck's docs to give it a good test drive.

In the mean time, comments very welcome!

from fsharp.formatting.

Great work! This looks fantastic! I cannot wait to start using it :-)

• unparse - yes, this is a bit silly, but I think it's OK. We could change CodeFormat to keep the original source around (but that does not really makes such a difference).
• regarding formatting - emitting <pre> is a good start - in the longer term, it would be nice if the caller could specify how to format objects - e.g. I could format Deedle frames as tables and F# Charting charts as images - but having just the output in the first version will certainly do! This can be added later.
• Yes, I think making this opt-in would be a good choice. I would probably add an optional parameter to ParseLiterateScript (and similar) - these call the transform function (here) which could then run the transformation on the document if this is enabled

from fsharp.formatting.

Ok, I cleaned up and made evaluation optional. https://github.com/kurtschelfthout/FSharp.Formatting/commit/9cb9cafae1d0adb04ccd085c81a7336e96714425

Slightly better, at least the evaluation now happens in parse, instead of WriteHtml.

I like your idea of allowing custom formatters. But I'll leave that for later or someone else.

I'll try to convert the quickstart from FsCheck tonight - hopefully a PR will be coming your way in the next few days!

from fsharp.formatting.

Excellent - thanks a lot for looking into this!

I'll wait until you use this with the FsCheck documentation - if that works, then I think we have a good proof that it works nicely and can merge it into the master :-)

from fsharp.formatting.

To keep the story going :) I have found an issue: hidden code is removed from the LiterateDocument (in ParseScript.transformBlocks). But of course fsi needs it to correctly evaluate the whole thing. Quite confusing to figure out what was going on. I'll have to move things around a little.

from fsharp.formatting.

I'm closing this as done (see http://tpetricek.github.io/FSharp.Formatting/evaluation.html).

There are probably a couple of other things to be added on top of what we have now, but I think that should be a separate work item.

from fsharp.formatting.