add .dib notebook support about fsharp.formatting HOT 6 CLOSED

@Fxplorer there’s a discussion of .dib vs .ipynb motivation here dotnet/interactive#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.

from fsharp.formatting.

@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.

from fsharp.formatting.

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

from fsharp.formatting.

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.

from fsharp.formatting.

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.

from fsharp.formatting.

Sure

from fsharp.formatting.