Bringing mapnik-reference up-to-date

[dch0ph]

mapnik-reference is significantly behind mapnik, which is a growing problem for projects such as carto (now in a new organisation) and the OSM Carto map style.

Although not a complete solution for updating documentation, an up-to-date mapnik-reference would greatly improve the state of documentation.

Can we see a manageable route to restoring life to this project?

A lot of changes in 3.1 have been collated (#143), and it shouldn't be too difficult to draft documentation from the PRs without much expert knowledge. Documenting 3.1 would address most current mapnik installations (current Ubuntu and Debian distributions package 3.1).

Upcoming releases will be targetting newer versions: Ubuntu LTS Resolute (4.2) and Debian Trixie (4.0.7). [OSMF now run their OSM Carto servers on Debian.]

[artemp]

#160 - improved usability by adding access to Layer and Datasources via web interface https://mapnik.org/mapnik-reference/
Also, making Symbolizers and Datasource menu items collapsible. Feedback how to make it even better most welcome.

/cc @dch0ph @gravitystorm @yohanboniface

[dch0ph]

Looks good!

I think the most useful thing to make the github pages documentation more useable would be to add a "description" or "overview" tag which is briefly explains the "why" of a given object. For example, there is an interesting datasource python, but it's only entry is encoding, which means a reader hasn't a clue about what the python datasource could be used for and how it might work. Similarly, what is the use case for rasterlite as opposed to raster?

In terms of documenting 3.1, do we need a new branch which can be developed independently?

On a strategic note, we should clarify whether mapnik-reference is intended to document all of mapnik, or the subset that is accessible through CartoCSS. My understanding is that there are significant chunks, such as GroupSymbolizer that are not documented here as a suitable CSS-style syntax has not been developed. Or is the problem with the JSON representation?

[artemp]

@dch0ph - sounds good to me ^.

NEW branch for to track 3.1 - https://github.com/mapnik/mapnik-reference/tree/mapnik-v3.1.0

Good question about clarifying the scope.. I think as a first iteration we could add v3.1.x and v4.2.x following current CartoCSS subset. I'm not sure about GroupSymbolizer, I'll need to investigate.

There's also
https://get-map.org/mapnik-lost-manual/
https://github.com/hholzgra/mapnik-lost-manual
/cc @hholzgra

[dch0ph]

I think it would be helpful to clarify between documenting mapnik functionality and how this is accessed via CartoCSS. As discussed in #119, the github pages are a little confusing as mapnik API documentation because they refer to CartoCSS terminology, e.g. line rather than LineSymbolizer and line-width rather than stroke.

This could be addressed by using the Symbolizer names in the panel menu (rather than line etc.) and adding the mapnik property name in () e.g. line-width (stroke)=float. [If I understand correctly, there are some CartoCSS properties that don't have equivalents e.g. line (CartoCSS only)=list.]

[artemp]

@dch0ph - I agree ^ mapnik-reference is double misleading here. It is Map styling reference only and specifically CartoCSS which is a subset.

Better naming would be mapnik-cartocss-reference or mapnik-style-reference - somewhat more explicit.

I'm wondering if combining mapnik style reference (Symbolizers/Rules/Filters etc) with relations to CartoCSS would be most useful?

[dch0ph]

It does document data sources as well, so it's not just styling.

I'm wondering if combining mapnik style reference (Symbolizers/Rules/Filters etc) with relations to CartoCSS would be most useful?

I think so. mapnik-reference does document a significant fraction of mapnik, which it wouldn't make sense to duplicate.

Making the connection between mapnik features and how they are expressed (or not) in CartoCSS more clearly would improve the value of the documentation for both CartoCSS and mapnik.

[dch0ph]

@artemp As noted in #167, I think I've documented all the render-side changes up to 4.2.0 - this didn't take as long as I thought.

So, unless you notice anything I've missed, you can merge the 4.2.0 into the main branch.

[dch0ph]

@artemp Could you sort out an npm release so that we can incorporate these updates into carto.js? I think it's sufficient for the CHANGELOG to refer to recent pull requests rather than re-document all the features added. A release would close this issue.

[artemp]

@artemp Could you sort out an npm release so that we can incorporate these updates into carto.js? I think it's sufficient for the CHANGELOG to refer to recent pull requests rather than re-document all the features added. A release would close this issue.

Great idea @dch0ph ! I don't have access to https://www.npmjs.com/package/mapnik-reference but I can start publishing mapnik-reference as @mapnik/mapnik-reference. The same way node-mapnik is configured currently and I think this is the way forward. Would it work for you?

[dch0ph]

Yes, that would make sense. carto has similarly been forked to become @cartocss/carto to extricate it from the dead hand of mapbox.

[artemp]

@dch0ph
https://www.npmjs.com/package/@mapnik/mapnik-reference

https://www.npmjs.com/package/@mapnik/mapnik-reference/v/9.0.2 <-- Is the latest

npm info --@mapnik:registry=https://registry.npmjs.org @mapnik/mapnik-reference versions
[ '9.0.0', '9.0.1', '9.0.2' ]

npm info @mapnik/mapnik-reference versions 
9.0.2

[dch0ph]

That's great! I can get carto to use the new npm package. We'll have to see whether the carto maintainers (Andy Allan?) are happy to accept PRs/changes, but that's not a mapnik issue!