add .dib notebook support

[Fxplorer]

I have really come to love the Polyglot Notebook of learning things. I am trying to incorporate documentation and to get FSharp.Formatting 'working'. It is rather confusing and daunting for the inexperienced. Doing notebooks is a great way to reuse exploration and then have documentation and Literate Programming options. The library is not supporting the .dib ms notebook version. It does markdown and the .ipynb formats. I created a couple test files (a .dib and a .ipynd) and the .dib seems to me to be mainly a markdown file with a starting command line and then the # lines denoting the blocks. My simple test files changed to markdown rather easily by hand. Going from code into .dib would also be awesome like it does with .ipynb.

I am trying to go from notebook -> .md and like #811 going from notebook to .fsx easily. One of the docs referenced that the .ipynb was converted to a .fsx and then to the html. Is that .fsx put to file or accessible to me as the user?? I am just confused enough in the whole cycle to determine this myself. It would be awesome if it is.

[nhirschey]

Thanks for the suggestion. I agree polyglot notebooks are quite nice.

This could be worth considering, though I’m not sure if the .dib file format will catch on. Is there a specific reason you are using .dib notebooks instead of .ipynb Polyglot notebooks?

At this point my guess is that .ipynb Polyglot notebooks will dominate. My understanding is .dib only exists for simpler .git diffs.

In visual studio code, if you use the polyglot notebook extension to save your .dib as .ipynb you’ll have all the same Polyglot notebook features and it’ll work with this tool for website documentation.

I am trying to incorporate documentation and to get FSharp.Formatting 'working'. It is rather confusing and daunting for the inexperienced.

Have you seen this guide? We could try clarifying any parts that are unclear. https://fsprojects.github.io/FSharp.Formatting/zero-to-hero.html

[Fxplorer]

This could be worth considering, though I’m not sure if the .dib file format will catch on. Is there a specific reason you are using .dib notebooks instead of .ipynb Polyglot notebooks?

Back when Polyglot notebooks were first introduced the (arbitrary) guidance was to use .dib unless one had a specific reason to use .ipynb which is longer and, for me at least, was unknown and hard to remember. I think the py for python put me off. Anyway, I think the main point was that the .dib did not save the outputs and so the files did not bloat in size and one did not have to clear the outputs upon saving if one wanted a clean notebook to execute upon the net open.

As a result, when I have done a notebook since then, I have done .dib format.

I have known that F# had this comment and markdown library but my attempts to use over the years have failed. This week, I had some downtime from working (my current career is not a programmer) and wanted to get the docs thing working. I keep doing "squirrel research", but have managed to learn a lot about getting fsdocs working. In the past week, I have done digging into fsdocs and reviewing the discussions and PRs concerning the notebooks support (and usage) and in looking at the raw files for each extension and see the different approaches on how it stores the info. In reference to a couple of the use cases described, I now understand where advantages can be had with the .ipynb and it saving the output wanted when converted to .html and the cool little dotnet-repl library. I think I am understanding the advantage of the nbconvert concept as well, and whether that should be part of FSharp.Formatting proper or its own library. The NBformat.net is still unclear to me where it fits in with where fsdocs and NBconvert should live, but that is another discussion.

[Fxplorer]

Have you seen this guide? We could try clarifying any parts that are unclear. https://fsprojects.github.io/FSharp.Formatting/zero-to-hero.html

I have seen that link several time and truly read it or looked at it until just before your reply. It was just a stupid mental thing. The title was long, I think I registered 'github pages' in it and my thought was that is not what I was looking for. I was inspired b the fsdocs init idea and posts and I started working on a notebook to create a getting started tutorial and then I actually looked at the link. Made me feel dumb for not looking at it before as I was basically recreating it! My suggestion would be to call out this guide specifically in the readme and index pages and maybe even put a new heading instead of documentation in the html left menu that would be like GUIDES or GETTING started or TUTORIAL or SETUP TUTORIAL or USAGE TUTORIAL. Just brainstorming there. Having my attention drawn to that HERE is where you get started using this yourself kind of indicator. I am willing to work that idea if given to nod to proceed.

Either way, I am planning to continue with my own tutorial write up and I am thinking to do a blog setup using the notebooks and fsdocs actually. I started one on hashnode but now I am seeing how doing the notebooks to html and fsdocs could be a less duplicate effort and that is actually where I want to get to. Explore requirements and development in notebooks and the documention converts to the final solution, like the nbdev idea someone mentioned in another post in here.

[nhirschey]

@Fxplorer there’s a discussion of .dib vs .ipynb motivation here https://github.com/dotnet/interactive/issues/467

@nojaf maybe we retitle zero to hero “getting started” and promote it to the first (index=0) documentation page, before “Command Line”? It’s a fair point that socially people expect the beginner docs to be one of the first links.

[nojaf]

Sure

[Fxplorer]

@nojaf maybe we retitle zero to hero “getting started” and promote it to the first (index=0) documentation page, before “Command Line”? It’s a fair point that socially people expect the beginner docs to be one of the first links.

That change is awesome! I feel that noobs like me will get a much better idea of what is going on with that.