new scripts and templates to support the User Manual for primitives a…

…nd recipes.

geminidr/core/primitives_ccd.py

@@ -128,10 +128,10 @@ def subtractOverscan(self, adinputs=None, **params):
         region be a vertical strip) is determined in one of the following
         ways, according to the *function* and *order* parameters:
 
-        "poly":   a polynomial of degree *order* (1=linear, etc)
-        "spline": using *order* equally-sized cubic spline pieces or, if
+        :"poly":   a polynomial of degree *order* (1=linear, etc)
+        :"spline": using *order* equally-sized cubic spline pieces or, if
                   order=None or 0, a spline that provides a reduced chi^2=1
-        "none":   no function is fit, and the value for each row is determined
+        :"none":   no function is fit, and the value for each row is determined
                   by the overscan pixels in that row
 
         The fitting is done iteratively but, in the first instance, a running

geminidr/doc/usermanuals/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

geminidr/doc/usermanuals/README

@@ -0,0 +1,44 @@
+Generating the primitive documentation.
+---------------------------------------
+There are two steps:
+
+1) run the script to generate the docs from the docstrings and the parameter
+   files.
+     utility_scripts/generate_primdoc.py -d primitives/generated-doc
+
+2) use the template to write the primitive_name.rst file that will load the
+   generated subsections.   The template is "primmitive_createExample.rst" in
+   "examples".   This is a manual, human-driven task.
+
+
+
+
+
+Generating the recipe documentation.
+------------------------------------
+There are two steps:
+
+1) run the script to generate the automated part.
+      The generated file should have:
+        * name of the recipe (as heading with ====)
+        * module and name of recipe library
+        * recipe tags
+        * docstring which should include the type of inputs (tags) required.
+        * the recipe
+
+2) Then manually create the .rst that put them all together and adds additional
+   comments.
+   The
+
+
+Development
+-----------
+
+Dev and test for primitives
+* To try it out:
+   utility_scripts/generate_primdoc.py core gmos -d testdoc
+
+Dev and test for recipes
+
+* ./generate_recipedoc.py gmos -d testdoc
+

geminidr/doc/usermanuals/_static/css/code.xref-styles.css

@@ -0,0 +1,16 @@
+
+/* , a .rst-content tt, a .rst-content code */
+
+.rst-content code.xref {
+    background-color: transparent;
+    border: solid 1px transparent;
+    color: #2980B9;
+    padding: 0px 0px;
+    font-size: 80%;
+    }
+
+.rst-content code.xref:hover {
+    /* border: solid 1px #e1e4e5; */
+    text-decoration: underline;
+    }
+

geminidr/doc/usermanuals/_static/css/fonts.css

@@ -0,0 +1,36 @@
+.red {
+  color: red;
+}
+
+.blue {
+  color: blue;
+}
+
+.green {
+  color: green;
+}
+
+.yellow {
+  color: yellow;
+}
+
+.gray {
+  color: gray;
+}
+
+.lightgray {
+  color: lightgray;
+}
+
+.small {
+  font-size: 80%;
+}
+
+.large {
+  font-size: 120%;
+}
+
+.bolditalic {
+  font-weight: bold;
+  font-style: italic;
+}

geminidr/doc/usermanuals/_static/css/rtd_theme_overrides.css

@@ -0,0 +1,20 @@
+/* override RTD table width restrictions */
+
+@media screen and (min-width: 767px) {
+
+  .wy-table-responsive table td, .wy-table-responsive table th {
+      /* !important prevents the common CSS stylesheets from 
+         overriding this as on RTD the are loaded after this stylesheet */
+      white-space: normal !important;
+  } 
+
+  .wy-table-responsive {
+      /* margin-bottom: 24px; */ 
+      /* max-width: 100%; */
+      overflow: visible !important;
+  }
+
+  .wy-nav-content {
+      max-width: 1200px !important;
+  }
+}

geminidr/doc/usermanuals/_static/css/todo-styles.css

@@ -0,0 +1,7 @@
+div.admonition-todo {
+border-top: 2px solid red;
+border-bottom: 2px solid red;
+border-left: 2px solid red;
+border-right: 2px solid red;
+background-color: #ff6347
+}

geminidr/doc/usermanuals/conf.py

@@ -0,0 +1,150 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+# import os
+# import sys
+# sys.path.insert(0, os.path.abspath('.'))
+
+
+# -- Project information -----------------------------------------------------
+
+project = 'DRAGONS Data Reduction User Reference'
+copyright = '2023, Association of Universities for Research in Astronomy'
+author = 'DRAGONS Team'
+
+# The short X.Y version
+version = '3.1'
+
+# The full version, including alpha/beta/rc tags
+release = '3.1.1-dev'
+#rtdurl = 'v'+release
+#rtdurl = 'release-'+release
+rtdurl = 'latest'
+
+
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+    'sphinx.ext.todo',
+]
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# The suffix(es) of source filenames.
+# You can specify multiple suffix as a list of string:
+#
+# source_suffix = ['.rst', '.md']
+source_suffix = '.rst'
+
+# The master toctree document.
+master_doc = 'index'
+
+# There are two options for replacing |today|: either, you set today to some
+# non-false value, then it is used:
+today = 'May 2023'
+# Else, today_fmt is used as the format for a strftime call.
+#today_fmt = '%B %d, %Y'
+
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = None
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+#html_theme = 'alabaster'
+html_theme = 'sphinx_rtd_theme'
+
+# The name of an image file (relative to this directory) to place at the top
+# of the sidebar.
+#html_logo = None
+html_logo = "_static/img/DRAGONS - Icon blue.png"
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']
+
+# -- Options for LaTeX output ------------------------------------------------
+
+latex_elements = {
+    # The paper size ('letterpaper' or 'a4paper').
+    #
+    # 'papersize': 'letterpaper',
+
+    # The font size ('10pt', '11pt' or '12pt').
+    #
+    # 'pointsize': '10pt',
+
+    # Additional stuff for the LaTeX preamble.
+    #
+    # 'preamble': '',
+
+    # Latex figure (float) alignment
+    #
+    # 'figure_align': 'htbp',
+}
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title,
+#  author, documentclass [howto, manual, or own class]).
+latex_documents = [
+    (master_doc, 'DRAGONSDRUserReference.tex', 'DRAGONS Data Reduction User Reference',
+     'DRAGONS Team', 'manual'),
+]
+
+# -- Options for todo extension ----------------------------------------------
+
+# If true, `todo` and `todoList` produce output, else they produce nothing.
+todo_include_todos = True
+
+
+# -- Finishing with a setup that will run always -----------------------------
+def setup(app):
+
+    # -- Adding custom styles ---
+    app.add_css_file('css/todo-style.css')
+    app.add_css_file('css/rtf_theme_overrides.css')
+    app.add_css_file('css/fonts.css')
+    app.add_css_file('css/code.xref-styles.css')
+
+rst_epilog = """
+.. role:: raw-html(raw)
+   :format: html
+
+.. |caldb| replace:: :raw-html:`<a href="https://dragons-recipe-system-users-manual.readthedocs.io/en/{v}/caldb.html" target="_blank">caldb</a>`
+.. |dataselect| replace:: :raw-html:`<a href="https://dragons-recipe-system-users-manual.readthedocs.io/en/{v}/supptools.html#dataselect" target="_blank">dataselect</a>`
+.. |descriptors| replace:: :raw-html:`<a href="https://astrodata-user-manual.readthedocs.io/en/{v}/appendices/appendix_descriptors.html" target="_blank">descriptors</a>`
+.. |descriptor| replace:: :raw-html:`<a href="https://astrodata-user-manual.readthedocs.io/en/{v}/appendices/appendix_descriptors.html" target="_blank">descriptors</a>`
+.. |reduce| replace:: :raw-html:`<a href="https://dragons-recipe-system-users-manual.readthedocs.io/en/{v}/reduce.html" target="_blank">reduce</a>`
+.. |showd| replace:: :raw-html:`<a href="https://dragons-recipe-system-users-manual.readthedocs.io/en/{v}/supptools.html#showd" target"_blank">showd</a>`
+.. |showrecipes| replace:: :raw-html:`<a href="https://dragons-recipe-system-users-manual.readthedocs.io/en/{v}/supptools.html#showrecipes" target="_blank">showrecipes</a>`
+.. |showpars| replace:: :raw-html:`<a href="https://dragons-recipe-system-users-manual.readthedocs.io/en/{v}/supptools.html#showpars" target="_blank">showpars</a>`
+.. |typewalk| replace:: :raw-html:`<a href="https://dragons-recipe-system-users-manual.readthedocs.io/en/{v}/supptools.html#typewalk" target="_blank">typewalk</a>`
+.. |atfile| replace:: :raw-html:`<a href="https://dragons-recipe-system-users-manual.readthedocs.io/en/{v}/reduce.html#the-file-facility" target="_blank">"at-file" Facility</a>`
+.. |astrodatauser| replace:: :raw-html:`<a href="https://astrodata-user-manual.readthedocs.io/en/{v}/" target="_blank">Astrodata User Manual</a>`
+
+.. |RSUser|  replace:: :raw-html:`<a href="http://dragons-recipe-system-users-manual.readthedocs.io/en/{v}/">Recipe System Users Manual</a>`
+
+""".format(v = rtdurl)

geminidr/doc/usermanuals/examples/primitives/generated_doc/geminidr.core.primitives_ccd.CCD.subtractOverscan_docstring.rst

@@ -0,0 +1,34 @@
+
+This primitive subtracts the overscan level from the image. The
+level for each row (currently the primitive requires that the overscan
+region be a vertical strip) is determined in one of the following
+ways, according to the *function* and *order* parameters:
+
+:"poly":   a polynomial of degree *order* (1=linear, etc)
+:"spline": using *order* equally-sized cubic spline pieces or, if
+          order=None or 0, a spline that provides a reduced chi^2=1
+:"none":   no function is fit, and the value for each row is determined
+          by the overscan pixels in that row
+
+The fitting is done iteratively but, in the first instance, a running
+median of the rows is calculated and rows that deviate from this median
+are rejected (and used in place of the actual value if function="none")
+
+Parameters
+----------
+suffix: str
+    suffix to be added to output files
+niterate: int
+    number of rejection iterations
+high_reject: float/None
+    number of standard deviations above which to reject high pixels
+low_reject: float/None
+    number of standard deviations above which to reject low pixels
+nbiascontam: int/None
+    number of columns adjacent to the illuminated region to reject
+function: str/None
+    function to fit ("chebyshev" | "spline" | "none")
+order: int/None
+    order of polynomial fit or number of spline pieces
+bias_type: str
+    For multiple overscan regions, selects which one to use

geminidr/doc/usermanuals/examples/primitives/generated_doc/geminidr.core.primitives_ccd.CCD.subtractOverscan_param.rst

@@ -0,0 +1,23 @@
+Parameter defaults and options
+------------------------------
+::
+
+   function             'spline3'            Fitting function
+      Allowed values:
+      	none	Row-by-row values
+      	spline3	Cubic spline
+      	chebyshev	Chebyshev polynomial
+      
+   order                None                 Order of fitting function
+      	Valid Range = [0,inf)
+   lsigma               3.0                  Low rejection in sigma of fit
+      	Valid Range = [0,inf)
+   hsigma               3.0                  High rejection in sigma of fit
+      	Valid Range = [0,inf)
+   niter                0                    Maximum number of rejection iterations
+      	Valid Range = [0,inf)
+   grow                 0                    Rejection growing radius
+      	Valid Range = [0,inf)
+   suffix               '_overscanSubtracted' Filename suffix
+   nbiascontam          0                    Number of columns to exclude from averaging
+      	Valid Range = [0,inf)