Centralize package documentation

[alfonsogarciacaro]

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

[whitetigle]

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.

[Zaid-Ajaj]

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

[alfonsogarciacaro]

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

[Zaid-Ajaj]

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

[Zaid-Ajaj]

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

[whitetigle]

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

[Zaid-Ajaj]

@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 something-js@1.0.0 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

[whitetigle]

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

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

[whitetigle]

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 😜

[forki]

Yeah would be wonderful. Am Mi., 14. Nov. 2018, 16:25 hat Whitetigle <notifications@github.com> geschrieben:

…

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 <https://github.com/forki> 😜 — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#32 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AADgNP-s0yh1P3TqLp6yoyUd3ulpJdDTks5uvDXigaJpZM4YcrZE> .

[whitetigle]

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)

[alfonsogarciacaro]

@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 🐰 🕳️

[forki]

Yeah you will always have to play catch. Am Do., 15. Nov. 2018, 10:45 hat Alfonso Garcia-Caro < notifications@github.com> geschrieben:

…

@Zaid-Ajaj <https://github.com/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 🐰 🕳 — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#32 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AADgNHY9dFYbUInliEWFvqUXTB1z7COAks5uvTeygaJpZM4YcrZE> .

[Zaid-Ajaj]

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