Merge pull request #275 from hpparvi/documentation_facelift

Documentation facelift

Author: hpparvi

CHANGES.rst

@@ -1,3 +1,11 @@
+1.7.1 (2025-11-2x)
+------------------
+
+Other changes
+^^^^^^^^^^^^^
+
+- Changed to use ``sphinx_astropy.conf.v2`` and revised the documentation.
+
 1.7.0 (2025-11-13)
 ------------------
 

docs/_static/specreduce.css

@@ -1,15 +0,0 @@
-@import url("bootstrap-astropy.css");
-
-div.topbar a.brand {
-  background: transparent url("logo_icon.png") no-repeat 8px 3px;
-  background-image: url("logo_icon.png"), none;
-  background-size: 32px 32px;
-}
-
-#logotext1 {
-  color: #519EA8;
-}
-
-#logotext2 {
-  color: #FF5000;
-}

docs/api.rst

@@ -1,7 +1,7 @@
 .. _api_index:
 
-API Index
-=========
+API Reference
+=============
 
 .. automodapi:: specreduce
     :no-inheritance-diagram:

docs/background.rst

@@ -0,0 +1,34 @@
+Background correction
+=====================
+
+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, where each window is a region parallel to a
+`~specreduce.tracing.Trace`, offset from that `~specreduce.tracing.Trace` by a
+specified separation in the cross-dispersion direction, and extending over a
+specified width (also measured along the cross-dispersion axis) in pixels. The
+object can be generated with:
+
+* `~specreduce.background.Background`
+* `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
+`~specreduce.tracing.Trace`.
+
+.. code-block:: python
+
+  bg = specreduce.background.Background.one_sided(image, trace, separation=5, width=2)
+
+or, equivalently
+
+.. code-block:: python
+
+  bg = specreduce.background.Background.one_sided(image, 15, separation=5, width=2)
+
+The background image can be accessed via `~specreduce.background.Background.bkg_image`
+and the background-subtracted image via `~specreduce.background.Background.sub_image`
+(or ``image - bg``).
+
+The background and trace steps can be done iteratively, to refine an automated
+trace using the background-subtracted image as input.

docs/conf.py

@@ -27,116 +27,126 @@
 
 import sys
 import datetime
-
 import sphinx
 
 from specreduce import __version__
 
 try:
-    from sphinx_astropy.conf.v1 import *  # noqa
+    from sphinx_astropy.conf.v2 import *  # noqa
+    from sphinx_astropy.conf.v2 import extensions  # noqa
 except ImportError:
-    print('ERROR: the documentation requires the sphinx-astropy package to be installed')
+    print("ERROR: the documentation requires the sphinx-astropy package to be installed")
     sys.exit(1)
 
 # xref: https://github.com/sphinx-doc/sphinx/issues/13232#issuecomment-2608708175
 if sys.version_info[:2] >= (3, 13) and sphinx.version_info[:2] < (8, 2):
     import pathlib
-
     from sphinx.util.typing import _INVALID_BUILTIN_CLASSES
 
     _INVALID_BUILTIN_CLASSES[pathlib.Path] = "pathlib.Path"
 
 # -- General configuration ----------------------------------------------------
 
 # By default, highlight as Python 3.
-highlight_language = 'python3'
+highlight_language = "python3"
 
 # If your documentation needs a minimal Sphinx version, state it here.
-#needs_sphinx = '1.2'
+needs_sphinx = "3.0"
 
 # To perform a Sphinx version check that needs to be more specific than
 # major.minor, call `check_sphinx_version("x.y.z")` here.
 # check_sphinx_version("1.2.1")
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
-exclude_patterns.append('_templates')
+exclude_patterns.append("_templates")
 
 # This is added to the end of RST files - a good place to put substitutions to
 # be used globally.
-rst_epilog += """
-"""
+#rst_epilog += """
+#.. _Astropy: https://www.astropy.org/
+#"""
+
+extensions.extend(
+    [
+        "sphinx_design",
+        "nbsphinx",
+    ]
+)
 
 # -- Project information ------------------------------------------------------
 
 # This does not *have* to match the package name, but typically does
 project = "specreduce"
 author = "Astropy Specreduce contributors"
-copyright = '{0}, {1}'.format(
-    datetime.datetime.now().year, author)
+copyright = "{0}, {1}".format(datetime.datetime.now().year, author)
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
 # built documents.
 
 # The short X.Y version.
-version = __version__.split('-', 1)[0]
+version = __version__.split("-", 1)[0]
 # The full version, including alpha/beta/rc tags.
 release = __version__
 
 
 # -- Options for HTML output --------------------------------------------------
 
-# A NOTE ON HTML THEMES
-# The global astropy configuration uses a custom theme, 'bootstrap-astropy',
-# which is installed along with astropy. A different theme can be used or
-# the options for this theme can be modified by overriding some of the
-# variables set in the global configuration. The variables set in the
-# global configuration are listed below, commented out.
-
-
-# Add any paths that contain custom themes here, relative to this directory.
-# To use a different custom theme, add the directory containing the theme.
-#html_theme_path = []
-
-# The theme to use for HTML and HTML Help pages.  See the documentation for
-# a list of builtin themes. To override the custom theme, set this to the
-# name of a builtin theme or the name of a custom theme in html_theme_path.
-#html_theme = None
-html_static_path = ['_static']  # html_theme = None
-html_style = 'specreduce.css'
+html_static_path = ["_static"]  # html_theme = None
+html_style = "specreduce.css"
 
-
-html_theme_options = {
-    'logotext1': 'spec',  # white,  semi-bold
-    'logotext2': 'reduce',  # orange, light
-    'logotext3': ':docs'   # white,  light
+html_theme_options.update(
+    {
+        "github_url": "https://github.com/astropy/specreduce",
+        "use_edit_page_button": False,
+        "navigation_with_keys": False,
+        "logo": {
+            "text": f"{project}",
+            "image_light": "_static/logo_icon.png",
+            "image_dark": "_static/logo_icon.png",
+        },
+        "secondary_sidebar_items": {"**": ["page-toc"], "index": []},
     }
+)
+
+html_context = {
+    "default_mode": "light",
+    "version_slug": os.environ.get("READTHEDOCS_VERSION") or "",
+    "to_be_indexed": ["stable", "latest"],
+    "github_user": "astropy",
+    "github_repo": "specreduce",
+    "github_version": "main",
+    "doc_path": "docs",
+    "edit_page_url_template": "{{ astropy_custom_edit_url(github_user, github_repo, github_version, doc_path, file_name, default_edit_page_url_template) }}",
+    "default_edit_page_url_template": "https://github.com/{github_user}/{github_repo}/edit/{github_version}/{doc_path}{file_name}",
+    # Tell Jinja2 templates the build is running on Read the Docs
+    "READTHEDOCS": os.environ.get("READTHEDOCS", "") == "True",
+}
 
 # Custom sidebar templates, maps document names to template names.
-#html_sidebars = {}
-html_sidebars['**'] = ['localtoc.html']
-html_sidebars['index'] = ['globaltoc.html', 'localtoc.html']
+html_sidebars = {}
+html_sidebars['index'] = []
+html_sidebars["contributing"] = []
 
-# The name of an image file (relative to this directory) to place at the top
-# of the sidebar.
-#html_logo = ''
+# html_sidebars['**'] = ['localtoc.html']
+# html_sidebars['index'] = [] #['globaltoc.html', 'localtoc.html']
 
 # The name of an image file (within the static path) to use as favicon of the
 # docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
 # pixels large.
-html_favicon = '_static/logo_icon.ico'
+html_favicon = "_static/logo_icon.ico"
 
 # If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
 # using the given strftime format.
-#html_last_updated_fmt = ''
+# html_last_updated_fmt = ''
 
 # The name for this set of Sphinx documents.  If None, it defaults to
 # "<project> v<release> documentation".
-html_title = '{0} v{1}'.format(project, release)
+html_title = "{0} v{1}".format(project, release)
 
 # Output file base name for HTML help builder.
-htmlhelp_basename = project + 'doc'
+htmlhelp_basename = project + "doc"
 
 # Prefixes that are ignored for sorting the Python module index
 modindex_common_prefix = ["specreduce."]
@@ -145,18 +155,18 @@
 
 # Grouping the document tree into LaTeX files. List of tuples
 # (source start file, target name, title, author, documentclass [howto/manual]).
-latex_documents = [('index', project + '.tex', project + u' Documentation',
-                    author, 'manual')]
+latex_documents = [("index", project + ".tex", project + " Documentation", author, "manual")]
 
 
 # -- Options for manual page output -------------------------------------------
 
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
-man_pages = [('index', project.lower(), project + u' Documentation',
-              [author], 1)]
+man_pages = [("index", project.lower(), project + " Documentation", [author], 1)]
+
+# -- Options for numpydoc extension -------------------------------------------
+numpydoc_xref_param_type = False
 
-extensions.append('nbsphinx')
 
 # -- Options for the edit_on_github extension ---------------------------------
 
@@ -165,10 +175,10 @@
 nitpicky = True
 intersphinx_mapping.update(
     {
-        'astropy': ('https://docs.astropy.org/en/stable/', None),
-        'ccdproc': ('https://ccdproc.readthedocs.io/en/stable/', None),
-        'specutils': ('https://specutils.readthedocs.io/en/stable/', None),
-        'gwcs': ('https://gwcs.readthedocs.io/en/stable/', None)
+        "astropy": ("https://docs.astropy.org/en/stable/", None),
+        "ccdproc": ("https://ccdproc.readthedocs.io/en/stable/", None),
+        "specutils": ("https://specutils.readthedocs.io/en/stable/", None),
+        "gwcs": ("https://gwcs.readthedocs.io/en/stable/", None),
     }
 )
 #

docs/contributing.rst

@@ -0,0 +1,102 @@
+.. _contributors_guide:
+
+Contributing
+============
+
+As with all `Astropy <https://www.astropy.org>`_ coordinated packages, **Specreduce** is
+developed *by* the astrophysics community, *for* the astrophysics community. We warmly welcome
+contributions of all kinds, whether it’s sharing feedback, reporting bugs, suggesting new
+features, or improving code and documentation. Every contribution, big or small, helps make
+Specreduce more useful and reliable for everyone.
+
+Specreduce follows the `Astropy development and contribution guidelines
+<https://docs.astropy.org/en/latest/index_dev.html>`_ and the
+`Astropy Community Code of Conduct <https://www.astropy.org/code_of_conduct.html>`_.
+By contributing, you agree to uphold these community standards, which help ensure that the
+project remains a welcoming and inclusive space for all contributors.
+
+Getting Started
+---------------
+
+If you’re new to open-source development or to the Astropy ecosystem, do not worry. The best place
+to start is by visiting the
+`Specreduce GitHub repository <https://github.com/astropy/specreduce>`_,
+where you can find current issues, pull requests, and the latest development activity.
+
+Before you begin contributing code, you may want to:
+
+* Read through the Astropy developer documentation linked above.
+* Explore the existing documentation and tutorials to get a sense of how Specreduce works.
+* Comment on an issue to let others know you’d like to work on it — or open a new issue to
+  discuss an idea or feature you’d like to propose.
+
+Roadmap
+-------
+
+.. image::
+   roadmap.png
+   :align: center
+   :width: 100%
+
+Contribute feedback
+-------------------
+
+The Specreduce team values feedback from all users. If something doesn’t work as expected,
+if you encounter a bug, or if you have an idea for an improvement, please let us know by opening
+a new issue on the
+`Specreduce GitHub issue tracker <https://github.com/astropy/specreduce/issues>`_.
+
+For bug reports, please include:
+
+* A short description of the problem.
+* The version of Specreduce and Python you are using.
+* A minimal example (if possible) that reproduces the issue.
+
+For feature requests or usability feedback, describe your idea clearly and explain how it would
+improve the user experience. Even short notes are valuable and help guide development priorities.
+
+
+Contribute Code or Documentation
+--------------------------------
+
+If you see an open issue you’d like to work on, or if you’ve spotted an error or missing detail
+in the documentation, you can submit your own improvements through GitHub.
+To get started:
+
+1. Fork the Specreduce repository and create a new branch for your changes.
+2. Make your edits or additions, whether it’s a bug fix, a new feature, or a documentation update.
+3. Commit your changes with a clear message describing what you did.
+4. Open a pull request to the main repository.
+
+Contribute Tutorials and Examples
+---------------------------------
+
+Tutorials and worked examples are among the most valuable contributions. They help other users
+learn from real data and see how different tools fit together in practice.
+
+While the main steps of spectroscopic reduction (for example, tracing, extraction, and wavelength
+calibration) are similar across most instruments, the best workflow can still depend on the
+setup and science goals. In the long term, we aim to build a library of example reduction recipes
+for different instruments that users can adapt for their own observations.
+
+If you have a reduction example, a notebook, or a teaching resource that might help others,
+please share it, either by opening a pull request or by discussing it in an issue first.
+We’re happy to help with formatting and integration into the documentation.
+
+Staying in Touch
+----------------
+
+Development discussions happen mainly on GitHub, but you can also connect with the wider Astropy
+community through the `Astropy Discussion Forum <https://community.openastronomy.org/c/astropy/>`_,
+where you can ask questions, share ideas, and get advice from other developers and users.
+
+Your contributions help make Specreduce and the Astropy ecosystem stronger and more sustainable.
+Whether you fix a typo, improve a function, or share a new example, you are helping build a tool
+that benefits the entire astrophysics community. Thank you for being part of it!
+
+.. toctree::
+    :maxdepth: 1
+    :hidden:
+
+    process/index
+    terms