Recreate structure of documentation

[tmcw]

Fixes #2799

Trying to refactor this as much as possible, I'll record quibbles here:

This process gives you a native iOS app for simulator or device which compiles the source to GL within it for fastest turnaround time during development

What does this mean? "compiles the source to GL"... does this JIT compile anything, or is it just saying "compiles mapbox-gl-native instead of using a bundle".

---

Install appledoc 2.2v963 for API docs generation (only this exact version works right now (#2117).

This links to a closed ticket that doesn't give a clear answer. Is this statement still true?

[tmcw]

Okay: I think this refactor is ready for review. cc @incanus

[incanus]

Taking a look now @tmcw.

What does this mean?

Ordinary consumers of GL link it into their app as a static library. For development, we actually integrate the source of GL right into the source of the test app, for compilation speediness reasons. More here: https://www.mapbox.com/ios-sdk/#source

Is this statement still true?

I'm running 2.2.1 (1333) so I think not. Will amend.

[incanus]

I'm not sure about the approach of so many files, particularly docs/TROUBLESHOOTING.md. If I were having a problem, my first instinct wouldn't be to search the source for a file called TROUBLESHOOTING.md, particularly if one or more of the existing DEVELOP_ files had troubleshooting sections already.

[incanus]

We should probably bring in Node-specific instructions here as well, as "Linux on Linux" could be desktop, could be Node. /cc @mikemorris

[incanus]

Otherwise I'm 👍 here @tmcw.

[mikemorris]

Node.js docs have lived in https://github.com/mapbox/mapbox-gl-native/blob/master/platform/node/README.md for mostly historical reasons, we should consistify this between platforms - either break all platform implementations into platform/%/README.md or bring everything into README.md. Same goes for the Node.js changelog.

[tmcw]

@mikemorris are there any instructions for building the node module from source? The instructions in README.md are

npm install mapbox-gl-native

Which would install it from npm, right?

[mikemorris]

@tmcw npm install --build-from-source to install node modules then do a source compile, make node (or make xnode) for recompiling C++ files during development.

[tmcw]

This process gives you a native iOS app for simulator or device which compiles the source to GL within it for fastest turnaround time during development

Okay so this is trying to use "GL" as a stand-in for "the library". I'll improve this sentence.

[tmcw]

I wrote a section for the node.js bindings, documenting --build-from-source: if there's some more reasoned reason for using that versus make node versus make xnode, that's something for @mikemorris to write because it isn't clear from any of the issues/prs/code

[tmcw]

Better API documentation, for all bindings, should be a second pass. This PR is just reorganizing our current build-stage docs.

[mikemorris]

Cleaned up Node.js docs a bit, looks good to me now 👍

[tmcw]

rebasing into one commit & merging.

[incanus]

Great work @tmcw. We've gone through some solid iterations of all this mess o' docs and this is the best yet.