Documentation overhaul

[tomasaschan]

This is to discuss changes to, and completion of, documentation for this package. Major questions are:

• How do we want to organize the documentation? Formats, locations etc...
• What should be documented (more than just by writing clear code)? Devdocs? Implementation details?
• On what level of detail do we want to document things?

Some discussion started in #45 already, where the following points were raised:

In a sense the README could be a summary of what's available, now that

julia> using Interpolations
julia> ?Interpolations

dumps the README contents. So I've begun to think that it might be good to keep the README as an "API reminder" for people who already understand the package, and the IJulia notebook as an introduction to the package.

I agree that it's probably a good idea to make the readme minimalistic. I'd also like to start documenting most other things in a help>-compatible way, so we might want to move off from the IJulia notebooks alltogether. And I feel like I have to strip down the LaTeX stuff to something with minimal dependencies, so anyone can at least compile it, but it is a very handy way to document the mathematical background of any methods we implement...

[tomasaschan]

This was raised again in discussion in #90. I'd like to find a better place to keep documentation of math that's too lengthy and/or not relevant for docstrings.

Requirements:

• Readable and editable in any text editor
• It should be possible to render the equations to something nice-looking
• It should be relatively easy to have the rendered documentation shown on the web somewhere (could be inside the repo if we choose markdown - could be something like readthedocs.org...) and update it as part of the bulid/test process.

Nice-to-haves:

• The notation to render mathematics should, preferrably, be easy enough on the eyes to be able to follow even if looking at the plaintext version.

Any suggestions are welcome.

[tomasaschan]

I asked a question on julia-users to get some input for tools and platforms: https://groups.google.com/forum/?nomobile=true#!topic/julia-users/mRk0igz_uHQ

[aramirezreyes]

I have seen in the docs some obscure infromation about how to select the behaviour outside the domain, i.e, decide wether or not to extrapolate. I haven't figured how to use it, however, i can see that ExtrapNaN or ExtrapError are no longer valid as arguments to extrapolate. I think that part of the docs could be improved. [I'll check the source and see if i can help]

[tomasaschan]

That would be most appreciated!

[tomasaschan]

@argelouski: I think that this section of the Readme is up to date, so that can hopefully provide some assistance, too.

[tomasaschan]

This blog post should definitely be considered, too: http://maurow.bitbucket.org/notes/documenting-a-julia-package.html