fable-compiler / fable-compiler.github.io Goto Github PK

During the rework, I mostly copy/pasted information from other pages into this one. But I don't think this page is really useful in the state because it is really complex and could be better structured.

I can only see the "Home" menu item.

In the Getting started page (http://fable.io/docs/getting-started.html), the snippet for downloading the Fable template for dotnet core looks wrong (it doesn't work for Mac and Linux).
On the site the snippet is:
dotnet new -i Fable.Template

Error: Package "Fable.Template" is not a valid package specification

while it should be:
dotnet new -i "Fable.Template::*"

Should be based on JavaScript Features page content.

See how Python has been adapted for an example.

When you are currently stuck with something in Fable and the docs don't cover your problem your goto is the gitter channel.

This is great because generally there is always someone there and the community is wonderful.
However I think it would be nice if we have some sort of FAQ page and instead of answering the same questions in gitter all the time.

The same idea could be helpful for the elmish site as well.

See REPL

This documentation seems to be missing: https://github.com/fable-compiler/Fable/blob/master/src/dotnet/dotnet-fable/Server.fs

Upon successful merge to the main branch, there could be an action triggered whenever there is a new commit to that branch. It could then build and deploy the site to the github pages environment. That would speed up updates to the site.

Any thoughts? Happy to help, although I believe I need more permissions to do this myself.

I believe this is because we're missing the responsive tag:

<meta name="viewport" content="width=device-width, initial-scale=1">

I cannot find an HTML template in the repo so I guess it's in Nacara? Can we add the responsive tag to the default layout there? @MangelMaxime

Wonderful blogs are not linked now. Please update them.

This is going to be a long post, but I think that it should be worth reading.

Recently, I have started learning F# and have noticed that some libraries (including this one) have poor documentation. This includes the outdated content, missing documentation and terrible styling. I don't want to sound negative, but this can be improved a lot.

My background is mainly PHP and JS, so examples of good documentation would be:

• https://laravel.com/docs/8.x
• https://vuejs.org/v2/guide/#What-is-Vue-js
• https://reactjs.org/docs/getting-started.html

Something similar to F#/Fable scenario:

• https://rescript-lang.org/docs/manual/latest/introduction
• https://guide.elm-lang.org/

Then, I have read the documentation of these language and they have something special:

• Elixir https://hexdocs.pm/elixir/Kernel.html
• Go https://golang.org/pkg/

They use valid code to generate documentation, api documentation and valid examples.

This got me thinking that I read somewhere while learning F# that for comments you can use XML and something something it can be parsed (way above my head). Then I have stumbled upon a tweet from Don Syme that he has recently pushed a commit to a tool called:

https://fsprojects.github.io/FSharp.Formatting/

This is the first line on that page:

F# Formatting: Documentation Tools for F# Code

Upon reading about it these are my opinions:

• This should be used by every F# library
• The default styling should be improved
• This tool should have better documentation :)
• F# Formatting is a terrible name for something like this :) How can you say to someone: "Use F# formatting to generate API documentation for you library."
• The great thing about this library is that inside it you write valid F# code which you can execute and test. This is far better than any PHP/JS documentation. I think that having this means that writing documentation is now fun.
• Option to include markdown files into documentation is great for text heavy pages where there is not a lot of code
• Having the package generate API documentation is a huge time saver and promotes writing good comments.

In conclusion,

let's not reinvent the wheel. There is a package which exists and works made specifically for generating F# documentation. We should use it for everything F# related.

The majority of pages currently on Fable.io website can be moved to that package. I don't know the amount of comments that there are in the code of Fable itself, but I assume that it can fetch the namespaces and functions. I'm going to try to use F# formatting with the main fable repository to see what I get and then try to moved content from this website to that documentation.

I repeat, I don't want to be negative or say bad things about months of work that went into this website (so I have heard), but this can be improved further.

My opinions here are true for other package which I have used so far (Feliz, Fable.React). What is the deal with double scrollbars everywhere :)

but... Alfonso is currently sleeping (or at least pretending) and I wanted so much to improve Fable web site with Fulma in Full Wondercolors.

But I ran into 3 problems:
1 - I'm a little bit tired because of vodka and loud music coming from my German friends upstairs
2 - I get this strange error which I tried to understand but due to my currently very limited non-MVP powers I can't solve.

[0] fable: Compilation succeeded at 01:58:52 (21.126 s)
[0] TypeError: (0 , _Navbar.root) is not a function
[0]     at render (C:\Users\conta\Documents\workspace\fable-compiler.github.io\build\Main.js:66:210)
[0]     at renderHomePage (C:\Users\conta\Documents\workspace\fable-compiler.github.io\build\Main.js:131:3)
[0]     at Object.<anonymous> (C:\Users\conta\Documents\workspace\fable-compiler.github.io\build\Main.js:135:1)
[0]     at Module._compile (module.js:652:30)
[0]     at Object.Module._extensions..js (module.js:663:10)
[0]     at Module.load (module.js:565:32)
[0]     at tryModuleLoad (module.js:505:12)
[0]     at Function.Module._load (module.js:497:3)
[0]     at Module.require (module.js:596:17)
[0]     at require (internal/module.js:11:18)

The third problem is obviously the most important one.

I am working on a Dutch national pediatric emergency app to provide ready to use interventions in case of medical emergencies, i.e. it shows the calculated interventions according to age and weight. This might be a very nice show case of the use of Fable for real life working apps.

Furthermore, this app needs to be certified according to the European Medical Device regulation and this means very strict quality requirements have to be met. So, this will need some solid financing as well.

As this project heavily depends on Fable, I would like to cooperate and to support Fable as this will have a direct impact on the project I am working on. Please inform to get in touch.

P.S. And of course the project could be an excellent showcase of the use of Fable and F# in general, along with Feliz, and the SAFE-stack initiative.

Hi,
on https://fable.io/resources.html the link for "bulma-timepicker"
incorrectly links to https://github.com/rfrerebe/fable2-samples/tree/master/minimal

The documentation for TypeScript's features currently ends in the tagged union section with what appears to be a partial implementation of how unions can be implemented in order to resolve to TypeScript interfaces. However, the code for this section seems to cover only the F# portion of declaring the union types and a method that consumes them without the expected generated TypeScript output.

The example here should likely be completed with comments to demonstrate the capability.

Is there a reason why dotnet tool install fable is not mentioned in the docs?
Or did I not find it? e.g. on https://fable.io/docs/2-steps/setup.html ?
I only read about it here: https://fable.io/blog/Announcing-Nagareyama-4.html

Not sure if this is the right place, but it would be great to have an RSS feed or similar for the Fable blog.

Hello! Just a simple question.

I recently introduced Fable to our company's tech stack. When going through the technical review board process, I was asked how we would know if a vulnerability was found - i.e. are there any bulletin boards, feeds or web pages that we should keep an eye on?

I know it seems like an odd question, especially given that this is a compiler rather than a runtime library, but because we are a bank the infosec requirements are quite tight!

My guess was that if you needed to get a notification out to all users it would be here on Github somewhere and possibly also X / Twitter?

When you go to the documentation, there is no link available to go back to fable.io

Possible scenario:
User clicks the link 'docs' to find a specific topic, but does not find it there and wants to go to the blog instead.

Executing this scenario is now not possible

http://fable.io/api

404
File not found

Apologies if this is not the correct repo to raise this issue. If it's not, please point me in the right direction.

https://fable.io/docs/2-steps/your-first-fable-project.html

This page tells me to run the command dotnet new fable-react-elmish, but I believe it should (now) be dotnet new fable-elmish-react, i.e. the order of the words "react" and "elmish" is wrong.

The new banner on the home page is great, but when you go to the blog section there should be a minimized version of it instead.
Users go to the blog part to read the entries and now that is barely visible on the screen:

I don't think this is in the Fable docs; it would be very useful to have!

When writing custom bindings for JavaScript libraries, I often refer to https://medium.com/@zaid.naom/f-interop-with-javascript-in-fable-the-complete-guide-ccc5b896a59f. There are a few reasons why this isn't ideal:

• It's not as easy to find as it would be if it were in the Fable docs. Newcomers likely don't know it exists.
• It was written in 2017. I don't know whether there have been later changes to Fable which add more alternatives with different tradeoffs.
• It's more verbose than I'd like for a reference (which makes sense - its purpose is to teach, not to be a reference).

A page in the docs would be easier to find, provide more confidence that it's up to date and could be more focused.

https://github.com/fable-compiler/fable-compiler.github.io/blob/dev/docs/docs/getting-started/python.md

not very clear, maybe we need to make it shorter but clearer, also not specified that one has to pass the --lang py argument to dotnet fable command unless checking the cli help

List of libraries already quite long, not full and slightly hard to navigate.

@delneg already created new list of categorised libraries - https://github.com/delneg/Fable-useful-resources

I think would be nice to merge it with official documentation. As an option it can be new Libraries page near the Resources.

@fable-compiler/documentation what do you think?

https://twitter.com/OnurGumusDev/status/1333364233782833152

While revamping the site and moving to a new domain, it may be a good idea to simplify the generation of the website and its different section, for better maintenance and to make it easier for contributors to focus on different parts. I've already cleaned up this repo but the build process still depend on other repositories to generate the documentation. Maybe it's a good idea to move each section to a different repo and don't worry about having a unified look. An initial proposal could be:

• Keep this repo for the landing page. Then we can focus on have an attractive design with useful information to get started.
• Separate repository for the REPL: already done!
• Move docs to a different repo and use gitbook to build them. This gives us a nice and practical format which developers are already used to and it can make contributions easier.
• Move the blog to Medium? This can also increase Fable visibility among people visiting Medium.

Thoughts? @whitetigle @MangelMaxime

@dbrattli @ncave @alexswan10k @MangelMaxime

I think we'll need to replace/add a Feature/Language matrix to this page so users know what it's supported and what not in each language: https://fable.io/docs/dotnet/compatibility.html

I'm thinking of something similar to the picture below, with language targets replacing the browser and without version numbers:

The current doc also lists the type equivalence in generated code. Maybe we can keep this when there's a corresponding native type and skip it when it's a custom type from fable-library. If there are some particularities we can include them as footnotes below as it is in the "Caveats" section.

If it looks good to you, I can try creating the table and then I will ask you to fill it for Rust and Python 👍

I've bought the fable-compiler.com domain, we should move everything as we've lost control of the fable.io domain and we don't know how long we'll be able to use it. We also need this to use HTTPS.

I nominate @whitetigle as the chief of operations for this as we already had some discussions about it :) We want to have a transition phase where users going to fable.io are redirected to the new domain (or at a minimum, a web is displayed showing the new url).

The thing is, I don't know if we can point the fable.io domain to another repository at this point. So we may need to keep this repo as is and create a new one for fable-compiler.com. Or is there any other solution?

The main problem of keeping this repo for fable.io is we don't get automatic redirections for fable.io/repl2 and such.

Now that the new Fable docs are available at https://fable.io/docs/, some URLs scattered around the Web are broken. It would be nice to provide a way to redirect requests for the old URLs to go to the new URLs, perhaps keeping the same fragment identifier in the rewritten URL.

For example, https://github.com/fable-compiler/Fable/blob/8f10128dbd6e0d7c648dd9fd97eef028b337bf36/src/Fable.Core/Fable.Core.Types.fs#L101 mentions the URL http://fable.io/docs/interacting.html#Erase-attribute in a comment. That content is now at https://fable.io/docs/communicate/js-from-fable.html#Erase-attribute, so it would be nice if http://fable.io/docs/interacting.html#Foo would redirect to https://fable.io/docs/communicate/js-from-fable.html#Foo for all values of Foo. (Some headings in the old document may not have corresponding headings in the new document so some of those fragment identifier redirects might be broken, but in that case it would just go to the top of the page, so nothing is lost by trying to preserve the fragment identifier.)

Here is how it is done in the original Fable awesome repository:

https://github.com/kunjee17/awesome-fable/blob/master/.travis.yml

I think we just need to setup a workflow with ruby installed to install the awesome_bot and the command line.

It should be based on JavaScript section by replacing the examples with Dart code, adding specify Dart interop and removing interop not supported by Dart.

See how Python is organised compared to JavaScript.

Qt is an open source library collection.

Javascript supports the whole set of it and QML is one of the diamonds in this toolset.
It is possible to use JS and QML in order to develop native desktop and phone applications.

Supported platforms are Android, iOS, macOS, Wayland, Windows, X.org and a bunch of others:
All that with one and the same code.

Those applications are inherently GPU accelerated, scale automatically to the used screen size and can delight our eyes by smooth animations.

It's possible to code the logic with JS and then use the WYSIWYG designer in Qt Creator to design the UI:
So you dont even need to code for the UI.

You call it by Qt Quick 2 JIT and you can compile it into C++ with the superb Qt Quick Compiler.

You can do pretty much all the IO in Qt.

In order for React Fast Refresh to work, files must include only one JS export. This means you should only expose one functional component (decorated with Feliz.ReactComponent or JSX.Component) and the rest of the code in the file must be private.

@alfonsogarciacaro

I think the "files must include only one JS export" is incorrect.

At least when using Feliz + Feliz.UseElmish, you can have several exports.

From my tests and understanding, the limitation for React Fast Refresh is that only ReactComponents should be exposed from the module.

So you can do stuff like:

type Components with

    [<ReactComponent>]
    static member AnErrorOccured = // ...


    [<ReactComponent>]
    static member AnErrorOccured(title: string, subtitle: string) = // ...

Example taken from Fable.Packages.

I'm having an issue that Fable compilation is failing with an error that it can't find Fable.Helpers.React

So I found this page at https://fable.io/blog/Announcing-Fable-React-5.html
but have noticed that there isn't any publication date written anywhere on that page.
So I don't know how relevant that blog post is (fwiw it might have been years old information).

Please include a publication date on Blog-post pages.

I want to move as many packages as possible out of the fable-compiler org, but at the same time it's good for users to have a central page where they can see the main packages of the ecosystem at a glance and learn a bit about them. Currently we have the awesome-fable list, but it may not be enough.

Elm packages is a great reference and we could build something like that. Probably for now we can just have a list with links to a markdown file (like the README) and the build script in Fable website will just fetch and format them.

This doesn't mean packages cannot have their own site. They can link to it from the markdown.

What do you think? @MangelMaxime @et1975 @Zaid-Ajaj

Hi dear maintainer,

I just wanted to see how this nice website is created, npm install fails,

and the output looks like it depends on python or can't be build on win32.

It is not important for me, but a little comment here would come via PR to the readme, and avoid this experience to other's

Thanks for the nice website, cheers Frank

First things first, the summary of changes in fable-compiler 2.2 is as follows (full change list here):

The here link (https://github.com/fable-compiler/Fable/blob/635c0379d12ca7348b394310256105e56240408c/src/fable-compiler/RELEASE_NOTES.html) gives me a 404