Documentation facelift

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
+===
 
 .. automodapi:: specreduce
     :no-inheritance-diagram:

docs/background.rst

@@ -0,0 +1,29 @@
+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, and 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 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

@@ -33,7 +33,7 @@
 from specreduce import __version__
 
 try:
-    from sphinx_astropy.conf.v1 import *  # noqa
+    from sphinx_astropy.conf.v2 import *  # noqa
 except ImportError:
     print('ERROR: the documentation requires the sphinx-astropy package to be installed')
     sys.exit(1)
@@ -52,7 +52,7 @@
 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.
@@ -87,40 +87,46 @@
 
 # -- 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_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",
+        },
     }
+)
+
+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",
+}
+
+#html_theme_options = {
+#    'logotext1': 'spec',  # white,  semi-bold
+#    'logotext2': 'reduce',  # orange, light
+#    'logotext3': ':docs'   # white,  light
+#    }
 
 # Custom sidebar templates, maps document names to template names.
 #html_sidebars = {}
-html_sidebars['**'] = ['localtoc.html']
-html_sidebars['index'] = ['globaltoc.html', 'localtoc.html']
-
-# 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

docs/contributing.rst

@@ -0,0 +1,11 @@
+Contributing
+============
+
+Please feel free to contribute code and suggestions through `GitHub. <https://github
+.com/astropy/specreduce>`_
+
+.. toctree::
+    :maxdepth: 1
+
+    process/index
+    terms

docs/extraction.rst

@@ -0,0 +1,110 @@
+Spectrum Extraction
+===================
+
+The `specreduce.extract` module extracts a 1D spectrum from an input 2D spectrum
+(likely a background-extracted spectrum from the previous step) and a defined
+window, using one of the following implemented methods:
+
+* `~specreduce.extract.BoxcarExtract`
+* `~specreduce.extract.HorneExtract`
+
+Each of these takes the input image and trace as inputs (see the :ref:`api_index` for
+other required and optional parameters)
+
+.. code-block:: python
+
+  extract = specreduce.extract.BoxcarExtract(image-bg, trace, width=3)
+
+or
+
+.. code-block:: python
+
+  extract = specreduce.extract.HorneExtract(image-bg, trace)
+
+For the Horne algorithm, the variance array is required. If the input image is
+an `~astropy.nddata.NDData` object with ``image.uncertainty`` provided,
+then this will be used. Otherwise, the ``variance`` parameter must be set.
+
+.. code-block:: python
+
+  extract = specreduce.extract.HorneExtract(image-bg, trace, variance=var_array)
+
+An optional mask array for the image may be supplied to HorneExtract as well.
+This follows the same convention and can either be attached to ``image`` if it
+is an `~astropy.nddata.NDData` object, or supplied as a keyword argument.
+
+The extraction methods automatically detect non-finite pixels in the input
+image and combine them with the user-supplied mask to prevent them from biasing the
+extraction. In the boxcar extraction, the treatment of these pixels is controlled by
+the ``mask_treatment`` option. When set to ``exclude`` (the default), non-finite
+pixels within the extraction window are excluded from the extraction, and the extracted
+flux is scaled according to the effective number of unmasked pixels. When using other
+options (``filter`` or ``omit``), the non-finite values may be propagated or treated
+differently as documented in the API.
+
+The previous examples in this section show how to initialize the BoxcarExtract
+or HorneExtract objects with their required parameters. To extract the 1D
+spectrum
+
+.. code-block:: python
+
+  spectrum = extract.spectrum
+
+The ``extract`` object contains all the set options.  The extracted 1D spectrum
+can be accessed via the ``spectrum`` property or by calling (e.g ``extract()``)
+the ``extract`` object (which also allows temporarily overriding any values)
+
+.. code-block:: python
+
+  spectrum2 = extract(width=6)
+
+or, for example to override the original ``trace_object``
+
+.. code-block:: python
+
+  spectrum2 = extract(trace_object=new_trace)
+
+Spatial profile options
+-----------------------
+The Horne algorithm provides two options for fitting the spatial profile to the
+cross dispersion direction of the source: a Gaussian fit (default),
+or an empirical ``interpolated_profile`` option.
+
+If the default Gaussian option is used, an optional background model may be
+supplied as well (default is a 2D Polynomial) to account
+for residual background in the spatial profile. This option is not supported for
+``interpolated_profile``.
+
+If  the ``interpolated_profile`` option is used, the image will be sampled in various
+wavelength bins (set by ``n_bins_interpolated_profile``), averaged in those bins, and
+samples are then interpolated between (linear by default, interpolation degree can
+be set with ``interp_degree_interpolated_profile``, which defaults to linear in
+x and y) to generate an empirical interpolated spatial profile. Since this option
+has two optional parameters to control the fit, the input can either be a string
+to indicate that ``interpolated_profile`` should be used for the spatial profile
+and to use the defaults for bins and interpolation degree, or to override these
+defaults a dictionary can be passed in.
+
+For example, to use the ``interpolated_profile`` option with default bins and
+interpolation degree
+
+.. code-block:: python
+
+    interp_profile_extraction = extract(spatial_profile='interpolated_profile')
+
+Or, to override the default of 10 samples and use 20 samples
+
+.. code-block:: python
+
+    interp_profile_extraction = extract(spatial_profile={'name': 'interpolated_profile',
+                                    'n_bins_interpolated_profile': 20)
+
+Or, to do a cubic interpolation instead of the default linear
+
+.. code-block:: python
+
+    interp_profile_extraction = extract(spatial_profile={'name': 'interpolated_profile',
+                                    'interp_degree_interpolated_profile': 3)
+
+As usual, parameters can either be set when instantiating the HorneExtraxt object,
+or supplied/overridden when calling the extraction method on that object.