RTD sphinx format updates

[sean-lockwood]

This PR allows the RTD environment to build.
PRs #145 + #151 fixed the RTD build issue, but this PR resolves formatting issues in the docs.

Build was failing due to time-out or memory exhaustion on the RTD server. Now mocking many packages and selectively installing them based on the READTHEDOCS environment variable.

Sphinx issues rectified by modifying docstrings.

Also updated RTD environment to Python 3.7.

New build of docs available for review here:
https://stistools.readthedocs.io/en/sl_rtd-env/

vs current build:
https://stistools.readthedocs.io/en/latest/

Note that the TOC now displays various helper functions. We need to decide if this should be suppressed.

[dougbrn]

Looks good. Feel free to merge

[sean-lockwood]

I tried building the docs in a separate RTD version.
https://stistools.readthedocs.io/en/sl_rtd-env/index.html

Something happened to the formatting we should work out before merging. This might be caused by a change to the Sphinx version?

Before:

After:

[sean-lockwood]

sphinx on RTD (4.5.0) is not generating bulleted lists properly. This may be related to the docutils version (0.17.1) needing to be pinned to 0.16 (or possibly a version >= 0.18).

[sean-lockwood]

Still having problems with bulleted lists, e.g.:

[sean-lockwood]

@starphire -
Looking for feedback on the formatting issues vs the current version. E.g., does the lack of bulleted lists change the meaning in any places?

[sean-lockwood]

@stscirij -
The change to the setup.py install_requires seems a little hacky. Feedback would be appreciated.

[sean-lockwood]

Note that PR #145 also changes the RTD configuration. Haven't resolved the differences yet.

[zacharyburnett]

@stscirij -
The change to the setup.py install_requires seems a little hacky. Feedback would be appreciated.

Would adding the docs extra to readthedocs.yaml work?
https://github.com/spacetelescope/jwst/blob/f10a9bba8ca54a460f649e1de0af1c4efb1d5f87/.readthedocs.yaml#L20-L26

python:
  version: 3.8
  install:
    - method: pip
      path: .
      extra_requirements:
        - docs

EDIT: I apologize, I misread the PR; I thought the issue was selectively adding docs requirements, instead of removing them.

[sean-lockwood]

@stscirij @starphire -
I believe this branch is ready for review.

[starphire]

Formatting looks good, and search bar removal probably is probably better off. Feel free to merge!

[stscirij]

The numpy/scipy docstring format calls for a space between a parameter and the colon (and most of the changes in this PR involve removing that space). Not exactly sure why, but jwst follows this practice.

[sean-lockwood]

@stscirij -

Ideally we shouldn't have to change the docstrings out of compliance. Just found something about the theme possibly causing problems with the colons in the parameter lists (stsci_rtd_theme in our case):

fsspec/filesystem_spec#1150

I'll look into this a bit more first.