Styling documentation via mapnik-reference

[springmeyer]

We should pull in https://github.com/mapnik/mapnik-reference and use it to auto-generate awesome pages with all the details Mapnik cartographers need for understanding:

• what styling properties exist
• what they are named in Mapnik (and CartoCSS)
• how they behave
• their stability (e.g. stable or deprecated)
• all this browseable by mapnik version.

This will be similar to the built-in styling docs some people may know from tilemill/mapbox-studio, except that:

• Each mapnik version will be listed
• The community will be able to update and help refine the docs by contributing to mapnik-reference
• Everything will be easily linkable via name anchors. And a link to the place to edit mapnik-reference on github should be provided so it is really really easy for others to provide pull requests with doc improvements.

Once this is done, we should remove the wiki pages that have become unmaintainable, hard to read, and out of date like https://github.com/mapnik/mapnik/wiki/TextSymbolizer.

[springmeyer]

@yohanboniface - I'd love your feedback on the above plan. Basically I'm imagining that something like this would really benefit openstreetmap-carto and kosmtik.

[yohanboniface]

Hehe, I've just created https://github.com/kosmtik/kosmtik-mapnik-reference plugin, to integrate the documentation in Kosmtik ;)

A part from that, for sure that's a nice thing to do. :)
The issue I've in mind, is how to have a smooth workflow to update such a site.
I'm not a Github Pages advanced user, but AFAIK it's not possible to pull anything dynamic at build time (no npm install or such, for example).
So I imagine we only can access reference.json files through submodules, which are a pain to work with.
But if we have a git version recent enough I think we can point on a branch, which then auto-update at each build (hopefully), but we are talking about builds of this repository, not the mapnik-reference ones. So this doesn't make a nice workflow that auto-update the site each time the reference is updated.

The better option I can think of right now is to have a reference.mapnik.org domain, that then points to the Github Pages of mapnik-reference, and we switch to using gh-pages as main branch instead of master. We'd also need to add a .npmignore file there not to push every site related files in the node package.

About the site itself, I would go for a single page, with drop down or so for choosing the Mapnik version, plus a quick javascript to filter symbolizers and/or rules (or maybe one just hit ctrl-F…). And we'll need anchor for version (dynamic) and rules I think.

If needed, I can certainly find some time to work on this in the incoming days/weeks.

[springmeyer]

Hehe, I've just created https://github.com/kosmtik/kosmtik-mapnik-reference plugin, to integrate the documentation in Kosmtik ;)

Excellent. That is exactly what it is designed to enable. The more places it is used the better. It definitely makes sense to embed as you need.

The better option I can think of right now is to have a reference.mapnik.org domain, that then points to the Github Pages of mapnik-reference, and we switch to using gh-pages as main branch instead of master.

Great idea.

About the site itself, I would go for a single page, with drop down or so for choosing the Mapnik version, plus a quick javascript to filter symbolizers and/or rules (or maybe one just hit ctrl-F…). And we'll need anchor for version (dynamic) and rules I think.

💯

If needed, I can certainly find some time to work on this in the incoming days/weeks.

\o/

[springmeyer]

Closed by mapnik/mapnik-reference#107