Considering better documentation tooling about fable-compiler.github.io HOT 38 CLOSED

@alfonsogarciacaro @ncave

I think you should read this issue and share your opinion, feedbacks, ideas, etc.

Also pinging:

• @dbrattli because you are an active contributor of Fable with your Python port right now and others libraries :)
• @whitetigle if you are still around as you wrote a lot of the new Fable docs

from fable-compiler.github.io.

In fact, I will ping more people: to have more feedback from SAFE stack maintainers, long time Fable/F# users and contributors to different tools around Fable ecosystem.

@Zaid-Ajaj @humhei @isaacabraham @theimowski @Krzysztof-Cieslak @forki

If you think we should ask more people please feel free to add them.

from fable-compiler.github.io.

I finally have a showcase that I can share:

Everything is powered by Nacara meaning that everything is a markdown/html file.

The main page of Fable has been completely rewritten:

• It now use at 99% Bulma components instead of having a lost of inlined style and patches.
• Doesn't have layout flash/resize as all the element already have their place reserved

The advantage of using Bulma at maximum is to have a consistent style across all Fable website.

I still have a bit of work to do before sending a PR so you can have a better look at it:

• Fix the copy button when there is only one line in a snippet
• Add the blog pages
• Improve a bit the mobile layout of the main page especially the first section

We will not have the API section at first but it is still plan for the future.

from fable-compiler.github.io.

Thanks @mabasic for all for opening the issue and for your comments. Yes, we've probably spent too much energy creating our own tools (even if that was good dogfood) instead of improving the actual content. It'd be good to refocus from now on. Not sure what would be the perfect tool, although I believe the main issue is the lack of contributors. I myself spend less time writing docs than I should, my attention deviates too easily towards fixing bugs or adding new features. The current website and docs just happened thanks to @whitetigle 😄

So any help with the docs and website would be greatly appreciated. Some random ideas:

• I don't have a strong opinion about tooling, anything that lowers the entry barrier to contribute would be great. When I used FSharp.Formatting in the past (the first version of Fable website used it) I found that it required complicated build scripts that broke quite easily. But it's been a while so maybe it has improved now.

• In any case, I would scope any improvements efforts to Fable website and documentation. Trying to make the documentation of all Fable packages consistent would be too much. We already have two competing sites to list the ecosystem (fable.io/community and awesome-fable) and none is very actively maintained 🤣

• Add a Twitter feed to the website? Most of Fable-related news are announced there so we can avoid the copy and pasting (maybe we could even try to write a bot to automatically update community.json from Fable tweets).

• Better synergies with the safe-stack? They already have great documentation, so an option could be to just integrate the docs and avoid duplicating efforts.

from fable-compiler.github.io.

It's btw interesting to see the similarity between FSharp.Formatting and Jupytext for Markdown encoded Jupyter notebooks. Would be great to open F# documentation directly as a notebook (as well as a web-page). For Jupytext you can have both Markdown with code blocks or code with markdown comments. Sorry for some Python examples:

percent-encoding:

 %% [markdown]
# ### Assign a function to a variable

# %%
multiply = lambda a, b: a * b


# %%
def add(a, b):
    return a + b

adding = add

markdown

### Assign a function to a variable

`` `python
multiply = lambda a, b: a * b
`` `

`` `python
def add(a, b):
    return a + b

adding = add
`` `

from fable-compiler.github.io.

I am a big fan of https://docusaurus.io to use for both the landing page, the blog, the showcase and the docs

from fable-compiler.github.io.

Not sure what would be the perfect tool, although I believe the main issue is the lack of contributor 💯

from fable-compiler.github.io.

Simple and effective.

Perfect for me. And honestly, maybe the best option today to make people add doc and links to samples and unit tests until someone can devote his/her time updating it regularly. Then the people responsible for the docs will decide what to do just like we did when we decided to give nacara a go. That's very easy really. That's what I meant when I wrote I do not care. I do care about the documentation since I remember the time and energy it took to make it. But I do not care about the tooling used as long as it's simple and convenient enough to make people submit 100 PRs every day 😉

from fable-compiler.github.io.

FSharp.Formatting is a great tool, once upon a time I've used it generate sources with intellisense tooltips for my gitbook.

FSharp.Formatting was actually used for documenting most of the F# projects back in a day - if you search a bit you'll see that e.g. Paket, SQLProvider or FsUnit all use same template for docs - FSharp.Formatting and some probably even ProjectScaffold.

I think that it lost a bit of attention when there was a longer period of no updates (around 2016-2019) which overlapped with the rise of .net core and Fable - that's probably one of the reasons why few new F# projects nowadays employ FSharp.Formatting.

It's a bit of shame though, as @mabasic pointed out - there are many benefits in using this library for documentation, specially things like static checking of docs samples being up to date.

As for SAFE docs, they could also benefit from using the library, but we currently just do plain markdown there.

from fable-compiler.github.io.

Seems you can embed a twitter feed for a specific profile so we can control what's in it (basically, everything tweeted and retweeted from FableCompiler account). I've added it to the website, how does it look? https://fable.io/

from fable-compiler.github.io.

I've been researching documentation for a PHP package that I am working on and have found myself in the same situation there. There is phpDocumentor (equivalent to FSharp.Formatting) but there is very little resource on how to do stuff other than generating API documentation. I think that this is better done in FSharp.Formatting.

Other options are:

• Docute (Vue + markdown) This is simple because we add markdown files and it generates beautiful documentation on the fly.
• Docsify (vanilla JS + markdown) This is also simple for the same reasons as above, but uses vanilla JS meaning that it is much lighter.
• Docusaurus (React + markdown) as @Zaid-Ajaj mentioned This is more complex to setup but has extra features like a landing page, documentation and blog.
• VuePress A lot of packages from the Laravel ecosystem use this.
• Plain markdown in GitHub. It has table of content now so that is nice. We could keep the fable.io website as is and move the docs to markdown files in the repository or we could go all in on markdown and move everything to plain markdown on GitHub. There is always GitHub wiki option also.
• Nacara is a F# solution. Current documentation is written using this if not mistaken. It is not bad. The benefits of continuing using Nacara is that it is F# and improving it improves the ecosystem. In my opinion it just needs a few tweaks. Currently I'm having issues opening the documentation on mobile in edge browser and other small things.

I'm leaning towards continuing using Nacara but improving it and making it match the rest of the website. There is no reason to discard work that has already been done. It needs to be improved upon. Is everyone ok with this?

I will also spend some time thinking about how to add documentation for other fable related packages. Maybe using plain markdown in the readme of the package would be enough. Currently fable-react and fable-fetch are unusable. There is very little to go on there. Rescript has rescript/react documentation in the same place: https://rescript-lang.org/docs/react/latest/introduction

I will rethink the structure for the documentation. I find that rescript and elm have nice structure and are well organized.

FSharp.Formatting would be nice but it does not offer things that the current website has like the blog and community etc.

Non related. The other thing that I talked about regarding central place for all F# package documentation. I still think that FSharp.Formatting is the way to go. I will be opening a issue there to discuss that topic further.

from fable-compiler.github.io.

I agree with what you are saying @cartermp

Now that I released Fable.Form, I will work on cleaning a bit the repository to have a single too for the different section of the documentation. It will have the benefit of making it streamline what needed to be edited for which section of the documentation.

Then I plan to check how to call fsdocs/FSharp.Formatting (especially FSharp.Formatting.CodeFormat) to integrate it into the documentation as it seems this package is available to extract the information and process them outside of F# formatting. I know Fornax is doing it for example.

from fable-compiler.github.io.

Hello @mabasic,

thank you for initiating this discussion.

In the past I tried to use FSharp.Formatting and it was breaking really easily especially with the switch from .NET to NetCore. Also not all the features where working or required specific condition.

The pros I see in FSharp.Formatting is the same as you, the fact that you can validate your documentation by running it through the compiler meaning that it will (in theory) automatically detects API changes etc.

The main cons, I see is that it is another thing to configure, maintains and make it evolves in the time.

For the history:

In the past, I was one of the person we wanted to have full control over the documentation of my project that's why I decided to create Nacara but now I realize that I would prefer to loose a bit of possibility to just focus on writing the documentation.

Currently, for my projects, I am experimenting with Gitbook, which is used by Elm or The Elmish book. It is not perfect but it get the jobs done and provide an "ok" thanks to their new approach in v2.

There is also another to consider in this discussion. Which ever solutions we choose to use, the core maintainers of Fable are the ones who are going to have to maintain it/fix it in case of problem.

What I mean by that, is that since the creation of Fable, is that we had a lot of contributors and that's something wonderful but often people contribute on a period of time and them didn't have the time/energy to continue (that's totally normal :) ). So, what ever solution we choose we need to be sure we can make it evolve and live on the long term at a small cost.

from fable-compiler.github.io.

I think for now we can gather feedbacks from different experimentation and the communities to help make a list of possibilities.

We also need to understand what we is good about our current documentation and what is bad. Without that, we will not be able to focus our effort.

There is also the need to list the different project we want to document, where to store the documentation. For example, should the "core" library of Fable supported by the main maintainer be documented on the main site.

Should they have their own website documentation etc.

from fable-compiler.github.io.

The main cons, I see is that it is another thing to configure, maintains and make it evolves in the time.

I can agree with this to a degree. This got me thinking. I really need to explore elixir docs and packages more.

Take a look at this:

https://hexdocs.pm/ - this page holds all the documentation for every package available for elixir.

When you find a package you get this:

https://hexdocs.pm/ecto/Ecto.html

When you view the source code for that you can see that it uses something similar to F# formatting:

https://github.com/elixir-ecto/ecto/blob/v3.6.1/lib/ecto.ex#L1

This is what F# formatting (terrible name) could bring to F# ecosystem.

I haven't found anything similar to this in F#, but since the library for this exists I think that this would be super nice to have.

Rough idea

Since I don't know much of how things work in .net ecosystem I assume that there is a way to get all packages from nuget which are for F#, then we can use once instance of F# formatting to generate documentation for every F# package there is. We would of course have to tell people to place the docs in /docs directory. We could even include the README.md from every package. And one extra benefit is that we would get the API for that package for free.

Now imagine that you have a website called fdocs.org or something like that as we can point new users to browse documentation there for every F# package there is. That would take the work from package maintainers to this one single F# application which would generate the documentation for every package.

The package maintainers could then in their README.md or repository website point to the URL on fdocs.org for package documentation. Everyone benefits.

@MangelMaxime What do you think about this?

Currently, for my projects, I am experimenting with Gitbook, which is used by Elm or The Elmish book. It is not perfect but it get the jobs done and provide an "ok" thanks to their new approach in v2.

Gitbook is great, but I am not a big fan on relying on third party services for something that should be long term. Sure the md files would be kept in the repository, but this would have to be setup for each library.

from fable-compiler.github.io.

There is also the need to list the different project we want to document, where to store the documentation. For example, should the "core" library of Fable supported by the main maintainer be documented on the main site.

My comment above solves this since the documentation for every package would be automatically created without almost any work from the package author. He could only have code comments, or a single readme file, or additional docs in the docs/ directory. He could provide a logo and etc.

from fable-compiler.github.io.

From what I see hex.pm is the equivalent to nuget.org or npmjs.com.

It is possible to create something like that for example https://www.fuget.org/ shows that. However, it is not a simple task to do something like that.

One of the problem you will face is adaption both because existing project already have their own documentation and perhaps the maintainer don't want or doesn't have the time to make the change.

Some others questions that can be asked are:

• Who will take the responsibility to support such a project?
• Who will pay for the infrastructure?
• How can we guarantee long term existence?

I am not at all saying this is not something that should happen. I would probably love to see such a project. For example, elm have it via https://package.elm-lang.org/ , erlang via https://hexdocs.pm/, etc.

But I think that their are well integrated into their ecosystem and for example elm has been think with package.elm-lang.org in mind since the beginning.

If something equivalent can happen to F# it would be awesome.

You are kind of speaking about F# project now and not just Fable. Perhaps, you should try to open a discussion on FSharp.Formatting to propose your ideas/visions and see if others adhere to the ideas and perhaps want to join you on this project.

Gitbook is great, but I am not a big fan on relying on third party services for something that should be long term. Sure the md files would be kept in the repository, but this would have to be setup for each library.

In general, I am not neither but when you have a limited work force/time then you have to make a trade-off. From what, I see, if Gitbook where to disappear it would not be difficult to use the registered *.md file to generate an equivalent website as an escape way.

from fable-compiler.github.io.

I'll open an issue there to discuss that project there. In my opinion the cost of the infrastructure should fall on the foundation since that would be the central place for F# documentation.

Regarding adoption. That would not be an issue. If you publish a F# package on nuget its docs would automatically be published on fdocs. The package author wont have to do anything extra if he does not want to. He can have documentation in:

• the readme file
• in docs/directory
• his own website
• in code comments
• it should all work seamlessly

I need to explore if nuget already has something for documentation built in.

If the foundation can't support this then we could rely on free tier services to build upon a thing like that.

Regarding Fable and its documentation.

These are the things that I will try:

• clone this repo and see what can be done.

• try to setup F# formatting and see what I can get

• if the two attempts above fail I will try to use a simple approach with markdown files and see how that feels.

There are many solutions for using markdown files and generating pretty html documentation that don't require much upkeep.

I am still in favor of F# formatting because there are so many benefits that come with it.

Imagine if F# formatting would look and feel like gitbook. There would be no excuse to not use it.

from fable-compiler.github.io.

Yes, I think the combination of F# and .NET Core / Mono have made doc tooling e.g FSharp.Formatting and DocFx difficult for a very long time. Many of us have struggled and given up, including myself. Especially for mixed language libraries (C#/F#). But the dust may have settled so perhaps it's time to give it another go.

from fable-compiler.github.io.

Regarding Fable and its documentation.

Today: markdown all the way on my side or anything so that could the doc be updated fast without struggling with complex build systems or added CLIs or lib dependencies or not so clear fake/fsx scripts or anything that would undermine all the motivation from good willing people. So the best of all: no build system at all. Update directly from Github.

Now if fable was backed financially and had an official doc maintainer then any doc building system would fit, of course using f#. 😉

Regarding any other F# lib/project

Whatever suits the author. Honestly, I don't care.

from fable-compiler.github.io.

Not sure what would be the perfect tool, although I believe the main issue is the lack of contributor 💯

I think that this is the same as the chicken and the egg question. Is the documentation bad because of the lack of contributors or is there a lack of contributors because of bad documentation. I think that this issue can be disregarded.

In my experience better documentation leads to more people willing to start using the product.

In this particular case of Fable documentation, if I was a beginner programmer and my first experience with Fable documentation was this, I would not have been even able to start a project.

from fable-compiler.github.io.

@alfonsogarciacaro Just a few comments to your comment.

• Add a Twitter feed to the website? Most of Fable-related news are announced there so we can avoid the copy and pasting (maybe we could even try to write a bot to automatically update community.json from Fable tweets).

I'm not for having a twitter feed on the website. Anybody can tweet anything and tag fable, resulting in that tweet being in the twitter feed on the homepage.

Regarding community.json,

I have seen the discussion leading to the creation of community.json from a few years ago... Is this not more/less the same: https://www.nuget.org/packages?q=Tags%3A%22fable%22

Instead of manually adding things to community.json, you could have just used nuget to fetch all F# packages with a tag "fable". Maybe you are doing this already, I'm not sure.

There is a question is building something like that even necessary when I've managed to get all nuget packages related to fable and elmish on this page: https://www.nuget.org/packages?q=Tags%3A%22fable%22+elmish

• Better synergies with the safe-stack? They already have great documentation, so an option could be to just integrate the docs and avoid duplicating efforts.

One could argue that safe-stack documentation is too complex and outdated. I've read a few complaints that the docs are saying one thing for an older version, but when you start the template you get different instructions for a newer version.

They are using mkdocs, which is basically markdown to html with a maybe custom theme.

I am still gathering feedback and suggestions on this topic. I'm reading a lot of old issues, experiencing documentation websites around F#, experimenting with code and trying to generate a plan of action, so that I can propose it here. There is a lot going on on the current fable website so I need to soak that in in order to propose something.

from fable-compiler.github.io.

Regarding any other F# lib/project

Whatever suits the author. Honestly, I don't care.

@whitetigle It is your right not to care about what others do, but as a F# community "we" need to lead by example. I consider Fable as the main package for JS development with F#. Meaning that people who write Fable binding and packages will look up to Fable's documentation.

If upkeep is to be avoided, I am more than fine with having all the documentation in the README.md file in the repository. It really can't get simpler than that.

Look at this documentation:

https://github.com/joy-framework/joy/tree/master/docs

Simple and effective.

One thing that bothers me here is that F# has FSharp.Formatting. From reading the docs it should be very simple to get it started and published to Github pages. I still need to test this so that I can report my experience with it.

from fable-compiler.github.io.

@theimowski I've just checked the links you've sent and the documentation for those looks very nice and consistent. Are the docs using a custom design than the default FSharp.Formatting or are they using an older version?

I'm liking the sidebar to the right and that it is not a separate scroll section.

from fable-compiler.github.io.

I think it's the old default FSharp.Formatting design, there are slight customizations, e.g. here for Paket

from fable-compiler.github.io.

Seems you can embed a twitter feed for a specific profile so we can control what's in it (basically, everything tweeted and retweeted from FableCompiler account). I've added it to the website, how does it look? https://fable.io/

I liked it better without the twitter feed 😅

To be honest, the actual website for fable is awesome. Home page is great, repl is awesome, blog is fine but could possibly be moved somewhere else or stylized better. Docs look completely separate from the rest of the website (because they are). Fableconf is an entire different website in a subfolder and for some reason it has double scrollbars one next to the other. This could maybe be moved somewhere else.

I'll try to do some minor tweaks there and send screenshots.

from fable-compiler.github.io.

@dbrattli Don't know much about Jupyter notebooks, must research.

from fable-compiler.github.io.

@alfonsogarciacaro This kind of embeddings seems blocked by ad blockers like UOrigin which makes it looks strange:

I don't know if we can detect that and revert to the old layout in case of ad-blockers.

Docs look completely separate from the rest of the website (because they are).

Well both the docs and the main website is using Bulma as the CSS framework so it should be easy to change the brown orange to blue to get a uniform themes.

Which lefts the navbar to style/organize. I don't think the exposed feature of Nacara via the navbar.links property can achieve that.

However, Nacara is totally customisable and it is possible to use another layout than the default one referenced here.

From here, there is 2 solutions use F# and borrow the code from Nacara/Layout/Default.fs or use raw JavaScript to write the layout function example.

Borrowing the F# code Layouts/Standard would be much easier to do because there is a lot of specificities to handle like correct link generation, creation of special element to register next / previous navigation, inclusion of scripts needed to handle the menu, TOC, Scroll to top button, etc.

from fable-compiler.github.io.

Thanks @mabasic for all for opening the issue and for your comments. Yes, we've probably spent too much energy creating our own tools (even if that was good dogfood) instead of improving the actual content. It'd be good to refocus from now on. Not sure what would be the perfect tool, although I believe the main issue is the lack of contributors. I myself spend less time writing docs than I should, my attention deviates too easily towards fixing bugs or adding new features. The current website and docs just happened thanks to @whitetigle 😄

So any help with the docs and website would be greatly appreciated. Some random ideas:

• I don't have a strong opinion about tooling, anything that lowers the entry barrier to contribute would be great. When I used FSharp.Formatting in the past (the first version of Fable website used it) I found that it required complicated build scripts that broke quite easily. But it's been a while so maybe it has improved now.

• In any case, I would scope any improvements efforts to Fable website and documentation. Trying to make the documentation of all Fable packages consistent would be too much. We already have two competing sites to list the ecosystem (fable.io/community and awesome-fable) and none is very actively maintained 🤣

• Add a Twitter feed to the website? Most of Fable-related news are announced there so we can avoid the copy and pasting (maybe we could even try to write a bot to automatically update community.json from Fable tweets).

• Better synergies with the safe-stack? They already have great documentation, so an option could be to just integrate the docs and avoid duplicating efforts.

This seems like a good read regarding writing documentation: https://kislayverma.com/programming/why-programmers-dont-write-documentation/

from fable-compiler.github.io.

I'm leaning towards continuing using Nacara but improving it and making it match the rest of the website. There is no reason to discard work that has already been done. It needs to be improved upon. Is everyone ok with this?

Well, yes I am 😉

I did explore F# formatting again yesterday and I didn't like it too much. It has indeed been improved since the last time I checked for example, it does provide a CLI tool which automate a lot of stuff.

However, the customisation part is not great and personally I don't like the default theming.

Also tried Gitbook but the editor have a several bugs (already reported) which are a bit annoying unfortunately. I think it can work in some places but not in our case.

I am going to go back to improving the Nacara.

1. By fixing the already listed issue
2. Adding support for automatic API documentation generation. I am speaking of stuff like that
3. Refining the user experience where there are some rough edge

It would still lack the "Literate programming" mode but that can come later.

from fable-compiler.github.io.

I am going to go back to improving the Nacara.

@MangelMaxime I will help you out as much as I can. I'll write a few things first in the issues so that we can work from there.

API documentation is a bonus for sure. I have noticed that Nacara is also lacking in documentation 😊 I"ll help with that also.

from fable-compiler.github.io.

I have noticed that Nacara is also lacking in documentation 😊 I"ll help with that also.

But... but it has a "beautiful" website https://mangelmaxime.github.io/Nacara/

Honestly I agree, that website is something I put together but it is not really useful have a lot of problems.. And is mostly useful because I am using it to build/debug Nacara 😂

@MangelMaxime I will help you out as much as I can. I'll write a few things first in the issues so that we can work from there.

👍

from fable-compiler.github.io.

This is a nice feature that was missing on nuget:
https://devblogs.microsoft.com/nuget/add-a-readme-to-your-nuget-package/

We should leverage this for this and other packages.

from fable-compiler.github.io.

On a side note, I was researching a bit and stumbled upon https://fake.build website.

On this page it says that they are using F# Formatting library, but the website looks awesome. It even has a frontpage that looks similar to the current frontpage for Fable.

I have been digging, but I can't find how did they make the customizations, like the navbar and the sidebar.

from fable-compiler.github.io.

They do that by customizing the template passed down to F# Formatting.

However, F# formatting says:

For your project, you don't need any of these files. However you can add them if you wish, though if you adjust them there is no guarantee that your template will continue to work with future versions of F# Formatting.

The important part being there is no guarantee and also there is not a lot of documentation available about what is need to keep the documentation etc.

Like I mentioned before, I think we are going to keep using Nacara.

The documentation is indeed lacking at the moment, but I am here to answer the questions.

For the customisation part, everything can be done in F#, so if I document Types.fs it represents the majority of what is needed to people to write their own layouts.

The real, missing stuff right now, is the API doc generation.

from fable-compiler.github.io.

Also Nacara, is already set up in the project so migrating the custom generation to Nacara is not hard to do.

For example, currently the things not handled by Nacara from the current website are:

• Blog: need a custom layout and move the files from blog/ to docsrc/blog and add the front-matter tags required.

• Index page: we can write it using standard HTML and using a layout which gives access to the fullwidth of the screen.

• Community: is a standalone application which mimic the navbar of the main website to make the transitions "seemless". We could keep it like that of create a special layout to load the the bundle.js on the page.

Thoth.Elmish.Toast was doing that:

---
title: Demo
layout: demo
---

<div id="toast_demo"></div>

<div class="has-text-centered">

*[View the code](https://github.com/thoth-org/Thoth.Elmish.Toast/blob/2.0.0/demo/src/Toast.fs)*
</div>

<script type="text/javascript" src="/Thoth.Elmish.Toast/demo/vendors.js"></script>
<script type="text/javascript" src="/Thoth.Elmish.Toast/demo/demo.js"></script>
<script type="text/javascript">
    startDemo("toast_demo");
</script>

Custom layout code

• FableConf: Doesn't need to be migrated because it is in it's own repository and the design of FableConf is different because it was the colour choosed for the marketing stuff etc.

If we take care of the index page and blog page, that's all this repository would be converted to Nacara. And this also means that the index, blog and docs shares the same style.scss so their visual styles are aligned.

from fable-compiler.github.io.

My impression of the docs for fable is that it's a lack of content problem, not a "should be using a different tool" problem. The docs are trivial to contribute to, and it doesn't appear that anything is inhibited by the tools right now.

The one benefit to using fsdocs/FSharp.Formatting would be to have it auto-generate an API reference for Fable.Core. That's what the tool is primarily for, anyways - documenting a library with an API reference.

from fable-compiler.github.io.

@MangelMaxime Very nice and consistent. Great work!

This now looks fresh. Can't wait to try it out.

from fable-compiler.github.io.