Documentation facelift #275

hpparvi · 2025-06-25T15:18:15Z

This PR modernizes the documentation by adopting sphinx_astropy.conf.v2 with the pydata-sphinx-theme. It also updates and reorganizes several existing sections and introduces new documentation covering 1D wavelength calibration.

codecov · 2025-06-25T15:19:54Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 89.57%. Comparing base (5a58333) to head (3e0af09).
⚠️ Report is 43 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #275      +/-   ##
==========================================
+ Coverage   89.52%   89.57%   +0.04%     
==========================================
  Files          17       17              
  Lines        1795     1803       +8     
==========================================
+ Hits         1607     1615       +8     
  Misses        188      188

☔ 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.

tepickering · 2025-07-01T03:18:24Z

not sure if it fits in this PR or a future one, but we have a lot of example docs implemented within docstrings in various parts of the code (i am one of the guilty parties). as part of a fuller refactor, we should decide whether to leave that as-is, migrate it to specific .rst files, or refactor all examples into notebooks or something notebook-based. i think the last option is the most useful going forward, but the most work up-front.

hpparvi · 2025-10-28T20:23:40Z

The documentation update is coming together! Please take a look at the rendered docs at
https://specreduce--275.org.readthedocs.build/en/275/index.html and let me know your thoughts.

No need to worry about the large number of commits and changed files. This PR builds on the 1D wavelength calibration PR, which should be merged first.

…text.

….toml`.

- Added `sphinx-copybutton` and `sphinx-design` to documentation dependencies in `pyproject.toml`. - Improved content structure by renaming and reorganizing documentation files. - Expanded "Contributing" and "Index" sections.

…action examples; updated `conf.py` with formatting adjustments and extended Sphinx documentation settings.

- Corrected typos and clarified text. - Renamed `common.py` to `quickstart.py`. - Updated function and variable names for consistency. - Streamlined background subtraction and wavelength calibration workflows.

…uncertainty handling.

…tdDevUncertainty` when absent.

…doc_xref_param_type` configuration.

cshanahan1 · 2025-11-18T17:52:43Z

docs/background.rst

+* `Background.one_sided <specreduce.background.Background.one_sided>`
+* `Background.two_sided <specreduce.background.Background.two_sided>`
+
+The center of the window can either be passed as a float/integer or as a trace


specify that trace is a ~specreduce.tracing.Trace

cshanahan1 · 2025-11-18T17:54:22Z

docs/background.rst

+
+The `specreduce.background` module generates and subtracts a background image from
+the input 2D spectral image.  The `~specreduce.background.Background` object is
+defined by one or more windows, and can be generated with:


can you clarify what 'windows' means in this context (maybe using trace, separation and width in the description)?

cshanahan1 · 2025-11-18T18:02:07Z

docs/contributing.rst

+3. Commit your changes with a clear message describing what you did.
+4. Open a pull request to the main repository.
+
+.. If you’re unsure how to start, you can look for issues labeled


uncomment this section

I decided to remove it completely for now. I still need to organise the issue labels better.

cshanahan1 · 2025-11-18T18:05:10Z

docs/extraction.rst

-
-Example Workflow
-================
+                                    'n_bins_interpolated_profile': 20)


missing closing brace

Great catch! Fixed.

cshanahan1 · 2025-11-18T18:05:32Z

docs/extraction.rst

-    from specreduce.background import Background
-    from specreduce.extract import BoxcarExtract
+    interp_profile_extraction = extract(spatial_profile={'name': 'interpolated_profile',
+                                    'interp_degree_interpolated_profile': 3)


missing closing brace

this is why my personal style is to put one parameter per line and indent. helps make it clearer what ) or } belongs to what ( or { and when one is missing.

True. These two examples are now formatted more neatly.

cshanahan1 · 2025-11-18T18:11:50Z

docs/index.rst

+            **Contributor's Guide**
+            ^^^^^^^^^^^^^^^^^^^^^^^
+
+            Want to contribute to specreduce? Found a bug? The contributing guidelines will


capitalize 'specreduce'

cshanahan1 · 2025-11-18T18:12:50Z

docs/index.rst

-    process/index
-    terms

+..  * :ref:`genindex`


uncomment/remove

cshanahan1 · 2025-11-18T18:13:16Z

docs/trace.rst

@@ -0,0 +1,166 @@
+Tracing


does this need a reference at the top as well?

cshanahan1 · 2025-11-18T18:14:44Z

docs/trace.rst

+the 2D spectral image as input, along with trace-specific parameters that control how the trace
+is determined.
+
+Flat trace


FlatTrace, for consistency with other section headings

cshanahan1 · 2025-11-18T18:15:37Z

docs/trace.rst

+
+.. code-block:: python
+
+    trace = specreduce.tracing.ArrayTrace(image, positions)


can you define positions in a line of code, or explain what it is above

I modified the text a bit to make it clear.

tepickering

looks good to me! i mostly agree with the comments @cshanahan1 left and added a few more, but think they're all pretty minor. the new style looks SOOO much better! there's some more work to do to better organize some parts, but this sets up a much better, more usable foundation for that.

tepickering · 2025-11-19T01:37:37Z

docs/extraction.rst

-    from specreduce.background import Background
-    from specreduce.extract import BoxcarExtract
+    interp_profile_extraction = extract(spatial_profile={'name': 'interpolated_profile',
+                                    'interp_degree_interpolated_profile': 3)


this is why my personal style is to put one parameter per line and indent. helps make it clearer what ) or } belongs to what ( or { and when one is missing.

tepickering · 2025-11-19T01:42:35Z

docs/getting_started/installation.rst

+
+    conda install conda-forge::specreduce
+
+or by cloning the repository from `GitHub <https://github.com/astropy/specreduce>`_


is cloning from the repo something we want normal users to do? my feeling is that's more for a developer install.

I like to remind users that this is an option. It's useful to have it clearly documented for anyone who wants to have the option to examine the code if something doesn't work as expected or as they'd like.

tepickering · 2025-11-19T01:53:31Z

docs/getting_started/quickstart.py

+from specreduce.utils.synth_data import make_2d_arc_image, make_2d_trace_image
+
+
+def make_2d_spec_image(


is there a reason this function was lifted from synth_data and not just updated there?

The main reason for this was to make minor modifications to the mock spectrum without altering how the original function in synth_data works (this would've been more work, and I didn't feel this sort of change belonged in a documentation update PR).

that's fair. i like the addition of the ability to add an airglow spectrum. i'll have a think about how to make the synth data utilities more easily composable.

hpparvi · 2025-11-19T21:36:40Z

Thanks @cshanahan1 and @tepickering! The PR is now merged :)

…opy/specreduce#275 has been merged.

hpparvi force-pushed the documentation_facelift branch from 7ee2d16 to c7344e7 Compare October 21, 2025 21:25

hpparvi marked this pull request as ready for review October 28, 2025 20:13

hpparvi requested review from camipacifici, cshanahan1, kecnry and tepickering October 28, 2025 20:29

hpparvi mentioned this pull request Nov 7, 2025

1D Wavelength Calibration #265

Merged

hpparvi and others added 20 commits November 15, 2025 19:42

Switching to use sphinx astropy conf v2 with the PyData theme.

0898b46

Restructuring the documentation without adding anything new.

5f00c3a

Revised tracing documentation.

85bd668

Revised tracing documentation.

75fff87

Revised documentation.

87176b9

Added basic plots to the specreduce.tracing docs and revised the …

503d7c4

…text.

Revised extraction_quickstart.rst.

dfbb443

Cleaned up and revised the documentation.

627d770

Revised the tracing documentation.

29799f4

Revised index.rst.

92189fc

Added sphinx-copybutton to documentation dependencies in `pyproject…

ff228f1

….toml`.

Updated sphinx-astropy dependency to use confv2 in pyproject.toml.

6346f5c

Added "Quickstart" Jupyter notebook and common.py for spectrum extr…

4420480

…action examples; updated `conf.py` with formatting adjustments and extended Sphinx documentation settings.

Revised the documentation.

f218779

Continued working on the expanded quickstart guide.

51975e2

Minor documentation fixes.

11d8f0d

Continued working on the quickstart guide.

0562110

Updated and improved the "Quickstart" Jupyter notebook:

1114e46

- Corrected typos and clarified text. - Renamed `common.py` to `quickstart.py`. - Updated function and variable names for consistency. - Streamlined background subtraction and wavelength calibration workflows.

Removed unnecessary warning for standard deviation interpretation in …

130a997

…uncertainty handling.

hpparvi added 11 commits November 15, 2025 19:42

Handled missing uncertainty in spectrum processing by initializing `S…

04cf06b

…tdDevUncertainty` when absent.

Removed the test for StdDevUncertainty warning in extraction.

11c9192

Minor docstring-related revisions.

89369fd

Revised the documentation.

c0e9642

Enabled sphinx_design and nbsphinx extensions, and updated `numpy…

ee13303

…doc_xref_param_type` configuration.

Documentation cleanup.

62ede6e

Corrected default trace_coeffs initialization in synth_data.py.

88b9b90

Revised contributing docs.

b578f99

Fixed a typo in contributing.rst

58495f9

Minor documentation style cleanup.

448b09f

Added a roadmap figure to main index and contributing guide.

d4d0c76

hpparvi force-pushed the documentation_facelift branch from c6a96b5 to d4d0c76 Compare November 15, 2025 18:43

hpparvi added 4 commits November 15, 2025 19:56

Added more line_matching tests.

2382b74

Revised line_matching function docstrings.

3fe11ba

Updated the roadmap figure.

a6ec116

Revised changelog.

a058f10

cshanahan1 reviewed Nov 18, 2025

View reviewed changes

tepickering approved these changes Nov 19, 2025

View reviewed changes

hpparvi added 7 commits November 19, 2025 21:41

Revised background.rst.

84ef844

Revised contributing.rst.

303da8a

More extraction documentation cleanup.

925f383

Revised trace.rst.

e0f9377

Further extraction documentation cleanup.

015ae26

Minor documentation cleanup.

0988e81

Continued documentation cleanup.

3e0af09

hpparvi merged commit e634aee into astropy:main Nov 19, 2025
12 checks passed

hpparvi added a commit to hpparvi/astropy-project that referenced this pull request Nov 20, 2025

Revised parviainen_specreduce.md to account for the fact that PR astr…

20dbd2e

…opy/specreduce#275 has been merged.


		.. code-block:: python

		trace = specreduce.tracing.ArrayTrace(image, positions)


		conda install conda-forge::specreduce

		or by cloning the repository from `GitHub <https://github.com/astropy/specreduce>`_

		from specreduce.utils.synth_data import make_2d_arc_image, make_2d_trace_image


		def make_2d_spec_image(

Uh oh!

Documentation facelift #275

Documentation facelift #275

Uh oh!

Conversation

hpparvi commented Jun 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

codecov bot commented Jun 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

tepickering commented Jul 1, 2025

Uh oh!

hpparvi commented Oct 28, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

tepickering left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

hpparvi commented Nov 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

hpparvi commented Jun 25, 2025 •

edited

Loading

codecov bot commented Jun 25, 2025 •

edited

Loading

hpparvi commented Nov 19, 2025 •

edited

Loading