Centralize package documentation
alfonsogarciacaro opened this issue · 23 comments
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
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.
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
Wow, you're already working on a template for docs? 😮 I was currently looking at Docusaurus (what ReasonML uses) for that.
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
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
@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?
@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.0in 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
or even better, have Fable run the installation commands by itself!
😆 @alfonsogarciacaro I told you this morning: just a wrapper 😉
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 😜
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)
@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 🐰 🕳️
@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 😄
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.
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.
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..
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).
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.
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 😉
🏖 🍾 😎 is perfect for me 😉
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!
Thank you @alfonsogarciacaro for making it happen ❤️