Centralize package documentation about fable-compiler.github.io HOT 23 CLOSED

I am working on a prototype for the website and tooling around it.

I will create a PR/issue so we can discuss the features.

from fable-compiler.github.io.

I was thinking about this for a while now, a central website for the packages is definitely needed. I thought of having a JSON file with entries like this:

[
{
  "name": "repo",
  "description" : "summary of what this library does",
  "category": "general", 
  "tags": [ "unit-tests", "coverage"  ],
  "type": "pure", 
  "platforms": [ "browser", "node", "dotnet" ],
  "repo": "github.com/user/repo" ,
  "nuget": "nuget.org/packages/repo", 
  "license": "MIT", 
  "website": "user.github.io/repo" 
},

{
  "name": "repo",
  "type": "binding", 
  "original-library": "github.com/other-user/repoJs",
  "category": "general", 
  "tags": [ "unit-tests", "coverage"  ],
  "type": "pure", 
  "platforms": [ "browser", "node", "react-native" ],
  "repo": "github.com/user/repo" ,
  "nuget": "nuget.org/packages/repo", 
  "license": "MIT", 
  "website": "user.github.io/repo" 
}
]

Every entry is a package, packages can be either pure (like Thoth.Json) or binding (like Fulma).

Every binding package includes a link to the original library.

Searching is possible by name, category, tags.

Website loads README, total stars from github and total downloads / versions from nuget

Many people ask "is there a binding for library X?" then they should be able to put the link of the original library and see whether there is a binding for it or not.

Packages must specify on which platforms they run: some browser packages do not work by default in node environments.

Suggestion

Every searchable package must have a README and docs website with live examples if applicable (react bindings) As an incentive for library authors to write docs so that they can add their library to the central package docs

I am working on a template to make writing docs websites easier

from fable-compiler.github.io.

I have looked into docusaurus too and looks really good but I just couldn't find an easy way of writing a docs website where I could put live (elmish) examples and make it easy to work with markdown

from fable-compiler.github.io.

from fable-compiler.github.io.

@alfonsogarciacaro I admit it is waaay easier said than done but I was just entertaining the idea, put it in the distant-future bucket of nice-to-have's 😄

from fable-compiler.github.io.

Long time user of Haxelist here. Great package manager. Handle both officially released packages as well as git counterparts.

Regarding the list it would be great to have some authoritative system to gather all fable listed packages. But at first a simple markdown as you mentionned will be a good start.

from fable-compiler.github.io.

@whitetigle This is a very good point, but the problem of getting the correct npm packages versions should not really be a documentation concern (it helps of course to document them) but IMO it should be enforced by Fable. For example, how awesome would it be if you only install the Fable package from nuget and have Fable tell you:

Nuget package Fulma.Something requires something-js [1.0.0-1.2.0] to be installed, you can install it by running npm install --save [email protected] in your terminal

or even better, have Fable run the installation commands by itself!

@alfonsogarciacaro What do think of adding an entry in the project file of Fable packages

<NpmDependency>
  <Package>something-js</Package>
  <Min>1.0.0</Min>
  <Max>1.2.0</Max>
</NpmDependency>

Then have Fable check whether a "compatible" version is installed / present in package.json before starting compilation

from fable-compiler.github.io.

from fable-compiler.github.io.

Aside jokes, I think what @Zaid-Ajaj proposed would really be great.

Every searchable package must have a README and docs website with live examples if applicable (react bindings) As an incentive for library authors to write docs so that they can add their library to the central package docs

👍 I would add a proper LICENSE (whatever it is)

from fable-compiler.github.io.

@Zaid-Ajaj Sorry, but I'm not going to add any feature to Fable that makes it look remotely like a package manager, even if it's "just a wrapper" 😉 We shouldn't go down that 🐰 🕳️

from fable-compiler.github.io.

we're not aiming to create a full repository package, just a way so package authors can share some documentation that it's easier to search from Fable website

My proposition will consist on provide a search bar so people can type keyword/package name. The idea is just so people can type json for example, so they will see Thoth.Json, Fable.SimpleJson, XXX as a result and have a link to go to their documentation/repo.

Adding metrics is out of my scope for now because it make things more complex and also for now, all we be stored in a single json as we don't have a backend, database, and co.

I want to keep things simple for now, and see if people really find this project useful and use it before investigating lot of effort and ressources in it.

from fable-compiler.github.io.

It would get all relevant Nuget and NPM packages and we would drink 🍾 on a remote 🏖 while watching all this done automatically and forget all about .Net.

@whitetigle I guess you could start looking for a remote 🏖 because a blog post is coming up with a solution for this exact thing 😉

from fable-compiler.github.io.

Hi all! For now I've just put up a simple community resource finder: https://fable.io/community/

It'd be great if you could start adding your awesome resources to the community.json file. Thank you!

from fable-compiler.github.io.

Thank you @alfonsogarciacaro for making it happen ❤️

from fable-compiler.github.io.

Wow, you're already working on a template for docs? 😮 I was currently looking at Docusaurus (what ReasonML uses) for that.

from fable-compiler.github.io.

Yeah but this is very specific for writing docs websites of individual packages

It is basically a small elmish app with a simple navigation module, turns static markdown files into react markdown components. Layout and structure is very similar to gitbooks but with the ability to add pages from react components so that you can add live examples.

code looks something like this:

let render state dispatch = 
  match state.CurrentPath with 
  | [ "index" ] -> Markdown.markdown (importAll "./docs/index.md") 
  | [ "examples"; "first" ] -> 
    div [ ] [ 
      Markdown.markdown (importAll "./docs/first-example.md")
      exampleOfComponent state dispatch
      Markdown.markdown (importAll "./docs/explain-first-example.md")
    ] 

CurrentPath reflects the tree structure of the sidebar, and yes, there has to be manual editing in the fsharp code to make it work

from fable-compiler.github.io.

@Zaid-Ajaj regarding the JSON structure, how would we resolve npm packages if any are needed? For instance, for Fulma's extensions? With the name field?

[Edit]: I mean, wouldn't it be be great to have links to npm package(s) used by the library?

from fable-compiler.github.io.

or even better, have Fable run the installation commands by itself!

😆 @alfonsogarciacaro I told you this morning: just a wrapper 😉

from fable-compiler.github.io.

Having a fable install Fulma command would so cool!
It would get all relevant Nuget and NPM packages and we would drink 🍾 on a remote 🏖 while watching all this done automatically and forget all about .Net.

Wouldn't it be wonderful? cc @forki 😜

from fable-compiler.github.io.

Also, before starting a new package repository, it could be important to consider what happens when a package goes "rogue". A good analysis of the current situation for npm can be found here : https://hillelwayne.com/post/stamping-on-eventstream/
I believe most of it is also relevant to Nuget.

I just wants to point out that if we start recommending packages, it also a good thing to think on how we will "un-recommend" packages.

from fable-compiler.github.io.

You are right @rfrerebe my plan is to allow people to mark a package as Obselete and allow them to provide a string or list of package to replace it.

I am still working on the first draft of the app, I am just sick at the moment so it's kind of paused..

from fable-compiler.github.io.

That's a good point and a great article @rfrerebe, thank you! Something to have in mind, but please note we're not aiming to create a full repository package, just a way so package authors can share some documentation that it's easier to search from Fable website.

About recommending one package over another, this can be a bit sensitive in the case of two similar packages from different contributors, but we can add some metrics for users to decide (number of downloads, GH stars). We can also add a way to mark packages as obsolete (or maintainers can just put that in the package description).

from fable-compiler.github.io.

🏖 🍾 😎 is perfect for me 😉

from fable-compiler.github.io.