Deployment strategy for fabulous.dev

[TimLariviere]

After https://github.com/fsprojects/Fabulous is moved to fsharp-mobile, it would be good to split it in 3 different repositories:

• Fabulous (the core project)
• Fabulous.XamarinForms
• Fabulous.MauiControls

This change will beg the question of how do we deal with the documentation website at https://fabulous.dev

Right now, this website is actually 2 individual parts hosted on GitHub Pages: fabulous.dev which is the "marketing" landing page and docs.fabulous.dev for all the documentation.

fabulous.dev is built from the repo fsharp-mobile/fabulousfx.github.io
docs.fabulous.dev is built from the repo fsprojects/Fabulous itself, but the compilation is a little bit more advanced:

• On commit to main, the action gh-pages is triggered
• It will pull the template for the website from the docs branch
• It will also pull the markdown files of the docs folder on the main branch and combine it with the website template
• The website is then compiled and published to GitHub Pages (branch gh-pages)

This was working because it is a single repository.

I've been thinking how to deploy the same website structure (each repo has its own markdowns) but make it work across repositories given a specific domain can only be hosted on a single repo.

I came up with this idea:

fabulous.dev (main landing page promoting both Fabulous and variants eg Fab.XF, Fab.Maui, etc)
==> fabulous.dev/xamarin.forms (landing page specific to Fabulous.XamarinForms)
==> fabulous.dev/maui

This would be hosted on a separate repo like today. Say fsharp-mobile/fabulous.dev.

Then we would have the documentation:

docs.fabulous.dev (landing page for the documentation)
==> docs.fabulous.dev/fabulous (documentation for Fabulous itself)
==> docs.fabulous.dev/xamarin.forms (landing page for the documentation of Fab.XF)
==> docs.fabulous.dev/maui
.......==> docs.fabulous.dev/maui/v2.1
..............==> docs.fabulous.dev/maui/v2.1/development

The root of docs.fabulous.dev would be hosted on a separate repo. Say fsharp-mobile/docs.fabulous.dev
This repo would have a template website on the main branch, and would be published on GitHub Pages.

Same for the API reference:

api.fabulous.dev (landing page for the API reference)
==> api.fabulous.dev/fabulous
==> api.fabulous.dev/xamarin.forms (landing page for the API reference of Fab.XF)
==> api.fabulous.dev/maui
.......==> api.fabulous.dev/maui/v2.1
..............==> api.fabulous.dev/maui/v2.1/button

The root of api.fabulous.dev would be hosted on a separate repo. Say fsharp-mobile/api.fabulous.dev
This repo would have a template website on the main branch, and would be published on GitHub Pages.

Each repos (Fabulous, Fabulous.XamarinForms, Fabulous.Maui) would be expected to have 2 folders: docs and api.
On commit that change either docs or api, it would push the contents to their respective fsharp-mobile/docs.fabulous.dev and fsharp-mobile/api.fabulous.dev on their own branch (Fab.XF ==> xf branch, Fab.Maui ==> maui branch).

Whenever a new commit is added to either fabulous.dev, docs.fabulous.dev or api.fabulous.dev, it would trigger a build and push to GitHub Pages.

docs.fabulous.dev and api.fabulous.dev would pull all their "known" branches into the main template and compile everything together, effectively releasing a single website for all frameworks.

graph LR;
    Main(fsharp-mobile/fabulous.dev)-->CommitMain{On commit}
    CommitMain-- compile template -->fabulous.dev

    A(Fabulous.XamarinForms)-->CommitA{On commit}
    CommitA-->docsA(docs)
    CommitA-->apiA(api)
    docsA-- push changes to branch Xamarin.Forms -->sitedocs(fsharp-mobile/docs.fabulous.dev)
    apiA-- push changes to branch Xamarin.Forms -->siteapi(fsharp-mobile/api.fabulous.dev)

    B(Fabulous.Maui)-->CommitB{On commit}
    CommitB-->docsB(docs)
    CommitB-->apiB(api)
    docsB-- push changes to branch Maui -->sitedocs
    apiB-- push changes to branch Maui -->siteapi

    sitedocs-- compile template & branches content -->docs.fabulous.dev
    siteapi-- compile template & branches content -->api.fabulous.dev

Loading

@edgarfgp What do you think? Do you know of a better way to handle that?

[TimLariviere]

I think we can even find a way to include documentation for 3rd party extensions such as Maps.
Like docs.fabulous.dev/xamarin.forms/plugins/maps and api.fabulous.dev/xamarin.forms/plugins/maps

[TimLariviere]

Actually instead of pushing on the repos docs.* / api.* all the markdowns, we could just update a txt file with the commit hash of the corresponding repo.
e.g.

fsharp-mobile/docs.fabulous.dev/commit.txt (branch xf)

ff96d7a61c5032f5e7f06b5a3cc81cffec4d71c0

Upon update, GitHub Actions would then pull the repo of Fabulous.XamarinForms for this specific commit getting all the markdown files without duplicating them.

[edgarfgp]

This structure looks good to me.

fabulous.dev (main landing page promoting both Fabulous and variants eg Fab.XF, Fab.Maui, etc)
==> fabulous.dev/xamarin.forms (landing page specific to Fabulous.XamarinForms)
==> fabulous.dev/maui

docs.fabulous.dev (landing page for the documentation)
==> docs.fabulous.dev/fabulous (documentation for Fabulous itself)
==> docs.fabulous.dev/xamarin.forms (landing page for the documentation of Fab.XF)
==> docs.fabulous.dev/maui
.......==> docs.fabulous.dev/maui/v2.1
..............==> docs.fabulous.dev/maui/v2.1/development

Actually instead of pushing on the repos docs.* / api.* all the markdowns, we could just update a txt file with the commit hash of the corresponding repo.
e.g.

fsharp-mobile/docs.fabulous.dev/commit.txt (branch xf)

ff96d7a61c5032f5e7f06b5a3cc81cffec4d71c0
Upon update, GitHub Actions would then pull the repo of Fabulous.XamarinForms for this specific commit getting all the markdown files without duplicating them.

Yeah that would be easier enough to manage :)