Add Style Docs

[birkskyum]

Closes maplibre/maplibre-gl-js-docs#400 (Repo split / migration), Closes #126 (New docs)

The new docs can be launched by running:

cd docs
npm i
npm run dev

[wipfli]

Looks really nice, thanks a lot @birkskyum

The URLs will still be the same as before, right?

[HarelM]

Can you please share some visuals of the new docs site?
Can you elaborate on the selection of the tools? Pros? cons? Why was this selected?
Can you please share what should be the process when updating the style-spec? Will it be fully automatic or will there be manual changes that need to happen here?

[wipfli]

[wipfli]

Clicking on things like "string" does not work yet: http://localhost:3000/maplibre-gl-style-spec/style-spec/types/#string

[birkskyum]

The URLs will be exactly the same as before. The only one I changed was /other -> /deprecations because it's more informative of what the page contains.

Here are some visuals of the menus - first on medium screens the menu one on the right will be pushed into a collapsible part on top of the main content, then on small screen the left menu will be hidden as well and toggled from the header.

[birkskyum]

Aaah, right there are some links that should be updated.

[wipfli]

Go to http://localhost:3000//layers#paint-background-background-opacity, click on "number" -> page not found

[wipfli]

I think basically not all titles in the "types" page have links.

[HarelM]

There's just too much code here from my point of view for a documentation site.
We might as well create a site in WordPress or Wix.
The main point from my point of view is how I can easily convert the v8.json file into a site.
This doesn't solve this issue for me.
If this is only a temporary solution, to have a doc site here so that we can work on the next gen, then this is great, otherwise it misses the point I think...

[roblabs]

@birkskyum — It's really nice. I welcome the move to the "solid stack" of modern tools. It builds easy enough for me and as Oliver noted, I too found a few broken links. I think those will get sorted. The documentation shortcuts (see below) are really nice, and I believe preserve what we had with batfish.

Overall, I like the documentation upgrade.

[louwers]

I am unable to build:

% npm run build

> build
> solid-start build

 solid-start build 
 version  0.2.24
 adapter  static

solid-start building client...
vite v4.2.1 building for production...
✓ 48 modules transformed.
transforming (380) node_modules/@kobalte/core/dist/source/radio-group/radio-group-item-context.jsxInspect report generated at /Users/bart/src/maplibre-gl-style-spec/docs/.solid/inspect
✓ built in 2.02s
[vite]: Rollup failed to resolve import "object.entries" from "/Users/bart/src/maplibre-gl-style-spec/docs/src/components/sdk-support-table/sdk-support-table.tsx".
This is most likely unintended because it can break your application at runtime.
If you do want to externalize this module explicitly add it to
`build.rollupOptions.external`
file:///Users/bart/src/maplibre-gl-style-spec/docs/node_modules/vite/dist/node/chunks/dep-79892de8.js:46368
            throw new Error(`[vite]: Rollup failed to resolve import "${exporter}" from "${id}".\n` +
                  ^

[louwers]

From the documentation of SolidStart:

We are very excited about SolidStart, but it is currently in beta. There will very likely be bugs and missing documentation. Come at it with a growth attitude, have fun, and don't use it yet for anything critical.

Sounds a little too bleeding edge to me...

[louwers]

This is a big improvement over Mapbox Batfish from what I can tell, but I feel that it repeats the same mistake in that we don't have the capacity to keep a partly home grown JS+HTML+CSS stack up to date. The JS ecosystem especially moves pretty fast, and I fear this will be completely outdated in as little as 2 years from now. In addition:

• As a web developer this all looks pretty familiar to me, but having to learn a JS framework and JS build tools makes contributing to the documentation less approachable.
• Lack of internationalization, ideally this should be built in from the start.
• Tightly coupled to v8 JSON representation which I thought we wanted to move away from.
• I was unable to build but I think lack of versioning may also a problem.

I worked with Vite for well over a year and it is a pleasure to use when developing SPAs and otherwise highly interactive web applications, where the loading time in the past could be measured in minutes. However even really complicated static sites that are generated from scratch on every change do not take more than a couple of seconds to render. I don't think choosing Vite is worth the added complexity.

[birkskyum]

Lack of internationalization, ideally this should be built in from the start.

@louwers , I had all the routes beneath a /en/ url path initially, would that be a suitable internationalization strategy to you going forward? So that we could add /xx/ languages down the line.

[birkskyum]

Tightly coupled to v8 JSON representation which I thought we wanted to move away from.

I believe this is still be the plan.

[birkskyum]

I am unable to build:

@louwers Did you run npm i first?

[birkskyum]

Thanks for all the feedback. I will look into fixing the links. The other mentioned features/refactors are good suggestions, but they go beyond the capabilities of the existing site, so it'll have to happen in future efforts to avoid feature creep. In terms of why this stack was selected, see the reasoning in the ticket #126 .