DOC: Complete API for AMI analyze and normalize

[pllim]

Towards JP-4107

This PR addresses AMI portion of #9793 . Only touch docs so should not need RT.

On main:

• https://jwst.readthedocs.io/en/latest/jwst/ami_analyze/index.html
• https://jwst.readthedocs.io/en/latest/jwst/ami_normalize/index.html

With this patch:

• https://jwst-pipeline--10095.org.readthedocs.build/en/10095/jwst/ami_analyze/index.html
• https://jwst-pipeline--10095.org.readthedocs.build/en/10095/jwst/ami_normalize/index.html

Tasks

• If you have a specific reviewer in mind, tag them.
• add a build milestone, i.e. Build 12.0 (use the latest build if not sure)
• Does this PR change user-facing code / API? (if not, label with no-changelog-entry-needed)
  • write news fragment(s) in changes/: echo "changed something" > changes/<PR#>.<changetype>.rst (see changelog readme for instructions)
  • update or add relevant tests
  • update relevant docstrings and / or docs/ page
  • start a regression test and include a link to the running job (click here for instructions)
    • Do truth files need to be updated ("okified")?
      • after the reviewer has approved these changes, run okify_regtests to update the truth files
• if a JIRA ticket exists, make sure it is resolved properly

[pllim]

Whatever layout and presentation style we decide on in this PR would be used as a basis for the rest of the package. Doing the entire package at once would make the PR hard to review and also drag on for too long, causing conflict and wasting developer time, so let's start with AMI (alphabetically selected).

My main priority is fixing doc build warning. Any violation that does not trigger warning (e.g., malformed listing), I will fix if I happen to notice or be asked to only. Beautifying and vetting API doc contents is out of scope here (and would also drag things on). My ticket is only to expose them.

For my sanity, I also alphabetized the intersphinx listing in this PR.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 85.88%. Comparing base (1193035) to head (5e57aba).
⚠️ Report is 29 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main   #10095      +/-   ##
==========================================
+ Coverage   85.72%   85.88%   +0.16%     
==========================================
  Files         367      365       -2     
  Lines       38235    38210      -25     
==========================================
+ Hits        32776    32818      +42     
+ Misses       5459     5392      -67     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[emolter]

Overall I'm on board with exposing all our API, but I feel pretty strongly that we need to define a deprecation policy, i.e write down what we consider "public" in the sense that we won't change it without warning. It's one thing to change API that's not documented in a minor release with no change log, which we've been doing for a long time, and another to change that API when it's documented in the readthedocs.

edit: lol, went to my next notification and it's a PR from you that would do the above. I guess this is just a note then that I'd probably prefer if that one went in first.

I've seen a few typos and things that don't render right within docs that you didn't touch here. Do you want me to flag those, and basically have a careful read through everything that's newly rendered here? If so, it'll take longer - there are a lot of new docstrings exposed here.

[pllim]

Do you want me to flag those

Sure. But as I commented in #10095 (review) , carefully reading through all the docs would take too long and probably not worth the cost. Once they are exposed, if user complain about some typo later, we can fix as needed.

However if you already noticed them and point them out exactly where, I can fix up real quick as part of this PR.

I guess this is just a note then that I'd probably prefer if that one went in first.

@melanieclarke told me to prioritize this ticket first. But that said, the whole ticket is going to take a while. This is just AMI stuff. So chances are the policy (#10096) would actually go in first before this ticket is done as a whole. Not sure if this elevates your concern or not.

[pllim]

Re: #10095 (comment)

I removed the offending periods and added Ned as commit co-author. I will mark the comment as resolved to ease future review handling. Thanks!

[emolter]

Thanks Pey-Lian, this is looking good. I noticed a few small things.

[pllim]

Okay, I think I have addressed the comments from yesterday. Please re-review. Thanks!

[emolter]

I think all my questions have been answered

[pllim]

Thanks for the reviews! I think just need @melanieclarke to approve now then this can be merged.

[melanieclarke]

Looks great, thanks!