Documentation Refactor

[ambrosejcarr]

The good:

• adds gitignore keys for the output of sphinx-gallery, which are incorporated into the documentation in the source directory
• adds additional galleries to docs/conf.py to render each of the data formatting examples and what were previously the notebooks
• Does NOT remove the notebooks, but they can be removed once they are properly tested in their new .py form/home.
• Makes minimal changes to the .py files to add docstrings to each data formatting and data processing example. These docstrings are needed by sphinx-gallery to add references to each file's header such that they can be linked to by the documentation.
• Moves around a ton of files without changing them
• Adds a bunch of vignettes about how to use starfish to create an image processing pipeline

The bad:

• breaks the CI.

Testing strategy:

make docs-html
open docs/build/html/index.html

Current state of testing of code in docs:

1. Any new code that has been added has been added to scripts prefixed by docs/source/_static/tutorials/exec_*. Anything in a folder specified by docs/source/conf.py that begins with exec_ is run by sphinx-gallery and therefore any errors in those .py files are caught by our existing CI, since the docs are built by travis.
2. The data formatting scripts (TileFetcher scripts) are not currently tested and have been moved to docs/source/_static/data_formatting_scripts/. They are not prefixed by exec_ and therefore continue to not be tested. It's not clear if we want to test these.
3. The notebook examples have been moved to docs/source/_static/data_processing_examples/. They were previously tested but are no longer being tested under CI. Ideally we would have travis build them, then upload the results to readthedocs. For the time being it is adequate to simply have travis build them so they are checked for errors. This probably means updating the makefile target.

Status of documentation added in this PR:

• It may contain spelling and grammatical errors. I offer to make fixes to any problems that people arise if the desire is to merge this to master so we can begin to work in parallel on the documentation.

Edit: also disables the bootstrap theme for the time being. We can put it back later, but it was doing some weird things to some of the gallery stuff.

[ambrosejcarr]

@ttung if you want to commit directly against this branch, or PR against it to fix the CI, that would be a good next step. 👍

[codecov-io]

Codecov Report

Merging #1153 into ajc-sphinx-gallery will increase coverage by 29.94%.
The diff coverage is 100%.

@@                   Coverage Diff                   @@
##           ajc-sphinx-gallery    #1153       +/-   ##
=======================================================
+ Coverage               59.94%   89.89%   +29.94%     
=======================================================
  Files                     172      120       -52     
  Lines                    6664     4414     -2250     
=======================================================
- Hits                     3995     3968       -27     
+ Misses                   2669      446     -2223

Impacted Files	Coverage Δ
...h/test/full_pipelines/api/test_iss_doc_pipeline.py	100% <100%> (ø)	⬆️
starfish/image/_filter/max_proj.py	93.75% <0%> (-6.25%)	⬇️
starfish/imagestack/parser/numpy/__init__.py	81.42% <0%> (-1.43%)	⬇️
starfish/image/__init__.py	100% <0%> (ø)	⬆️
starfish/test/full_pipelines/cli/test_iss.py	100% <0%> (ø)	⬆️
starfish/types/__init__.py	100% <0%> (ø)	⬆️
starfish/imagestack/test/test_imagestack.py
...arfish/spots/_detector/test/test_spot_detection.py
...fish/spots/_pixel_decoder/test/test_targets_map.py
...ish/imagestack/test/test_imagestack_coordinates.py
... and 122 more

---

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 cc47fbc...9c00293. Read the comment docs.