Plan for documentation

[birkskyum]

Our current setup for documentation is problematic for many reasons and we should look into something more standardized.

A such setup for the majority of the codebase could be to use:

TSDoc for writing the docs inline to write the docs inline - this would need syntax adjustments from JSDoc many places.
TypeDoc for exporting said docs

Then we'd need a way to display the docs nicely (the built-in typedoc site doesn't look modern), and by using the typedoc-plugin-markdown, we can use i.e.:

• Vuepress
• Docusaurus
• Github wiki
• Hugo (what we currently use for maplibre.org)

[rotu]

What are the reasons?

What is the documentation that doesn't look modern? this? https://maplibre.org/maplibre-gl-js-docs/api/markers/ (It looks pretty good to me, but I don't know much)

[HarelM]

I would also consider merging the repos and having the docs as part of this repo.

[birkskyum]

@rotu, The problem with the current docs is not so much the visuals, but the underlying stack. The main problems are:

• We have to maintain the obsolete jsdoc generator documentation.js.
• We have to maintain the obsolete mapbox build system batfish. Things are very hardcoded because it's the only project using this build system.
• We can't use TSDoc instead of JSDoc, so we have to sync redundant types. This is because Mapbox is written with Flow instead of Typescript, so no TS support.
• We have an issue with maplibre style spec that is currently locked on an older release because of Node 18 compat in Batfish - so we effectively can't update the docs of the style-spec if we make changes to it.

There are plenty of popular off-the-shelf docs compilers out there that we don't have to waste resources maintaining.

[rotu]

I think the build system does more than just build docs - it also does some preprocessing of example code and validates that the examples work.

I think a good first step would be moving the docs into this repo as a workspace. And then retooling the build system.

[IvanSanchez]

I've been looking for an opportunity to spend some time taking care of Leafdoc - the thing that builds the LeafletJS API docs.

Perhaps it's worth considering?

[HarelM]

The focus of this issue it to use exiting tools for documentation that are widely used.
In theory, much like batfish, we would like to avoid using a proprietary system and use the standard tools to generate documentation from the code.
The code is relatively well documented from jsdocs point of view, I would be happy to stop needing to sync between the typescript and the jsdocs, but that might just be wishful thinking.
The main idea behind this issue is to stantartize the stack.
@IvanSanchez can you maybe elaborate on what you wrote and what you would like to do?

[IvanSanchez]

can you maybe elaborate on what you wrote ...

Back in... 2015? the LeafletJS API docs were written by hand, and the existing tools back then weren't a good fit for several reasons. So I wrote Leafdoc and we moved the documentation into docstrings. Yes, it's a niche tool, but it's been working reliably for years.

...and what you would like to do?

Ideally I'd like to write Leafdoc docstrings once, and from those docstrings generate: (1) readable HTML API docs (2) graphviz UML class diagrams and (3) typescript definitions. (1) and (2) are doable right now (e.g. API, UML), but (3) would need a fair a bit of work.

[HarelM]

batfish is doing a very good job, and I'm generally happy with the results (I also think it's a lot more elaborate than the leaflet docs along with the style spec, the examples etc), the problem is maintenance mainly and the fact that we would like to use more standard tool, much like we did with typescript, jest, playwright, etc.
On boarding to this project and finding solutions to problem you encounter are way faster when you use commonly used tools.
Switching from one niche tool to another isn't what we would like to achieve with the bounty related to documentation or in general. Sorry to disappoint...

[birkskyum]

Ping @vshchutc

[birkskyum]

@HarelM , what is your opinion on the proposed solution with tsdoc -> typedoc -> markdown -> any of the off-the-shelf docs generators?

[HarelM]

Looks good to me, both project have a huge weekly downloads count in npm.

[birkskyum]

I've been exploring TypeDoc to assess how much work this is, and my conclusion is that it's a very big undertaking to resolve all the lint issues that arise from migrating JSDoc to TSDoc. Half of them can be resolved automatically, but still 5k+ issues remain that require manual intervention.

[HarelM]

From my point of view, the classes documentation is important, but the interesting part is the examples and style spec docs.
If we have good j/tsdocs comments on the methods you should get that using intellisense when simply using typescript.
The number of times I found something valuable when reading about a class documentation is neglectable, intellisense usually covers this part, it is when you don't have intellisense is when you need the docs:
For example, how things work behind the scenes, examples of pieces of code you might need etc...
Current documentation site covers that, this would be where I would consider investing time in improving.
Maybe a part of it is moving the v8 file to json-schema, but maybe it has nothing to do with it.

[birkskyum]

If we moved the style spec to a separate repo/docs site, we might be able to extend the lifetime of the batfish page a bit - it's the biggest deal-breaker as I see it that we currently can't update style spec docs

[HarelM]

If the style spec docs are the main reason for batfish and the rest can be done in this repo I'm all for it.

[HarelM]

I'm converting this into a discussion, as I would like to allocate some bounties around this. i.e. I'll be opening smaller issue to split the work and assign bounties to those.

[HarelM]

I think the info here is spot on in terms of technology, I'll continue the discussion in the following issue: #2150