search

fsprojects / FSharp.Formatting

F# tools for generating documentation (Markdown processor and F# code formatter)
https://fsprojects.github.io/FSharp.Formatting/
Other
462 stars 155 forks source link

Ipynb input #874

Closed nhirschey closed 7 months ago

nhirschey commented 7 months ago

Fixes #806. This code should be independent of everything else; only gets triggered on .ipynb input files. Could merge this into the modern theme branch for alphas or wait and merge into main after modern theme is complete.

The general strategy is to convert a notebook to markdown and then pass that markdown through FSharp.Formatting's existing markdown tools.

Parsing: This uses a custom parser to read notebooks as json. I tried using .NET Interactive's parser, but it requires mapping their undocumented internal C# classes to F# and at the end of the day it was easier to do the parsing from scratch.

Evaluation: relies on dotnet-repl, a personal project of someone on the .NET Interactive team. As recently as August they recommended it for commandline execution, so let's use it. The downside is that users must install this extra tool, but I don't think it's a big burden.

One thing @kMutagene, we have to decide what happens when we evaluate a notebook. What I did was have fsdocs --eval trigger dotnet-repl on the actual source notebook in the docs folder. This means that evaluating docs will change the content of the source notebooks (for example dotnet-repl puts some additional metadata in cells indicating time of execution). This seemed reasonable for now.

Testing: I added tests, but one thing I couldn't test well was dotnet-repl evaluation. I couldn't get the test project to evaluate the notebooks using dotnet-repl. Maybe test projects cannot call external dotnet tools? I don't know. I left the test in there but it's commented out.

nhirschey commented 7 months ago

Sounds good, I'll bump the alpha release when I merge.

Thanks for the code review and all your work on the modern theme. You've done incredible work the past month!

nhirschey commented 7 months ago

@nojaf, just to double check that I don't mess up any of your in-progress work. Are you ok with this being merged into main now? I'm done and I've updated release notes to bump the release

nojaf commented 7 months ago

You've done incredible work the past month!

Why thank you 😊

Are you ok with this being merged into main now?

Yes, go for it!

jonsequitur commented 5 months ago

Parsing: This uses a custom parser to read notebooks as json. I tried using .NET Interactive's parser, but it requires mapping their undocumented internal C# classes to F# and at the end of the day it was easier to do the parsing from scratch.

If there are changes you'd suggest making to Microsoft.DotNet.Interactive.Documents`, please let us know. Ideally you'd be able to use this effectively from F# without needing to duplicate the effort.

jonsequitur commented 5 months ago

Evaluation: relies on dotnet-repl, a personal project of someone on the .NET Interactive team. As recently as August they recommended it for commandline execution, so let's use it. The downside is that users must install this extra tool, but I don't think it's a big burden.

I'm the owner of dotnet-repl. It's intended as a prototype for command line functionality that could find its way into the core of .NET Interactive. I'm glad you're finding it useful. I'm also more than happy to work with people on contributions to it.