[MRG] update documentation & add notebooks to docs

[ctb]

This reorganizes the documentation and adds Jupyter notebooks + binder links. See

• top level index
• tutorials

for the major points of reorg.

Rendered notebooks are under the add-nbsphinx branch on readthedocs. Direct links:

• k-mers and minhash
• sourmash examples
• sourmash on collections

both tutorials are also now updated to work, and to use bioconda:

• basic tutorial
• LCA tutorial

Fixes #430 #552. See #628 for related discussions. Includes cleanup from #607.

TODO:

• link these into the rest of the documentation :)
• add binder integration so that from the documentation, you can directly click to execute notebooks
• add relative links between notebooks so that once in binder, you don't have to start up an independent binder
• before merge, check to make sure that we're pointing binder at the right branch (master, presumably)

Checklist:

• Is it mergeable?
• make test Did it pass the tests?
• make coverage Is the new code covered?
• Did it change the command-line interface? Only additions are allowed
  without a major version increment. Changing file formats also requires a
  major version number increment.
• Was a spellchecker run on the source code and documentation after
  changes were made?

[codecov]

Codecov Report

Merging #631 into master will not change coverage.
The diff coverage is n/a.

@@           Coverage Diff           @@
##           master     #631   +/-   ##
=======================================
  Coverage   89.47%   89.47%           
=======================================
  Files          27       27           
  Lines        4238     4238           
  Branches       39       39           
=======================================
  Hits         3792     3792           
  Misses        446      446

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update c30b915...f69e6c8. Read the comment docs.

[ctb]

w00t the basic config seems to work! https://sourmash.readthedocs.io/en/add-nbsphinx/test-notebook.html

[ctb]

This is ready for initial commentary @luizirber @taylorreiter - thoughts very welcome!

[ctb]

Ready for review @luizirber @taylorreiter @bluegenes - once this is reviewed and OKed, I will update all the references to the add/nbsphinx branch to point to master, and then merge.

[taylorreiter]

• I don't see the "Notebooks" section at sourmash.readthedocs.io
• I like that you link to other notebooks at the bottom of each notebook
• "sourmash: working with private collections of signatures" In[2] currently has output that indicates the signatures are already present, so the calculations do not occur. I can't find the big_genomes directory to see whether this is expected behavior (did big_genomes get switched to genomes?). If it is, maybe we should make a note of it in the notebook?

Otherwise, LGTM!

[ctb]

Thanks @taylorreiter!

Curious - why are you looking for the Notebooks section? :) (I had that in earlier, but then I refactored.) Do I have a reference to it somewhere?

Thanks for the catch re big_genomes! It's created in the top of the notebook (mkdir -p ...) so that's no problem; I've redone the signature calculation and pushed updates.

If it looks good, I think it's ready to be approved (and then I'll go update all of the URLs before merging)

[luizirber]

Fix the binder/environment.yml channel order, and good to go!

[ctb]

ok. maybe I didn't do this right? but it should be ready.

[ctb]

(that is, ready to be approved. I'll need to do the branch name editing before merging.)

[luizirber]

@ctb it's approved now. MacOS wheel building seems to be failing on Travis, probably related to pypa/cibuildwheel#122 (will check)

[ctb]

thx all!