Skip to content

Expand the README and the documentation landing page - #54

Merged
roytsmart merged 2 commits into
mainfrom
docs/readme-and-landing-page
Aug 19, 2026
Merged

Expand the README and the documentation landing page#54
roytsmart merged 2 commits into
mainfrom
docs/readme-and-landing-page

Conversation

@roytsmart

Copy link
Copy Markdown
Contributor

The README and the landing page
both described the library in one sentence and showed a single example, loading
a frame and displaying it. Nothing told the reader that the package splits a
frame into its four taps, measures and removes the bias, or models the sensor,
so the most useful parts of the API were reachable only by browsing the
autosummary.

Both pages

  • List the public API: fits.open, SensorData, TapData, ImageHeader,
    Camera, TeledyneCCD230, and samples.
  • Add a Key concepts section covering what a reader needs before the
    calibration steps make sense: an image pairs pixel values with the header
    describing them, the sensor is read out through four taps that each have
    their own amplifier and so their own bias, the 50 blank and 2 overscan
    columns per tap are what measures that bias, and .electrons needs a gain
    that has to be measured.

Landing page

Three new examples after the existing one: measuring the per-tap bias and
removing it, reading the header, and inspecting the sensor model. The corrected
frame is a much better picture of what this data is than the raw one, since
subtracting the ~3600 DN bias reveals the individual Fe55 X-ray events.

The original example keeps its position, so _images/index_0_0.png, already
linked from the README, still resolves. The new figure is index_2_0.png.

Verification

Built the docs locally: build succeeded, and the only warnings come from
excluding the report notebooks, which this environment cannot build because
pandoc is not installed. Every snippet was run to capture its real output,
and all 15 API cross references in the new prose resolve to real pages.

One thing worth knowing

While exercising the API for these examples I found that .electrons is broken
for any image loaded through msfc_ccd.fits.open:

img = msfc_ccd.fits.open(msfc_ccd.samples.path_fe55_esis1)
img.electrons   # TypeError: 'NoneType' object is not subscriptable

Camera.gain defaults to None and, unlike Camera.sensor, nothing resolves
it, so dn_to_electrons computes None * a and the failure surfaces later in
from_taps. Passing an explicit gain works. That is a code fix rather than a
docs fix, so it is not in this pull request; the documentation states that a
gain must be supplied, which is true either way.

🤖 Generated with Claude Code

@codecov

codecov Bot commented Aug 19, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 100.00%. Comparing base (b3d6fda) to head (5120386).

Additional details and impacted files
@@            Coverage Diff            @@
##              main       #54   +/-   ##
=========================================
  Coverage   100.00%   100.00%           
=========================================
  Files           19        19           
  Lines          875       875           
=========================================
  Hits           875       875           
Flag Coverage Δ
unittests 100.00% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 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.

roytsmart and others added 2 commits August 19, 2026 13:18
Both pages described the library in one sentence and showed a single example,
loading a frame and displaying it, which left the reader with no idea that the
package splits a frame into its four taps, measures and removes the bias, or
models the sensor.

Both pages now list the public API, and add a "Key concepts" section covering
what a reader has to know to use the calibration steps: an image pairs pixel
values with the header that describes them, the sensor is read out through four
taps which each have their own bias, the blank and overscan columns are what
measures that bias, and converting to electrons needs a gain that has to be
measured.

The landing page gains three examples: measuring and removing the per-tap bias,
reading the header, and inspecting the sensor model. The README shows the same
examples with their real output. The original example keeps its position, so
the figure link already in the README still resolves.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
#55 made `dn_to_electrons` raise a `ValueError` naming the missing parameter,
rather than silently producing an image whose outputs are `None`. Say so, since
a reader who reaches for `.electrons` will now meet that error, and note that
the gain differs from tap to tap.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@roytsmart
roytsmart force-pushed the docs/readme-and-landing-page branch from 454dba2 to 5120386 Compare August 19, 2026 19:20
@roytsmart
roytsmart merged commit b18f489 into main Aug 19, 2026
11 checks passed
@roytsmart
roytsmart deleted the docs/readme-and-landing-page branch August 19, 2026 19:29
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant