Syntax highlighting in docs

[bmorris3]

This PR makes some revisions to the sphinx docs and docstrings. PR outline: (1) improves readability of code blocks, (2) fixes broken internal references within the sphinx docs (in both .rst files and several docstrings, and (3) fixes a broken link in the README.

Fix #1781

Preview

Preview these changes in this branch's RTD build. Prepare for colorful code 🌈

Details

1. As I have been reading the docs to come up to speed on jdaviz, I noticed a convention to use :: before a code block in the docs/*.rst files. This works fine, but if you replace it with:

- some code::

+ some code: 
+ 
+ .. code-block:: <syntax>

you get syntax highlighting within the code blocks. This makes the Python blocks a bit easier to read, and distinguishes the Python from bash.

2. Our narrative docs are just a few characters away from successfully cross-referencing the API documentation for each class and method. I've made revisions in this PR that fix some broken cross-references throughout our documentation.

3. The link in this section of the README is broken because that docs page doesn't exist anymore. I've changed the link in this PR.

Further/future work

I mentioned in #1767 that there are still several missing docstrings, even if this PR gets merged. We should probably write those, too!

Change log entry

• Is a change log needed? If yes, is it added to CHANGES.rst? If you want to avoid merge conflicts,
  list the proposed change log here for review and add to CHANGES.rst before merge. If no, maintainer
  should add a no-changelog-entry-needed label.

Checklist for package maintainer(s)

This checklist is meant to remind the package maintainer(s) who will review this pull request of some common things to look for. This list is not exhaustive.

• Are two approvals required? Branch protection rule does not check for the second approval. If a second approval is not necessary, please apply the trivial label.
• Do the proposed changes actually accomplish desired goals? Also manually run the affected example notebooks, if necessary.
• Do the proposed changes follow the STScI Style Guides?
• Are tests added/updated as required? If so, do they follow the STScI Style Guides?
• Are docs added/updated as required? If so, do they follow the STScI Style Guides?
• Did the CI pass? If not, are the failures related?
• Is a milestone set?
• After merge, any internal documentations need updating (e.g., JIRA, Innerspace)?

[codecov]

Codecov Report

Base: 87.77% // Head: 87.79% // Increases project coverage by +0.01% 🎉

Coverage data is based on head (8c06e82) compared to base (a673139).
Patch coverage: 100.00% of modified lines in pull request are covered.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1768      +/-   ##
==========================================
+ Coverage   87.77%   87.79%   +0.01%     
==========================================
  Files          95       95              
  Lines       10162    10149      -13     
==========================================
- Hits         8920     8910      -10     
+ Misses       1242     1239       -3     

Impacted Files	Coverage Δ
jdaviz/configs/mosviz/helper.py	86.89% <ø> (ø)
jdaviz/configs/cubeviz/helper.py	98.36% <100.00%> (+1.69%)	⬆️
jdaviz/app.py	93.62% <0.00%> (-0.15%)	⬇️
jdaviz/core/validunits.py	100.00% <0.00%> (ø)
jdaviz/configs/cubeviz/plugins/parsers.py	63.95% <0.00%> (+0.64%)	⬆️

Help us with your feedback. Take ten seconds to tell us how you rate us. Have a feature suggestion? Share it here.

☔ View full report at Codecov.
📢 Do you have feedback about the report comment? Let us know in this issue.

[pllim]

Doc only change does not need a change log entry. The doc changes would appear to user anyway and does not change the actual package functionality. Please remove the change log changes and squash it out. Thanks!

[pllim]

I am not sure if this does anything different in GitHub view but I guess it does not hurt.

[pllim]

Don't think :py: is strictly necessary but I guess it doesn't hurt?

[pllim]

Almost there... 😸

[pllim]

I don't think this align has any effect on the GitHub rendering. Should we just remove it?

Suggested change

:align: center

[bmorris3]

Interestingly, it does, but not always? This is a feature I've wanted for a long time in GH renders of rst docs, and it works in some repos but not this one... not sure why?

[pllim]

LGTM. Thanks!