Documentation structure

[rgommers]

Some of this is still a bit rough and there are a bunch of questions in here. There's a number of other issues in this repo (and the other repos) about doc sections needed, but there's no overview/outline anywhere that describes how we'd like things to look.

• section on concepts (some of these can simply reference a good explanation elsewhere):
  • array types
    • explain why the type includes the shape
  • broadcasting
  • indexing & slicing
    • what types of indexing are supported? docs only say "indexing works as expected". does it work like NumPy or Xarray (or both)? fancy indexing? boolean indexing?
  • copies/views
  • casting rules
    • exact conversions allowed with builtin kernels, inexact not
    • use underspecified type concept (in Python)?
  • gufunc/kernel
  • an xnd container diagram (like at the top of https://www.numpy.org/devdocs/reference/arrays.html)
• doc structure:
  • why are xnd and gumath together, and ndtypes separate?
  • put Quick Start at top, update Install section (point to conda channel)
  • some things like Binder links, meetings, etc. are only mentioned on xnd.io and can't be found by searching the docs. So link back or add in docs.
  • split up in sections by language first? (C, Python, other)
  • or by library?
  • or by type of user? (library author, early adopter, average Python user)
  • probably best to keep average end user docs separate from what's there now (C + advanced Python)
    (rationale: average users likely won't contribute back and won't care much about internals)
• other sections we may want to add:
  • performance
  • features no other array library supports (well)
  • dev setup: does it need C99, does it work on Windows (no nightlies at least, so not sure), etc.
• A "I want to do X" type guide:
  • guide / decision tree, to figure out if XND is usable or recommended for a use case today or in the near to medium term
  • write bindings for another language (refer to Python, Ruby examples + a few words of general advice)
  • Generate custom kernels with Numba (gumath issue 8)
  • Use functions that expect NumPy arrays
  • Perform linear algebra / fft / etc.
  • explain what's stable, what may not be yet
• random:
  • make linkcheck
  • Plures --> XND
  • update releases section