Update docs (#902)

winter-telescope · May 20, 2024 · 3f05933 · 3f05933
1 parent 7d7b08f
commit 3f05933
Show file tree

Hide file tree

Showing 135 changed files with 411 additions and 1,995 deletions.
diff --git a/.gitignore b/.gitignore
@@ -6,6 +6,12 @@ __pycache__/
 .idea/
 .vscode/
 
+# Ignore docs that are autogenerated
+
+docs/source/mirar*.rst
+docs/source/autogen/
+docs/source/extra/flowcharts/
+
 # Distribution / packaging
 bin/
 build/

diff --git a/.readthedocs.yml b/.readthedocs.yml
@@ -14,6 +14,13 @@ build:
       # https://python-poetry.org/docs/managing-dependencies/#dependency-groups
       - VIRTUAL_ENV=$READTHEDOCS_VIRTUALENV_PATH poetry install --with docs
 
+    pre_build:
+      # Generate latest various flowcharts
+      - VIRTUAL_ENV=$READTHEDOCS_VIRTUALENV_PATH python mirar/utils/docs/pipeline_visualisation.py
+      - VIRTUAL_ENV=$READTHEDOCS_VIRTUALENV_PATH python mirar/utils/docs/auto_config_docs.py
+      # Generate API documentation
+      - VIRTUAL_ENV=$READTHEDOCS_VIRTUALENV_PATH poetry run sphinx-apidoc -o ./docs/source/ ./mirar --module-first --force
+
 sphinx:
   builder: html
   fail_on_warning: false

diff --git a/README.md b/README.md
@@ -1,5 +1,5 @@
 
-![alt text](./docs/MIRAR_logo.png?raw=true)
+![alt text](docs/source/extra/MIRAR_logo.png?raw=true)
 
 # Modular Image Reduction and Analysis Resource (MIRAR)
 

diff --git a/docs/flowcharts/git/default.png b/docs/flowcharts/git/default.png
diff --git a/docs/flowcharts/git/lt.png b/docs/flowcharts/git/lt.png
diff --git a/docs/flowcharts/git/lt_sub.png b/docs/flowcharts/git/lt_sub.png
diff --git a/docs/flowcharts/sedmv2/all_phot.png b/docs/flowcharts/sedmv2/all_phot.png
diff --git a/docs/flowcharts/sedmv2/default.png b/docs/flowcharts/sedmv2/default.png
diff --git a/docs/flowcharts/sedmv2/default_stellar.png b/docs/flowcharts/sedmv2/default_stellar.png
diff --git a/docs/flowcharts/sedmv2/default_transient.png b/docs/flowcharts/sedmv2/default_transient.png
diff --git a/docs/flowcharts/sedmv2/realtime.png b/docs/flowcharts/sedmv2/realtime.png
diff --git a/docs/flowcharts/sedmv2/test_stellar.png b/docs/flowcharts/sedmv2/test_stellar.png
diff --git a/docs/flowcharts/sedmv2/test_transient.png b/docs/flowcharts/sedmv2/test_transient.png
diff --git a/docs/flowcharts/sedmv2/transient_PSF.png b/docs/flowcharts/sedmv2/transient_PSF.png
diff --git a/docs/flowcharts/sedmv2/transient_upload.png b/docs/flowcharts/sedmv2/transient_upload.png
diff --git a/docs/flowcharts/summer/_monitor.png b/docs/flowcharts/summer/_monitor.png
diff --git a/docs/flowcharts/summer/_monitor_2.png b/docs/flowcharts/summer/_monitor_2.png
diff --git a/docs/flowcharts/summer/crtest.png b/docs/flowcharts/summer/crtest.png
diff --git a/docs/flowcharts/summer/dbtest.png b/docs/flowcharts/summer/dbtest.png
diff --git a/docs/flowcharts/summer/default.png b/docs/flowcharts/summer/default.png
diff --git a/docs/flowcharts/summer/full.png b/docs/flowcharts/summer/full.png
diff --git a/docs/flowcharts/summer/imsub.png b/docs/flowcharts/summer/imsub.png
diff --git a/docs/flowcharts/summer/log.png b/docs/flowcharts/summer/log.png
diff --git a/docs/flowcharts/summer/postprocess.png b/docs/flowcharts/summer/postprocess.png
diff --git a/docs/flowcharts/summer/realtime.png b/docs/flowcharts/summer/realtime.png
diff --git a/docs/flowcharts/summer/simrealtime.png b/docs/flowcharts/summer/simrealtime.png
diff --git a/docs/flowcharts/summer/test.png b/docs/flowcharts/summer/test.png
diff --git a/docs/flowcharts/summer/test_imsub.png b/docs/flowcharts/summer/test_imsub.png
diff --git a/docs/flowcharts/summer/testlog.png b/docs/flowcharts/summer/testlog.png
diff --git a/docs/flowcharts/winter/astrometry.png b/docs/flowcharts/winter/astrometry.png
diff --git a/docs/flowcharts/winter/buildtest.png b/docs/flowcharts/winter/buildtest.png
diff --git a/docs/flowcharts/winter/candidates.png b/docs/flowcharts/winter/candidates.png
diff --git a/docs/flowcharts/winter/commissioning.png b/docs/flowcharts/winter/commissioning.png
diff --git a/docs/flowcharts/winter/commissioning_dark.png b/docs/flowcharts/winter/commissioning_dark.png
diff --git a/docs/flowcharts/winter/commissioning_flat.png b/docs/flowcharts/winter/commissioning_flat.png
diff --git a/docs/flowcharts/winter/commissioning_multiboard_stack.png b/docs/flowcharts/winter/commissioning_multiboard_stack.png
diff --git a/docs/flowcharts/winter/commissioning_noise.png b/docs/flowcharts/winter/commissioning_noise.png
diff --git a/docs/flowcharts/winter/commissioning_photcal.png b/docs/flowcharts/winter/commissioning_photcal.png
diff --git a/docs/flowcharts/winter/commissioning_photcal_indiv.png b/docs/flowcharts/winter/commissioning_photcal_indiv.png
diff --git a/docs/flowcharts/winter/commissioning_proc.png b/docs/flowcharts/winter/commissioning_proc.png
diff --git a/docs/flowcharts/winter/commissioning_reduce.png b/docs/flowcharts/winter/commissioning_reduce.png
diff --git a/docs/flowcharts/winter/commissioning_split.png b/docs/flowcharts/winter/commissioning_split.png
diff --git a/docs/flowcharts/winter/commissioning_split_single_board.png b/docs/flowcharts/winter/commissioning_split_single_board.png
diff --git a/docs/flowcharts/winter/commissioning_stack.png b/docs/flowcharts/winter/commissioning_stack.png
diff --git a/docs/flowcharts/winter/detect_candidates.png b/docs/flowcharts/winter/detect_candidates.png
diff --git a/docs/flowcharts/winter/detrend_unpacked.png b/docs/flowcharts/winter/detrend_unpacked.png
diff --git a/docs/flowcharts/winter/diff_forced_phot.png b/docs/flowcharts/winter/diff_forced_phot.png
diff --git a/docs/flowcharts/winter/final.png b/docs/flowcharts/winter/final.png
diff --git a/docs/flowcharts/winter/focus_cals.png b/docs/flowcharts/winter/focus_cals.png
diff --git a/docs/flowcharts/winter/full.png b/docs/flowcharts/winter/full.png
diff --git a/docs/flowcharts/winter/full_commissioning.png b/docs/flowcharts/winter/full_commissioning.png
diff --git a/docs/flowcharts/winter/full_commissioning_all_boards.png b/docs/flowcharts/winter/full_commissioning_all_boards.png
diff --git a/docs/flowcharts/winter/full_imsub.png b/docs/flowcharts/winter/full_imsub.png
diff --git a/docs/flowcharts/winter/full_subset.png b/docs/flowcharts/winter/full_subset.png
diff --git a/docs/flowcharts/winter/imsub.png b/docs/flowcharts/winter/imsub.png
diff --git a/docs/flowcharts/winter/log.png b/docs/flowcharts/winter/log.png
diff --git a/docs/flowcharts/winter/mosaic.png b/docs/flowcharts/winter/mosaic.png
diff --git a/docs/flowcharts/winter/only_ref.png b/docs/flowcharts/winter/only_ref.png
diff --git a/docs/flowcharts/winter/photcal_stacks.png b/docs/flowcharts/winter/photcal_stacks.png
diff --git a/docs/flowcharts/winter/process_candidates.png b/docs/flowcharts/winter/process_candidates.png
diff --git a/docs/flowcharts/winter/realtime.png b/docs/flowcharts/winter/realtime.png
diff --git a/docs/flowcharts/winter/reduce.png b/docs/flowcharts/winter/reduce.png
diff --git a/docs/flowcharts/winter/reduce_unpacked.png b/docs/flowcharts/winter/reduce_unpacked.png
diff --git a/docs/flowcharts/winter/refbuild.png b/docs/flowcharts/winter/refbuild.png
diff --git a/docs/flowcharts/winter/reftest.png b/docs/flowcharts/winter/reftest.png
diff --git a/docs/flowcharts/winter/send_skyportal.png b/docs/flowcharts/winter/send_skyportal.png
diff --git a/docs/flowcharts/winter/split_stacks.png b/docs/flowcharts/winter/split_stacks.png
diff --git a/docs/flowcharts/winter/stack_forced_phot.png b/docs/flowcharts/winter/stack_forced_phot.png
diff --git a/docs/flowcharts/winter/test.png b/docs/flowcharts/winter/test.png
diff --git a/docs/flowcharts/winter/test_imsub.png b/docs/flowcharts/winter/test_imsub.png
diff --git a/docs/flowcharts/winter/unpack_all.png b/docs/flowcharts/winter/unpack_all.png
diff --git a/docs/flowcharts/winter/unpack_subset.png b/docs/flowcharts/winter/unpack_subset.png
diff --git a/docs/flowcharts/wirc/default.png b/docs/flowcharts/wirc/default.png
diff --git a/docs/flowcharts/wirc/imsub.png b/docs/flowcharts/wirc/imsub.png
diff --git a/docs/flowcharts/wirc/test.png b/docs/flowcharts/wirc/test.png
diff --git a/docs/flowcharts/wirc/test_fp.png b/docs/flowcharts/wirc/test_fp.png
diff --git a/docs/flowcharts/wirc/test_imsub.png b/docs/flowcharts/wirc/test_imsub.png
diff --git a/docs/source/about.rst b/docs/source/about.rst
@@ -1,6 +1,8 @@
 About
 =====
 
+.. image:: ./MIRAR_logo.png
+
 What is mirar? Good question!
 
 Errors

diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -32,6 +32,8 @@
 
 templates_path = ["_templates"]
 
+html_extra_path = ["extra"]
+
 # -- Options for HTML output
 
 html_theme = "sphinx_rtd_theme"

diff --git a/docs/MIRAR_logo.png → docs/source/extra/MIRAR_logo.png b/docs/MIRAR_logo.png → docs/source/extra/MIRAR_logo.png
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -6,10 +6,12 @@ It was created by `Robert Stein <https://robertdstein.github.io/>`_ and
 `Viraj Karambelkar <https://github.com/virajkaram>`_ (see everyone who contributed at :doc:`contributors`).
 
 * How does mirar work? Check out :doc:`about`.
+* How is mirar designed? See :doc:`design`.
 * How can you install mirar? You can find instructions at :doc:`installation`.
 * How can you use mirar? Have a look at :doc:`usage`, where there is a guide with examples.
 * Want to use mirar for your own telescope? Great! Have a look at our :doc:`contributing-guide`. This also describes what to do if you find a bug or want to request a new feature.
 * What does x piece of mirar do? See the full documentation at :doc:`modules`.
+* Want to which configurations are available for a pipeline, and what they do? Check out :doc:`autogen/pipelines`.
 
 If you make use of mirar in your research, please cite the version using
 the DOI provided by Zenodo:
@@ -22,18 +24,24 @@ Contents
 --------
 
 .. toctree::
+    :maxdepth: 2
 
     about
     installation
+    design
     usage
     contributors
     contributing-guide
-    modules
 
-    mirar.data
+.. toctree::
+    :maxdepth: 3
+
+    autogen/pipelines
+    modules
 
 Indices and tables
 ==================
 
 * :ref:`genindex`
 * :ref:`modindex`
+* :ref:`search`
diff --git a/docs/source/mirar.catalog.kowalski.rst b/docs/source/mirar.catalog.kowalski.rst
diff --git a/docs/source/mirar.catalog.rst b/docs/source/mirar.catalog.rst
diff --git a/docs/source/mirar.catalog.vizier.rst b/docs/source/mirar.catalog.vizier.rst
diff --git a/docs/source/mirar.data.rst b/docs/source/mirar.data.rst
diff --git a/docs/source/mirar.data.utils.rst b/docs/source/mirar.data.utils.rst
diff --git a/docs/source/mirar.database.rst b/docs/source/mirar.database.rst