Update documentation

[mapsam]

Collecting ideas for updating documentation around node-mapnik after merging #605 and closing #604.

Documentation system upgrades

• upgrade documentationjs to the newest version (currently at 4.0.0-beta)
• generate mapnik theme starting with documentation-theme-default
• paginate classes went with collapsed sections instead
• research auto pushing to gh-pages if the /documentation folder has been updated auto build docs #652
• bump documentation up in the CONTRIBUTING.md, prioritized as a part of developing node-mapnik

Grammar, doc errors

• "fromStringSync" is listed twice instead of "fromString" for the async function
• update mapnik enums with @enum class - currently errors
• fix broken links to enums: http://mapnik.org/node-mapnik/documentation/3.5/#mapnik-vectortile/composite
• update toGeoJSON language to "Can be a zero-index integer representing a layer or the string keywords __array__ or __all__ to get all layers in the form of an array of GeoJSON featurecollections or in the form of a single GeoJSON FeatureCollection with all layers smooshed inside" from @springmeyer

Guides - less API documentation, more how-to, probably replace /docs

• create _config.yml in root and use jekyll to create markdown guides
• sample code how-to's (major update to https://github.com/mapnik/node-mapnik-sample-code)
• how to install/build Node Mapnik from source (inspired from Documentation for building from mapnik source #613)

[springmeyer]

👍

[syork]

Not sure if this is the right place to leave this, but I noticed that you have "fromStringSync" listed twice instead of "fromString" for the async function.

https://github.com/mapnik/node-mapnik/blob/master/documentation/3.5/index.html#L5734
https://github.com/mapnik/node-mapnik/blob/master/documentation/3.5/index.html#L474

I originally noticed it here: http://mapnik.org/node-mapnik/documentation/3.5/#mapnik-map/fromstringsync

[mapsam]

good eye @syork! That's undoubtedly a miss on my part. It even shows different options ... zoinks. Added to the list of TODOs

[mapsam]

Heya @syork the fromString and fromStringSync options have been fixed. Thanks for reporting 😄

http://mapnik.org/node-mapnik/documentation/3.5/#mapnik-map/fromstring

[mapsam]

Per discussion with @springmeyer, we are going to look into pulling Node Mapnik documentation generation into a separate repository.

The goals:

• declutter the Node Mapnik repository (just source code)
• make generating documentation much more simple. A user would still update JSDoc comments in the /src directory files, but that should be it.
• give space for writing Node Mapnik guides using jekyll, which would add more cruft to the Node Mapnik source code repo, but this way we keep it all separated
• move mapnik/node-mapnik-theme into a documentation repository, rather than a separate repo, which makes theme development simpler
• ponder how we can more effectively update old versions of documentation (probably phase 2)

This would involve:

• hooking into commits on mapnik/node-mapnik's master branch using the travis API based on either commit messages (i.e. message [docs]) or checking the git diff for any changes to JSDoc lines
• once the above is detected, trigger another repository (something like mapnik/node-mapnik-docs) to build documentation and commit to its gh-pages branch.
• move node-mapnik-theme into new repository

Downsides:

• Abstraction can lead to confusion, but hopefully with a nicely updated CONTRIBUTING.md we can make this process clear
• Domain name stability - if we move the documentation page to mapnik/node-mapnik-docs we lose the index.html file in the main Node Mapnik repository, which means we may be unable to host docs at mapnik.org/node-mapnik/documentation and it would instead exist at mapnik.org/node-mapnik-docs. I'm not sure if this is 💯 true, so will look into customizing the subpage mapnik.org/node-mapnik to point to node-mapnik-docs.

cc/ @springmeyer @artemp @flippmoke @jakepruitt

[springmeyer]

:+1 The next steps of This would involve: are 💯

As far as domain name stability - I'm not too worried about it changing as long as you are happy with the final url name. Jekyll redirects could be used in a pinch to keep old links working if things change.