[FEATURE]: Full doc with docfx

[kubikpatrick]

Is your feature request related to a problem?

Missing documentation

Describe the solution you'd like

A complete documentation with docfx can be very useful, freely hosted on github pages

Describe alternatives you've considered

No response

MapLibre JS Reference

No response

Example Usage

Additional context

No response

Contribution

• I'm interested in implementing this feature with guidance

[ryanspain]

I like this idea personally. Docs-as-Code is best way to do docs for projects under source control where developers are the main actors.

I mentioned docfx in this comment on my latest pull request. I bring this up since we already have the Examples Blazor WASM project that shows off what the library can do. I suggested it might be worth embedding the docs in that WASM app using a Markdown to HTML renderer (if the docs footprint isn't too wild).

[kubikpatrick]

i can take of starting the docs if everyone agrees

btw, wdym bu docs footprint ?

[ryanspain]

docs footprint

I was talking about the number of Markdown files and complexity of the to-be folder structure.

Using docfx, it very easy to have a large documentation directory.

But if we decided to embed the documentation in the Blazor WASM examples site (using a Markdown to HTML converter), if there were too many files, it could be a littler harder to manage (without building out a a mini framework/process for showing them on the GitHub pages site).

[kubikpatrick]

why not just drop all markdowns into the repo?

github's repos don't have any size limit

[ryanspain]

Yeah that's absolutely the idea - everything goes in /docs.

I guess what I was talking about specifically is "how do we make the docs available on the internet? (outside of GitHub)".

Of course it's likely going to be hosted on GitHub Pages, but right now, the single GitHub Pages site for this repository is occupied by the Community.Blazor.MapLibre.Examples Blazor WASM stand-alone static side. We can't just plug a docfx site into that without some work to embed the docfx site into the Community.Blazor.MapLibre.Examples projects build output. But I think a more elegant solution is available. i.e.:

1. Use docfx exclusively:
   • ✅ Great for just static docs.
   • ❌ Lose the ability to embed interactive examples.
2. Render Markdown files in the existing Blazor site:
   • ✅ Maintains the ability to embed interactive examples.
   • ❌ Requires work to embed the docfx output into the site.
   • ❌ Requires work to keep styles/look/feel the same between docfx and Blazor site.

[kubikpatrick]

okay i see what you mean, you want both docs and examples into a single website ?

[ryanspain]

Yeah I think that would be pretty useful right? Working examples of the library in the docs site.

[kubikpatrick]

indeed, that's a pretty good idea, but prioritizing documentation first is imo the right thing to do imo. we should first replace examples by the docs, then, find a way to merge docs and examples

[ryanspain]

I reckon the docs would survive living under /docs for now until a way to merge them is designed (since the examples site is already up and running and a great testament to the work done on this library).

It'd be good to hear what @MatejMa2ur thinks of course before any time is sunk into the work.

[kubikpatrick]

okay, so i'll add some new examples, with markers for example

[MatejMa2ur]

Well so I would say let's go with docfx.

And host the examples on another url, I will set it up, that is not an issue.

And the examples are only to showcase a little what is possible.

Btw about the markers, I was looking into them and I think that for a lot of use cases it is better to use the point of geojson and just style it. You have much more features included in it. Not saying markers are wrong.

[MatejMa2ur]

Okay, I have one question for you.

How are you expecting it to be deployed, because currently the blazor web with examples is deployed here:

yet-another-solution.github.io/Blazor.MapLibre/

And I will make it, I was just if you meant that it would be something like:

yet-another-solution.github.io/Blazor.MapLibre/docs

[ryanspain]

We have two options that I can think of:

1. Replace the example repo with the build output from docfx (I have sample workflows for this)
2. Update the examples project to include the docfx site in it's build output (this wouldn't be too hard, but would require some tweaking of things to make it work cleanly) docs can be accessed via /docs and examples via /examples. I've set this up in work to support maintain multiple version of documentation in the one site.

I like option 2 best since we get to keep the great example site and extend both.

I can do a prototype for the examples project to show how it can work (embedding the docs site build into the Blazor WASM project build).

For now, maybe just having the structure in place is enough and people can add docs under /docs. But if we are in no rush, I have some time tomorrow where I can update this PR with that prototype.