Comments (6)
@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.
Related Issues (20)
- Directory.Build.props is ignored if there are no projects or solutions HOT 3
- SEO-optimization for new theme HOT 4
- Suggestion: init command
- Dark mode borders: too much contrast?
- Namespace description overflows content box
- Output font size on mobile safari is too big HOT 6
- Using testcontainers in a fsx script gives wrong output HOT 7
- Create a keyword/glossary site map
- --watch expectation HOT 1
- Suggestion: auto-expansion of `<details>…</details>` for direct links HOT 12
- Can FSharp.Formatting support documenting programs? HOT 1
- Enable `watch` server from arbitrary host HOT 4
- Is it possible to generate an HTML AST from Markdown? HOT 1
- Nesting Document Categories HOT 1
- Include images in documentation in generated content HOT 17
- Use signature-like for documenting the API HOT 6
- Making a change to `content/fsdocs-default.css` cause an infinite update loop
- Use `Ctrl+C` instead of allowing any key press to kill the process
- Replace `ApiDocMemberDetails` union with a record
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from fsharp.formatting.