diff --git a/.github/workflows/markdown_link_check.yml b/.github/workflows/markdown_link_check.yml index 2b8f1c42..3c1b6b25 100644 --- a/.github/workflows/markdown_link_check.yml +++ b/.github/workflows/markdown_link_check.yml @@ -1,23 +1,23 @@ name: Check Markdown links on: - push: - branches: - - main - - master - - dev_master - pull_request: - branches: - - main - - master - - dev_master + # push: + # branches: + # - main + # - master + # - dev_master + # pull_request: + # branches: + # - main + # - master + # - dev_master # Allows you to run this workflow manually from the Actions tab. workflow_dispatch: # Run every day at 5:00 UTC - schedule: - - cron: "0 5 * * *" + # schedule: + # - cron: "0 5 * * *" jobs: markdown-link-check: diff --git a/METIS/docs/README.md b/METIS/docs/README.md new file mode 100644 index 00000000..b248958a --- /dev/null +++ b/METIS/docs/README.md @@ -0,0 +1,108 @@ +```{image} metis_scopesim_logo.png +:width: 600px +:alt: METIS + ScopeSim +:align: center +``` + +# METIS + ScopeSim + +## Introduction + +The METIS data simulator is based on the generic simulator ScopeSim, a +descendant of the older SimCado/SimMETIS interface. METIS itself is handled +as an instrument package containing configuration files for the various +instrument modes and data files describing the instrument components. + +The simulator currently supports imaging and long-slit spectroscopy modes. +The LM-band high-resolution IFU (LMS) mode is under development. + +```{note} +**Bug reports and help desk** + +If you come across a bug or get stuck with ScopeSim or the METIS package, +please [open an issue on GitHub](https://github.com/AstarVienna/irdb/issues) +or contact us by email (see below). + +**Your feedback is the only way we know** what needs to be +changed or improved with the package and the simulator. + +Please always include the output of `scopesim.bug_report()` from your +installation. +``` + +## Downloading the METIS instrument package + +Once ScopeSim is installed, download the METIS instrument package into your +working directory: + +```python +import scopesim +scopesim.download_packages(["Armazones", "ELT", "METIS"]) +``` + +This installs the packages into the subdirectory `./inst_pkgs/`. + +Your working directory should look like this afterwards: + +``` +my_simulations/ +├── .ipynb +└── inst_pkgs/ + ├── Armazones/ + ├── ELT/ + └── METIS/ + └── docs/ + └── example_notebooks/ + └── .ipynb ← copy to working dir before running +``` + +```{include} ../../docs/ScopeSim_guide.md +``` + +## Example notebooks + +Find the notebooks locally in `inst_pkgs/METIS/docs/example_notebooks/` +after downloading the package, or download them from the +[GitHub repository](https://github.com/AstarVienna/irdb/tree/dev_master/METIS/docs/example_notebooks). + +```{warning} +Run notebooks in your working directory, **not** inside `inst_pkgs/`. +Copy the desired notebook out first. +``` + +### Introductory notebooks + +```{toctree} +:maxdepth: 1 + +example_notebooks/Introduction_to_Scopesim_for_METIS +example_notebooks/METIS_IFU-01-Source_cube +example_notebooks/METIS_IFU-02-Simulation +example_notebooks/METIS_WCU +``` + +### Scientific use-case notebooks + +```{toctree} +:maxdepth: 1 + +example_notebooks/IMG_L_N-examples +example_notebooks/LSS-YSO_model_simulation +example_notebooks/LSS_AGN-01_preparation +example_notebooks/LSS_AGN-02_simulation +``` + +### Effect demonstration notebooks + +These notebooks are in `docs/example_notebooks/demos/`. + +```{toctree} +:maxdepth: 1 +:glob: + +example_notebooks/demos/* +``` + +### Instrument homepage + +[METIS at Leiden Observatory](https://metis.strw.leidenuniv.nl/) diff --git a/METIS/docs/readme.rst b/METIS/docs/readme.rst deleted file mode 100644 index e1cb7ad5..00000000 --- a/METIS/docs/readme.rst +++ /dev/null @@ -1,184 +0,0 @@ -.. |pic1| image:: metis_scopesim_logo.png - :width: 600px - :alt: METIS + ScopeSim - -|pic1| -====== - -Introduction ------------- -The METIS data simulator is based on the generic simulator software Scopesim, a descendant of the older SimCado/SimMETIS interface. METIS itself is handled as an instrument package that contains configuration files for the various instrument modes as well as data files describing the components of the instruments. -The new METIS data simulator currently supports the imaging and long-slit modes. The LM-band high-resolution IFU (LMS) mode will be offered soon. - - -Prerequisites -------------- - -- A working installation of a recent Python version -- A working installation of Jupyter if you want to run the simulator from notebooks. This is necessary to run the example notebooks contained in the instrument package. -- A working installation of the Python package installer pip - -.. note:: - - If you come across a bug or get stuck with a certain aspect of ScopeSim or - the METIS package, please get in touch with us (email addresses below). - - **Your feedback is the only way we know** what needs to be changed/improved - with the package and the simulator. - - Please always provide the output of the command ``scopesim.bug_report()`` run on your installation. - - -Installation & setup --------------------- - -This is a short overview of the installation and setup procedure; for a more detailed presentation see `Introduction_to_Scopesim_for_METIS `_. - -1. Install ``scopesim`` in your python environment:: - - $ pip install scopesim - - To upgrade an existing installation do:: - - $ pip install -U scopesim - -2. Create a working directory where you want to run simulations, e.g.:: - - $ mkdir ~/path/to/playing_with_scopesim/ - $ cd ~/path/to/playing_with_scopesim - -3. Install relevant irdb packages into this directory:: - - $ python - >> import scopesim - >> scopesim.download_packages(["METIS", "ELT", "Armazones"]) - - This will install the packages in the subdirectory ``./inst_pkgs``. - -4. The METIS package includes a number of tutorial notebooks in the directory ``./inst_pkgs/METIS/docs/example_notebooks/`` (see `Python notebooks`_). - - Copy notebooks to the working directory (i.e. ``./``) to run them.:: - - $ cp ./inst_pkgs/METIS/docs/example_notebooks/ . - -5. In a terminal, execute the notebook by calling:: - - $ jupyter notebook - -6. Follow instructions and explanations in the notebook. Some notebooks use example data; the commands to download these data from the scopesim server are included in the notebooks. - -You can then edit the notebooks and use them as a starting point for your own simulations. - - -Python notebooks ----------------- - -These notebooks can be found either: - -- [locally] in the METIS instrument package in ``docs/example_notebooks``, or -- [download] in the `METIS/docs section of the IRDB Github repository `_ - - -.. warning:: - Notebooks should be run in your working directory, **NOT** directly in the - ``docs/example_notebooks`` folder. Please copy the desired notebook out of - this folder. - -Ideally your folder structure should look like this:: - - working-dir - |- .iypnb - | - |- inst_pkgs - |- METIS - | |- docs - | |- example_notebooks - | |- .iypnb # copy out to working-dir - |- ELT - |- Armazones - - -Introductory notebooks -++++++++++++++++++++++ - -.. list-table:: - :widths: 25 75 - :width: 900px - :header-rows: 1 - - * - Name - - Description - * - | `Introduction_to_Scopesim_for_METIS.ipynb `_ - | `Introduction_to_Scopesim_for_METIS.pdf `_ - - Introductory overview of how to run simulations in Scopesim - -Scientific use-case notebooks -+++++++++++++++++++++++++++++ - -.. list-table:: - :widths: 25 75 - :width: 900px - :header-rows: 1 - - * - Name - - Description - * - `IMG_L_N-examples.ipynb `_ - - Imaging observations of HL Tau and an AGN model in the L and N band - * - `LSS-YSO_model_simulation.ipynb `_ - - Long-slit spectroscopy in the L-band of three models of a young stellar object - * - | `LSS_AGN-01_preparation.ipynb `_ - | `LSS_AGN-02_simulation.ipynb `_ - - | Long-slit spectroscopy in the N-band of an AGN model. The first notebook describes - | how the input data are prepared for Scopesim, the second runs the simulation. - -Notebooks on individual effects -+++++++++++++++++++++++++++++++ - -These notebooks can be found in ``docs/example_notebooks/demos``. - -.. list-table:: - :widths: 25 75 - :width: 900px - :header-rows: 1 - - * - Name - - Description - * - `demo_adc_wheel.ipynb `_ - - How to use the atmospheric dispersion correctors. - * - `demo_auto_exposure.ipynb `_ - - How to select `dit`/`ndit` automatically. - * - `demo_chopping_and_nodding.ipynb `_ - - How to produce chop-nod difference images in the N band. - * - `demo_detector_modes.ipynb `_ - - How to set detector readout modes. - * - `demo_filter_wheel.ipynb `_ - - How to use the filter wheel(s). - * - `demo_lss_simple.ipynb `_ - - Basic procedure for long-slit spectroscopy. - * - `demo_grating_efficiency.ipynb `_ - - Demonstration of spectral (grating) efficiency. - * - `demo_slit_wheel.ipynb `_ - - How to use the slit wheel for spectroscopy (and imaging) - * - `demo_rectify_traces.ipynb `_ - - How to obtain wavelength-calibrated and rectified 2D spectra. - -Documentation and useful references ------------------------------------ - -- `ScopeSim documentation `_ -- `Sky Object Templates documentation `_ -- `METIS homepage `_ -- For experts: GitHub repositories: - - + `simulator package ScopeSim `_ - + `instrument-specific packages irdb `_. - - -Contact points --------------- -`ScopeSim Slack `_ - -Email: - -- scopesim@univie.ac.at -- kieran.leschinski@univie.ac.at diff --git a/MICADO/docs/README.md b/MICADO/docs/README.md new file mode 100644 index 00000000..3a5df1f6 --- /dev/null +++ b/MICADO/docs/README.md @@ -0,0 +1,101 @@ +```{image} micado_scopesim_logo.png +:width: 600px +:alt: MICADO + ScopeSim +:align: center +``` + +# MICADO + ScopeSim + +## Introduction + +A MICADO data simulator is being developed as part of the generic simulator +ScopeSim, a descendant of the older SimCADO software. MICADO is the +near-infrared camera for the ELT and supports both MCAO (4 mas) and SCAO +(1.5 mas and 4 mas) imaging modes. + +```{note} +**Bug reports and help desk** + +If you come across a bug or get stuck with ScopeSim or the MICADO package, +please [open an issue on GitHub](https://github.com/AstarVienna/irdb/issues) +or contact us by email (see below). + +**Your feedback is the only way we know** what needs to be +changed or improved with the package and the simulator. + +Please always include the output of `scopesim.bug_report()` from your +installation. +``` + +## Downloading the MICADO instrument package + +Once ScopeSim is installed, download the MICADO instrument package into your +working directory: + +```python +import scopesim +scopesim.download_packages(["Armazones", "ELT", "MICADO"]) +``` + +This installs the packages into the subdirectory `./inst_pkgs/`. + +Your working directory should look like this afterwards: + +``` +my_simulations/ +├── .ipynb +└── inst_pkgs/ + ├── Armazones/ + ├── ELT/ + └── MICADO/ + └── docs/ + └── example_notebooks/ + └── .ipynb ← copy to working dir before running +``` + +```{include} ../../docs/ScopeSim_guide.md +``` + +## Example notebooks + +Download the notebooks from the +[GitHub repository](https://github.com/AstarVienna/irdb/tree/dev_master/MICADO/docs/example_notebooks) +or find them locally in `inst_pkgs/MICADO/docs/example_notebooks/` after +downloading the package. + +```{warning} +Run notebooks in your working directory, **not** inside `inst_pkgs/`. +Copy the desired notebook out first. +``` + +### Scientific use-case notebooks + +```{toctree} +:maxdepth: 1 + +example_notebooks/1_scopesim_MCAO_4mas_galaxy +example_notebooks/2_scopesim_SCAO_1.5mas_astrometry +example_notebooks/3_scopesim_SCAO_4mas_fv-psf +example_notebooks/MICADO_FAQs +``` + +| Notebook | Description | +|----------|-------------| +| `1_scopesim_MCAO_4mas_galaxy` | MCAO 4 mas imaging of a galaxy | +| `2_scopesim_SCAO_1.5mas_astrometry` | SCAO 1.5 mas astrometry use case | +| `3_scopesim_SCAO_4mas_fv-psf` | SCAO 4 mas field-varying PSF | +| `MICADO_FAQs` | Frequently asked questions | + +## Validation + +The table below shows limiting-magnitude test results (minimum S/N = 5). +Green = passed, yellow = expected deviation, red = unexpected failure. +**Click** a row to see the test plot. + +```{eval-rst} +.. validation-report:: ./MICADO/test_micado/validation_results.xml +``` + +The test code lives in the +[MICADO/test_micado/](https://github.com/AstarVienna/irdb/tree/dev_master/MICADO/test_micado/) +folder on GitHub. diff --git a/MICADO/docs/readme.rst b/MICADO/docs/readme.rst deleted file mode 100644 index 78ecd8c2..00000000 --- a/MICADO/docs/readme.rst +++ /dev/null @@ -1,115 +0,0 @@ -.. |pic1| image:: micado_scopesim_logo.png - :width: 600px - :alt: MICADO + ScopeSim - -|pic1| -====== - -Introduction ------------- -A new MICADO data simulator is being developed as part of the generic simulator ScopeSim, a descendant of the older SimCADO software. - - -Prerequisites -------------- - -- A working installation of Python 3.6 or newer -- A working installation of Jupyter notebooks if you want to run the simulator from notebooks, i.e. using a graphical interactive interface, rather than just the terminal or scripts (highly recommended) -- A working installation of the Python package installer pip - -.. note:: Bug reports and help-desk - - If you come across a bug or get stuck with a certain aspect of ScopeSim or - the MICADO package, please get in touch with us (emails addresses below). - - **Your feedback is the only way we know** what needs to be changed/improved - with the package and the simulator - - -Installation & setup --------------------- - -1. Install ``scopesim`` in your python environment:: - - $ pip install scopesim - -2. Create a directory where your simulation notebooks will live, e.g. ``~/path/to/playing_with_scopesim/`` -3. Install relevant irdb packages & download example notebooks into this directory:: - - $ python - >> import scopesim - >> scopesim.download_packages(["Armazones", "ELT", "MICADO"]) - -4. Download one of the tutorial notebooks (see `Python notebooks`_) -5. In a Terminal, cd to ~/ScopeSim and execute the notebook by calling:: - - $ cd ~/path/to/playing_with_scopesim/ - $ jupyter notebook filename.ipynb - -6. Follow instruction and explanations in the notebook. - - -Python notebooks ----------------- - -.. note:: - To download a notebook from Github, either: - - - view the raw file and save this disk from the browser, or - - navigate up one level, then right click the file and save as - - -**Download the example notebooks** `from the Github repo -`_ - - -.. toctree:: - :maxdepth: 1 - :caption: List of notebooks for MICADO - - example_notebooks/1_scopesim_MCAO_4mas_galaxy - example_notebooks/2_scopesim_SCAO_1.5mas_astrometry - example_notebooks/3_scopesim_SCAO_4mas_fv-psf - example_notebooks/MICADO_FAQs - - -Scientific use-case notebooks -+++++++++++++++++++++++++++++ - -.. list-table:: Science case notebooks - :widths: 25 75 - :header-rows: 1 - - * - Name - - Description - * - - - - -Validation ----------- -The following table shows an overview of the test results for limiting magnitudes assuming a minimal signal-to-noise ration of 5. -Green (passed) means a result within the given tolerances, yellow (xfailed) means an *expected* deviation, red (failed) means an *unexpected* issue. - -**Click** on each row for a plot of the test results. - -.. validation-report:: ./MICADO/test_micado/validation_results.xml - -The code used to generate these results can be found in this `GitHub folder `_. - -Documentation and useful references ------------------------------------ - -- `ScopeSim documentation `_ -- `Sky Object Templates documentation `_ -- `MICADO homepage `_ -- For experts: GitHub repositories: - - + `simulator package ScopeSim `_ - + `instrument-specific packages irdb `_. - - -Contact points --------------- - -- kieran.leschinski@univie.ac.at -- oliver.czoske@univie.ac.at diff --git a/MOSAIC/docs/README.md b/MOSAIC/docs/README.md new file mode 100644 index 00000000..201b5474 --- /dev/null +++ b/MOSAIC/docs/README.md @@ -0,0 +1,80 @@ +```{image} mosaic_scopesim_logo.png +:width: 600px +:alt: MOSAIC + ScopeSim +:align: center +``` + +# MOSAIC + ScopeSim + +## Introduction + +The MOSAIC ETC is built on the generic simulator ScopeSim. MOSAIC is handled +as an instrument package containing configuration files for the various +instrument modes and data files describing the instrument components. + +MOSAIC supports twelve observation modes across visual (VIS) and near-infrared +(NIR) multi-object spectroscopy and NIR integral-field unit (mIFU) operations. + +```{note} +**Bug reports and help desk** + +If you come across a bug or get stuck with ScopeSim or the MOSAIC package, +please [open an issue on GitHub](https://github.com/AstarVienna/irdb/issues) +or contact us by email (see below). + +**Your feedback is the only way we know** what needs to be +changed or improved with the package and the simulator. + +Please always include the output of `scopesim.bug_report()` from your +installation. +``` + +## Downloading the MOSAIC instrument package + +Once ScopeSim is installed, download the MOSAIC instrument package into your +working directory: + +```python +import scopesim +scopesim.download_packages(["Armazones", "ELT", "MOSAIC"]) +``` + +This installs the packages into the subdirectory `./inst_pkgs/`. + +Your working directory should look like this afterwards: + +``` +my_simulations/ +├── .ipynb +└── inst_pkgs/ + ├── Armazones/ + ├── ELT/ + └── MOSAIC/ + └── docs/ + └── example_notebooks/ + └── .ipynb ← copy to working dir before running +``` + +```{include} ../../docs/ScopeSim_guide.md +``` + +## Example notebooks + +Find the notebooks locally in `inst_pkgs/MOSAIC/docs/example_notebooks/` +after downloading the package, or download them from the +[GitHub repository](https://github.com/AstarVienna/irdb/tree/dev_master/MOSAIC/docs/example_notebooks). + +```{warning} +Run notebooks in your working directory, **not** inside `inst_pkgs/`. +Copy the desired notebook out first. +``` + +### Introductory notebooks + +| Notebook | Description | +|----------|-------------| +| [`MOSAIC_demo.ipynb`](example_notebooks/MOSAIC_demo.ipynb) | Introductory overview of how to run MOSAIC simulations in ScopeSim | + +### Instrument homepage + +[MOSAIC at mosaic-elt.eu](https://mosaic-elt.eu/index.php/instrument/) diff --git a/MOSAIC/docs/readme.rst b/MOSAIC/docs/readme.rst deleted file mode 100644 index e92b638f..00000000 --- a/MOSAIC/docs/readme.rst +++ /dev/null @@ -1,133 +0,0 @@ -.. |pic1| image:: mosaic_scopesim_logo.png - :width: 600px - :alt: MOSAIC + ScopeSim - -|pic1| -====== - -Introduction ------------- -The MOSAIC ETC is built on the generic simulator software Scopesim. -MOSAIC itself is handled as an instrument package that contains configuration files for the various instrument modes as well as data files describing the components of the instruments. - - -Prerequisites -------------- - -- A working installation of a recent Python version -- A working installation of Jupyter if you want to run the simulator from notebooks. This is necessary to run the example notebooks contained in the instrument package. -- A working installation of the Python package installer ``pip`` - -.. note:: - - If you come across a bug or get stuck with a certain aspect of ScopeSim or - the MOSAIC package, please get in touch with us (GitHub issue, or email addresses below). - - **Your feedback is the only way we know** what needs to be changed/improved - with the package and the simulator. - - Please always provide the output of the command ``scopesim.bug_report()`` run on your installation. - - -Installation & setup --------------------- - -This is a short overview of the installation and setup procedure; for a more detailed presentation see `Introduction_to_Scopesim_for_MOSAIC `_. - -1. Install ``scopesim`` in your python environment:: - - $ pip install scopesim - - To upgrade an existing installation do:: - - $ pip install -U scopesim - -2. Create a working directory where you want to run simulations, e.g.:: - - $ mkdir ~/path/to/playing_with_scopesim/ - $ cd ~/path/to/playing_with_scopesim - -3. Install relevant irdb packages into this directory:: - - $ python - >> import scopesim - >> scopesim.download_packages(["MOSAIC", "ELT", "Armazones"]) - - This will install the packages in the subdirectory ``./inst_pkgs``. - -4. The MOSAIC package includes a number of tutorial notebooks in the directory ``./inst_pkgs/MOSAIC/docs/example_notebooks/`` (see `Python notebooks`_). - - Copy notebooks to the working directory (i.e. ``./``) to run them.:: - - $ cp ./inst_pkgs/MOSAIC/docs/example_notebooks/ . - -5. In a terminal, execute the notebook by calling:: - - $ jupyter notebook - -6. Follow instructions and explanations in the notebook. Some notebooks use example data; the commands to download these data from the scopesim server are included in the notebooks. - -You can then edit the notebooks and use them as a starting point for your own simulations. - - -Python notebooks ----------------- - -These notebooks can be found either: - -- [locally] in the MOSAIC instrument package in ``docs/example_notebooks``, or -- [download] in the `MOSAIC/docs section of the IRDB Github repository `_ - - -.. warning:: - Notebooks should be run in your working directory, **NOT** directly in the - ``docs/example_notebooks`` folder. Please copy the desired notebook out of - this folder. - -Ideally your folder structure should look like this:: - - working-dir - |- .iypnb - | - |- inst_pkgs - |- MOSAIC - | |- docs - | |- example_notebooks - | |- .iypnb # copy out to working-dir - |- ELT - |- Armazones - - -Introductory notebooks -++++++++++++++++++++++ - -.. list-table:: - :widths: 25 75 - :width: 900px - :header-rows: 1 - - * - Name - - Description - * - | `MOSAIC_demo.ipynb `_ - - Introductory overview of how to run simulations in Scopesim - -Documentation and useful references ------------------------------------ - -- `ScopeSim documentation `_ -- `Sky Object Templates documentation `_ -- `MOSAIC homepage `_ -- For experts: GitHub repositories: - - + `simulator package ScopeSim `_ - + `instrument-specific packages irdb `_. - - -Contact points --------------- -`ScopeSim Slack `_ - -Email: - -- scopesim@univie.ac.at -- kieran.leschinski@univie.ac.at diff --git a/conf.py b/conf.py index 966b16d0..51292183 100644 --- a/conf.py +++ b/conf.py @@ -1,273 +1,91 @@ -""" -Configuration file for Sphinx and ReadTheDocs - -This file originally lived in docs/source. -It has been moved into the top level so that all package docs are accessible to -sphinx -""" - - -#!/usr/bin/env python3 # -*- coding: utf-8 -*- -# -# Instrument Reference Database documentation build configuration file, created by -# sphinx-quickstart on Fri Jul 12 13:46:11 2019. -# -# This file is execfile()d with the current directory set to its -# containing dir. -# -# Note that not all possible configuration values are present in this -# autogenerated file. -# -# All configuration values have a default; values that are commented out -# serve to show the default. - -# 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. -# -# sys.path.insert(0, os.path.abspath('.')) +"""Sphinx configuration for the Instrument Reference Database.""" -import sys import os +import sys from pathlib import Path -sys.path.insert(0, os.path.abspath('/')) -sys.path.insert(0, os.path.abspath('docs')) +sys.path.insert(0, os.path.abspath(".")) +sys.path.insert(0, os.path.abspath("docs")) -# -- General configuration ------------------------------------------------ +project = "Instrument Reference Database" +copyright = "2024, A* Vienna Software Team" +author = "A* Vienna Software Team" -# If your documentation needs a minimal Sphinx version, state it here. -# -# needs_sphinx = '1.0' - -# Add any Sphinx extension module names here, as strings. They can be -# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom -# ones. extensions = [ - 'nbsphinx', - 'sphinx.ext.intersphinx', - 'sphinx.ext.todo', - 'sphinx.ext.coverage', - 'sphinx.ext.mathjax', - 'sphinx.ext.viewcode', - # 'matplotlib.sphinxext.plot_directive', - # 'numpydoc', - # 'sphinx.ext.autodoc', - # 'jupyter_sphinx.execute', - # 'sphinxcontrib.apidoc', + "sphinx.ext.todo", + "sphinx.ext.intersphinx", + "sphinx.ext.mathjax", + "sphinx.ext.napoleon", + "sphinx_copybutton", + "myst_nb", + "sphinx_design", "docs.source._ext.validation_report", ] -# numpydoc settings -numpydoc_show_class_members = False +myst_enable_extensions = ["colon_fence"] +todo_include_todos = True + +napoleon_numpy_docstring = True +napoleon_use_admonition_for_references = True -# apidoc settings -# apidoc_module_dir = os.path.abspath('irdb/') -# apidoc_output_dir = 'docs/source/reference' -# apidoc_separate_modules = True -# apidoc_excluded_paths = ["tests/", "docs/"] +source_encoding = "utf-8" +source_suffix = { + ".rst": "restructuredtext", + ".myst": "myst-nb", + ".md": "myst-nb", + ".ipynb": "myst-nb", +} -# nbsphinx settings -nbsphinx_allow_errors = True -nbsphinx_execute = "never" +nb_execution_mode = "off" -# add_hidden_cell_to_ipynb_files() +master_doc = "index" -def add_hidden_cell_to_ipynb_files(): - import glob - old_string = '''"cells": [''' - new_string = '''"cells": [ - { - "cell_type": "code", - "execution_count": null, - "metadata": { "nbsphinx": "hidden" }, - "outputs": [], - "source": [ - "import os, scopesim as sim", - "if os.environ.get(\"READTHEDOCS\") == \"True\" or \"F:\" in os.getcwd():", - " sim.rc.__config__[\"!SIM.file.local_packages_path\"] = os.path.abspath(\"../../../\")", - ] - },''' - paths = glob.glob("./**/*.ipynb", recursive=True) - for path in paths: - with open(path, "r+") as f: - contents = f.read() - # check if the hidden cell has already been added to notebook - if 'os.environ.get("READTHEDOCS")' not in contents: - contents = contents.replace(old_string, new_string) - f.seek(0) - f.write(contents) +exclude_patterns = [ + "_build", + "docs/ScopeSim_guide.md", # shared include file, not a standalone page +] +intersphinx_mapping = { + "python": ("https://docs.python.org/3/", None), + "numpy": ("https://numpy.org/doc/stable/", None), + "scipy": ("https://docs.scipy.org/doc/scipy/", None), + "matplotlib": ("https://matplotlib.org/stable/", None), + "astropy": ("https://docs.astropy.org/en/stable/", None), + "synphot": ("https://synphot.readthedocs.io/en/latest/", None), + "scopesim": ("https://scopesim.readthedocs.io/en/latest/", None), + "scopesim_templates": ("https://scopesim-templates.readthedocs.io/en/latest/", None), + "pyckles": ("https://pyckles.readthedocs.io/en/latest/", None), + "anisocado": ("https://anisocado.readthedocs.io/en/latest/", None), +} -# add_hidden_cell_to_ipynb_files() +html_theme = "sphinx_book_theme" +html_theme_options = { + "repository_url": "https://github.com/AstarVienna/irdb", + "use_repository_button": True, + "use_download_button": True, + "home_page_in_toc": True, +} +html_logo = "docs/source/_static/logos/T_favicon.png" +html_favicon = "docs/source/_static/logos/T_favicon.png" +html_sidebars = { + "**": [ + "navbar-logo.html", + "search-field.html", + "sbt-sidebar-nav.html", + ] +} + +html_static_path = ["docs/source/_static"] +html_css_files = ["validation_report.css"] +html_js_files = ["clickable_rows.js"] def remove_inst_pkgs_symlink(): """Remove inst_pkgs symlinks.""" - for path in list(Path(".").rglob('inst_pkgs')): + for path in list(Path(".").rglob("inst_pkgs")): if path.is_symlink(): path.unlink() remove_inst_pkgs_symlink() - -# Matplotlib plot directive config parameters -plot_html_show_source_link = False - -# 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' - -# General information about the project. -project = 'Instrument Reference Database' -copyright = '2019, A*Vienna Software Team' -author = 'Kieran Leschinski, Oliver Czoske' - -# 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 = '0' -# The full version, including alpha/beta/rc tags. -release = '1' - -# The language for content autogenerated by Sphinx. Refer to documentation -# for a list of supported languages. -# -# This is also used if you do content translation via gettext catalogs. -# Usually you set "language" from the command line for these cases. -language = None - -# List of patterns, relative to source directory, that match files and -# directories to ignore when looking for source files. -# This patterns also effect to html_static_path and html_extra_path -exclude_patterns = [] - -# The name of the Pygments (syntax highlighting) style to use. -pygments_style = 'sphinx' - - -# -- 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' - -# Theme options are theme-specific and customize the look and feel of a theme -# further. For a list of options available for each theme, see the -# documentation. -# -html_theme_options = {"body_max_width": "900px"} - -# 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 = ['docs/source/_static'] # 'METIS/docs/example_notebooks' -html_favicon = 'docs/source/_static/logos/T_favicon.png' -html_css_files = [ - "validation_report.css", -] -html_js_files = [ - "clickable_rows.js", -] - -# Custom sidebar templates, must be a dictionary that maps document names -# to template names. -# -# This is required for the alabaster theme -# refs: http://alabaster.readthedocs.io/en/latest/installation.html#sidebars -# html_sidebars = { -# '**': [ -# 'relations.html', # needs 'show_related': True theme option to display -# 'searchbox.html', -# ] -# } - - -# -- Options for HTMLHelp output ------------------------------------------ - -# Output file base name for HTML help builder. -htmlhelp_basename = 'IRDB' - - -# -- 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, 'InstrumentReferenceDatabase.tex', 'Instrument Reference Database Documentation', - 'Kieran Leschinski, Oliver Czoske', 'manual'), -] - - -# -- Options for manual page output --------------------------------------- - -# One entry per manual page. List of tuples -# (source start file, name, description, authors, manual section). -man_pages = [ - (master_doc, 'InstrumentReferenceDatabase', 'Instrument Reference Database Documentation', - [author], 1) -] - - -# -- Options for Texinfo output ------------------------------------------- - -# Grouping the document tree into Texinfo files. List of tuples -# (source start file, target name, title, author, -# dir menu entry, description, category) -texinfo_documents = [ - (master_doc, 'InstrumentReferenceDatabase', 'Instrument Reference Database Documentation', - author, 'InstrumentReferenceDatabase', 'One line description of project.', - 'Miscellaneous'), -] - - - - -# Example configuration for intersphinx: refer to the Python standard library. -intersphinx_mapping = {'python': ('http://docs.python.org/', None), - 'numpy': ('http://docs.scipy.org/doc/numpy/', None), - 'scipy': ('http://docs.scipy.org/doc/scipy/reference/', None), - 'matplotlib': ('http://matplotlib.org/', None), - 'astropy': ('http://docs.astropy.org/en/stable/', None), - 'synphot': ('https://synphot.readthedocs.io/en/latest/', None), - 'scopesim_templates': ('https://scopesim_templates.readthedocs.io/en/latest/', None), - 'pyckles': ('https://pyckles.readthedocs.io/en/latest/', None), - 'anisocado': ('https://anisocado.readthedocs.io/en/latest/', None), - } - - -# -- Options for todo extension ---------------------------------------------- - -# If true, `todo` and `todoList` produce output, else they produce nothing. -todo_include_todos = True diff --git a/docs/ScopeSim_guide.md b/docs/ScopeSim_guide.md new file mode 100644 index 00000000..9eb81bc7 --- /dev/null +++ b/docs/ScopeSim_guide.md @@ -0,0 +1,55 @@ +## Prerequisites + +- A working installation of Python 3.8 or newer +- `pip` (the Python package installer) +- Jupyter, if you want to run the example notebooks (recommended) + +## Installing ScopeSim + +Install the latest release from PyPI: + +```bash +pip install scopesim +``` + +To upgrade an existing installation: + +```bash +pip install -U scopesim +``` + +## Setting up a working directory + +Create a dedicated directory where your simulation notebooks will live and +where the instrument packages will be downloaded: + +```bash +mkdir ~/path/to/my_simulations +cd ~/path/to/my_simulations +``` + +## Running the example notebooks + +The instrument package ships tutorial notebooks inside +`inst_pkgs//docs/example_notebooks/`. +Copy the desired notebook out of that folder before running it — notebooks +should **not** be run in-place, as their output would modify the package files. + +```bash +cp ./inst_pkgs//docs/example_notebooks/ . +jupyter notebook +``` + +## Documentation and useful references + +- [ScopeSim documentation](https://scopesim.readthedocs.io/en/latest/) +- [ScopeSim Templates documentation](https://scopesim-templates.readthedocs.io/en/latest/) +- GitHub repositories: + - [ScopeSim (simulator engine)](https://github.com/AstarVienna/scopesim) + - [IRDB (instrument packages)](https://github.com/AstarVienna/irdb) + +## Contact and support + +- [ScopeSim Slack](https://join.slack.com/t/scopesim/shared_invite/zt-143s42izo-LnyqoG7gH5j~aGn51Z~4IA) +- [GitHub Issues](https://github.com/AstarVienna/irdb/issues) +- Email: scopesim@univie.ac.at · kieran.leschinski@univie.ac.at diff --git a/index.md b/index.md new file mode 100644 index 00000000..92761aa9 --- /dev/null +++ b/index.md @@ -0,0 +1,77 @@ +--- +html_theme.sidebar_secondary.remove: true +--- + +```{image} docs/source/_static/logos/logo_irdb.PNG +:width: 600px +:alt: Instrument Reference Database +:align: center +``` + +# Instrument Reference Database + +The **Instrument Reference Database (IRDB)** contains the instrument-specific +configuration and data files used by the +[ScopeSim](https://scopesim.readthedocs.io/en/latest/) astronomical instrument +simulator. + +Each instrument package below ships with example notebooks, mode configuration +files, and the component data (filters, PSFs, detector layouts, etc.) needed to +run realistic end-to-end simulations. + +## Available Instruments + +::::{grid} 1 2 3 3 +:gutter: 3 + +:::{grid-item-card} MICADO +:img-top: MICADO/docs/micado_scopesim_logo.png +:link: MICADO/docs/README +:link-type: doc + +**Near-infrared camera for the ELT** + +Supports MCAO (4 mas) and SCAO (1.5 mas / 4 mas) imaging modes. +::: + +:::{grid-item-card} METIS +:img-top: METIS/docs/metis_scopesim_logo.png +:link: METIS/docs/README +:link-type: doc + +**Thermal-infrared imager and spectrograph for the ELT** + +Supports imaging and long-slit spectroscopy. LMS IFU mode in development. +::: + +:::{grid-item-card} MOSAIC +:img-top: MOSAIC/docs/mosaic_scopesim_logo.png +:link: MOSAIC/docs/README +:link-type: doc + +**Multi-object spectrograph for the ELT** + +12 observation modes across VIS/NIR MOS and NIR mIFU. +::: + +:::: + +## All Instrument Packages + +| Location | Telescope | Instrument | Documented | +|-----------|-----------|------------------------------|------------| +| Armazones | ELT | [MICADO](MICADO/docs/README) | ✓ | +| Armazones | ELT | [METIS](METIS/docs/README) | ✓ | +| Armazones | ELT | [MOSAIC](MOSAIC/docs/README) | ✓ | +| Paranal | VLT | HAWKI | | +| LFOA | - | - | | + +```{toctree} +:hidden: +:maxdepth: 2 +:caption: Instruments + +METIS + ScopeSim +MICADO + ScopeSim +MOSAIC + ScopeSim +``` diff --git a/index.rst b/index.rst deleted file mode 100644 index 0fcf2e17..00000000 --- a/index.rst +++ /dev/null @@ -1,43 +0,0 @@ -.. ReadTheDocs index file. Originally from docs/source/index.rst - Moved here so that all package docs are accessible to Sphinx and RTD - -.. image:: docs/source/_static/logos/logo_irdb.PNG - :width: 600 px - :alt: Welcome to the ScopeSim Documentation! - :align: center - - -The Instrument Reference Database (IRDB) contains the instrument specific -information used by the ScopeSim astronomical instrument data simulator. - -Instrument-Specific "Getting Started" Guides --------------------------------------------- - -.. toctree:: - :maxdepth: 2 - :caption: Contents: - - METIS + ScopeSim - MICADO + ScopeSim - MOSAIC + ScopeSim - - -Instrument Packages in the IRDB -------------------------------- - -+-----------+------------+------------+ -| Locations | Telescopes |Instruments | -+===========+============+============+ -| Armazones | ELT | MICADO | -| | +------------+ -| | | METIS | -| | +------------+ -| | | MOSAIC | -+-----------+------------+------------+ -| Paranal | VLT | HAWKI | -+-----------+------------+------------+ -| | | LFOA | -+-----------+------------+------------+ - - - diff --git a/requirements.readthedocs.txt b/requirements.readthedocs.txt index 4ef79e4a..6ff92dca 100644 --- a/requirements.readthedocs.txt +++ b/requirements.readthedocs.txt @@ -12,9 +12,9 @@ scopesim scopesim_templates paramiko -sphinx>=4.3.0 -sphinx-rtd-theme>=0.5.1 -jupyter_sphinx==0.2.3 -sphinxcontrib-apidoc -nbsphinx +sphinx>=5.0 +sphinx-book-theme +myst-nb +sphinx-design +sphinx-copybutton numpydoc