Merge pull request #295 from roman-corgi/update-docs

documentation

.github/pull_request_template.md

@@ -16,3 +16,4 @@ Please delete options that are not relevant (and this line).
 - [ ] I have linted my code
 - [ ] I have verified that all unit tests pass in a clean environment and added new unit tests, as needed
 - [ ] I have verified that all docstrings are properly formatted and added new documentation, as needed
+- [ ] I have filled out the Unit Test Definition Table on confluence, as needed

.gitignore

@@ -53,7 +53,7 @@ coverage.xml
 *.log
 
 # Sphinx documentation
-docs/_build/
+docs/source/_build/
 
 # PyBuilder
 target/

docs/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     = source
+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)

docs/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=source
+set BUILDDIR=build
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

docs/source/conf.py

@@ -0,0 +1,37 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+import os
+import sys
+sys.path.insert(0, os.path.abspath('..'))
+
+project = 'corgidrp'
+copyright = '2025, corgidrp Developers'
+author = 'corgidrp Developers'
+release = 'v1.1.2'
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.napoleon',
+    'sphinx.ext.viewcode'
+]
+
+templates_path = ['_templates']
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = 'sphinx_rtd_theme'
+pygments_style = 'sphinx'  
+html_static_path = ['_static']

docs/source/index.rst

@@ -0,0 +1,17 @@
+.. corgidrp documentation master file, created by
+   sphinx-quickstart on Thu Jan 30 17:31:17 2025.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+corgidrp: CoronaGraph Instrument Data Reduction Pipeline 
+========================================================
+
+This is the documentation for the CoronaGraph Instrument Data Reduction Pipeline for the Nancy Grace Roman Space Telescope.
+
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents
+
+   installation
+

docs/source/installation.rst

@@ -0,0 +1,43 @@
+Installation Guide
+==================
+
+Quick Installation
+------------------
+
+As the code is very much still in development, clone this repository, enter the top-level folder, and run the following command:
+
+.. code-block:: bash
+
+    pip install -e .
+
+Then you can import ``corgidrp`` like any other Python package!
+
+The installation will create a configuration folder in your home directory called ``.corgidrp``. 
+That configuration directory will be used to locate things on your computer such as the location of the calibration database and the pipeline configuration file. The configuration file stores settings such as whether to track each individual error term added to the noise.
+
+For Developers
+--------------
+Large binary files (used in tests) are stored in Git LFS. Install Git LFS if it isn't already installed. 
+
+`Install Git LFS <https://docs.github.com/en/repositories/working-with-files/managing-large-files/installing-git-large-file-storage>`_ if it isn't already installed. 
+
+You may need to run the following after checking out the repository to download the latest large binary files, or the unit tests may fail:
+
+.. code-block:: bash
+
+    git lfs pull
+
+To run the existing end-to-end tests, you also need the II&T code, which is used directly for comparing results. This also requires Git LFS to be installed first. Then install the II&T code by doing the following while in the top-level folder:
+
+.. code-block:: bash
+
+    pip install -r requirements_e2etests.txt corgidrp
+
+This will install the II&T repositories ``cal`` and ``proc_cgi_frame``.
+
+Troubleshooting
+---------------
+If you run into any issues with things in the ``.corgidrp`` directory not being found properly when you run the pipeline, such as a ``DetectorParams`` file, ``caldb``, or configuration settings, your ``corgidrp`` is configured into a weird state. Report the bug to our GitHub issue tracker, including both the error message and the state of your ``.corgidrp`` folder. 
+
+If you don't want to wait for us to troubleshoot the bug and deploy a fix, you can probably resolve the issue by completely deleting your ``.corgidrp`` folder and rerunning the code (the code will automatically remake it). This, however, means you will lose any changes you've made to your settings as well as your calibration database.
+