Update user documentation, add frequently asked questions section

[cshanahan1]

trafficstars

Overview of changes:

added overview of package and logo to landing page

• made a Getting Started section above User Documentation - Added a Quickstart guide to this section. - Below that, detailed install instructions and contribution guide, both of which have their own RST page but link to the github .md files (figured it was best to have this in one place so they don’t become out of sync, and they’re pretty thorough there).

• added a ‘frequently asked question’ section. When possible, I try to answer questions by expanding and linking to permanent sections in documentation so that the best answer doesn’t live alone in the FAQs.

• expanded and sectioned the sidebar to easier find pages

• expand toctrees on landing page to maxdepth == 2. In my personal opinion, this makes things much easier to find (especially in package index)

• reorganize and expand User Documentation section.

  • Begins with an intro to the pipeline, then an overview of the pipeline code.
  • Sections each for general topics relevant to both strun and Python interface
    • Reference files / CRDS
    • Parameters
    • Inputs and outputs
    • Available pipeline modules, datamodels.
  • A section each for running/configuring the pipeline w/ strun and w/ Python interface

[codecov[bot]]

Codecov Report

Base: 79.64% // Head: 79.64% // No change to project coverage :thumbsup:

Coverage data is based on head (df931b7) compared to base (f6b3973). Patch has no changes to coverable lines.

Additional details and impacted files

@@           Coverage Diff           @@
##           master    #6919   +/-   ##
=======================================
  Coverage   79.64%   79.64%           
=======================================
  Files         412      412           
  Lines       37572    37572           
=======================================
  Hits        29924    29924           
  Misses       7648     7648           

Flag	Coverage Δ		*Carryforward flag
nightly	79.62% <ø> (ø)		Carriedforward from f6b3973
unit	52.23% <ø> (+<0.01%)	:arrow_up:

*This pull request uses carry forward flags. Click here to find out more.

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

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

[zacharyburnett]

It looks like the following warnings are being flagged by RTD before the build proceeds: https://readthedocs.org/projects/jwst-pipeline/builds/18203877/

/home/docs/checkouts/readthedocs.org/user_builds/jwst-pipeline/checkouts/6919/docs/getting_started/faq.rst:13: WARNING: Inline interpreted text or phrase reference start-string without end-string.
/home/docs/checkouts/readthedocs.org/user_builds/jwst-pipeline/checkouts/6919/docs/getting_started/faq.rst:32: WARNING: Title underline too short.

How do I install an older version of the pipeline?
------------------------------------------------
/home/docs/checkouts/readthedocs.org/user_builds/jwst-pipeline/checkouts/6919/docs/getting_started/faq.rst:32: WARNING: Title underline too short.

How do I install an older version of the pipeline?
------------------------------------------------
/home/docs/checkouts/readthedocs.org/user_builds/jwst-pipeline/checkouts/6919/docs/getting_started/faq.rst:41: ERROR: Unexpected indentation.
/home/docs/checkouts/readthedocs.org/user_builds/jwst-pipeline/checkouts/6919/docs/getting_started/faq.rst:42: WARNING: Block quote ends without a blank line; unexpected unindent.
/home/docs/checkouts/readthedocs.org/user_builds/jwst-pipeline/checkouts/6919/docs/getting_started/faq.rst:136: WARNING: Title underline too short.

Can I create my own pipeline? # note to reviewer, is this answer right?
-----------------------------
/home/docs/checkouts/readthedocs.org/user_builds/jwst-pipeline/checkouts/6919/docs/getting_started/install.rst:47: WARNING: Explicit markup ends without a blank line; unexpected unindent.
/home/docs/checkouts/readthedocs.org/user_builds/jwst-pipeline/checkouts/6919/docs/getting_started/install.rst:64: WARNING: Explicit markup ends without a blank line; unexpected unindent.
/home/docs/checkouts/readthedocs.org/user_builds/jwst-pipeline/checkouts/6919/docs/getting_started/install.rst:75: WARNING: Explicit markup ends without a blank line; unexpected unindent.
/home/docs/checkouts/readthedocs.org/user_builds/jwst-pipeline/checkouts/6919/docs/getting_started/install.rst:85: ERROR: Unexpected indentation.
/home/docs/checkouts/readthedocs.org/user_builds/jwst-pipeline/checkouts/6919/docs/jwst/user_documentation/reference_files_crds.rst:10: WARNING: Definition list ends without a blank line; unexpected unindent.
/home/docs/checkouts/readthedocs.org/user_builds/jwst-pipeline/checkouts/6919/docs/jwst/user_documentation/reference_files_crds.rst:52: WARNING: Explicit markup ends without a blank line; unexpected unindent.
/home/docs/checkouts/readthedocs.org/user_builds/jwst-pipeline/checkouts/6919/docs/jwst/user_documentation/running_pipeline_command_line.rst:94: CRITICAL: Title level inconsistent:

Output Directory
^^^^^^^^^^^^^^^^
/home/docs/checkouts/readthedocs.org/user_builds/jwst-pipeline/checkouts/6919/docs/jwst/user_documentation/running_pipeline_command_line.rst:119: CRITICAL: Title level inconsistent:

Output File
^^^^^^^^^^^
/home/docs/checkouts/readthedocs.org/user_builds/jwst-pipeline/checkouts/6919/docs/jwst/user_documentation/running_pipeline_command_line.rst:159: CRITICAL: Title level inconsistent:

Override Reference File
^^^^^^^^^^^^^^^^^^^^^^^
/home/docs/checkouts/readthedocs.org/user_builds/jwst-pipeline/checkouts/6919/docs/jwst/user_documentation/running_pipeline_command_line.rst:178: WARNING: Explicit markup ends without a blank line; unexpected unindent.
/home/docs/checkouts/readthedocs.org/user_builds/jwst-pipeline/checkouts/6919/docs/jwst/user_documentation/running_pipeline_command_line.rst:178: CRITICAL: Title level inconsistent:

Skip
^^^^
/home/docs/checkouts/readthedocs.org/user_builds/jwst-pipeline/checkouts/6919/docs/jwst/user_documentation/running_pipeline_python.rst:162: WARNING: Explicit markup ends without a blank line; unexpected unindent.
/home/docs/checkouts/readthedocs.org/user_builds/jwst-pipeline/checkouts/6919/docs/jwst/user_documentation/running_pipeline_python.rst:185: ERROR: Unexpected indentation.
/home/docs/checkouts/readthedocs.org/user_builds/jwst-pipeline/checkouts/6919/docs/jwst/user_documentation/running_pipeline_python.rst:189: WARNING: Explicit markup ends without a blank line; unexpected unindent.

[zacharyburnett]

@cshanahan1 it is giving a warning about skip_step_cli, but I can't seem to find that anchor anywhere. Is it supposed to be in the faq.rst file?

/home/docs/checkouts/readthedocs.org/user_builds/jwst-pipeline/checkouts/6919/docs/getting_started/faq.rst:128: WARNING: undefined label: 'skip_step_cli'

[cshanahan1]

@cshanahan1 it is giving a warning about skip_step_cli, but I can't seem to find that anchor anywhere. Is it supposed to be in the faq.rst file?

/home/docs/checkouts/readthedocs.org/user_builds/jwst-pipeline/checkouts/6919/docs/getting_started/faq.rst:128: WARNING: undefined label: 'skip_step_cli'

i am working on that file right now and haven't commited it yet, stay tuned

[nden]

This needs a rebase again

[cshanahan1]

I addressed all the review comments, and rebased to add in the changes in #7342.

[cshanahan1]

any objections to merging?

[cshanahan1]

ok, merging then. since this is a lot of text, if there are any issues you spot let me know and i will fix it!

[nden]

🎉