Validate docs (plus)

[joshmoore]

• schema: add README with file list
• validation: add examples to module; add usage page
• misc: update table-of-contents ordering
• misc: include license file
• misc: fix codebook and intensity_tables autodocs
• misc: move to index.rst in several cases (see discussion)
• sphinx: add program-ouputs for keeping --help uptodate

Note: this doesn't yet include enforcing validation via STARFISH_VALIDATION_STRICT. That's waiting on gh-789

[joshmoore]

For discussion: I'd propose that we move to topic/index.rst as frequently as possible since it produces nice URLs like https://spacetx-starfish.readthedocs.io/en/latest/API/image/ rather than https://spacetx-starfish.readthedocs.io/en/latest/API/image/filtering/filtering.html

[codecov-io]

Codecov Report

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

@@           Coverage Diff           @@
##           master     #900   +/-   ##
=======================================
  Coverage   87.86%   87.86%           
=======================================
  Files         149      149           
  Lines        4893     4893           
=======================================
  Hits         4299     4299           
  Misses        594      594

Impacted Files	Coverage Δ
sptx_format/util.py	94.44% <ø> (ø)	⬆️
starfish/pipeline/pipelinecomponent.py	92.68% <ø> (ø)	⬆️
sptx_format/validate_sptx.py	84.74% <ø> (ø)	⬆️
...ish/intensity_table/intensity_table_coordinates.py	100% <ø> (ø)	⬆️

---

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 0f6311d...e9679af. Read the comment docs.

[ambrosejcarr]

Fantastic. See request for clarification in comments, as well as point about literalincludes.

[ambrosejcarr]

This one would be easy to rewrite in ReST if we wanted to go that route.

[joshmoore]

I was actually surprised that sphinx handled the mix of rst and md so well. I don't feel a particular need to unify on rst (I find markdown easier to author myself) but where we want advanced sphinx features, we'll likely have to convert.

[ambrosejcarr]

Just a comment to others working in the docs -- at some point in the future we should figure out how we want to deal with literalinclude. Sphinx is careful to restart header levels based on toc links, but doesn't restart from literalinclude.

e.g. if you have two files whose contents are:

`file1.rst

Header 1
=========

file2.rst

Header 2
=========

toc link

Header 1
    Header 2

literalinclude

Header 1
Header 2

[joshmoore]

But at the moment, you don't see anything that is rendering incorrectly in this PR, correct?

[ambrosejcarr]

Nope, just pointing out that it's a trap that we'll eventually want to fix.