Merge pull request #454 from mwcraig/document-catalogs

Rearrange documentation

.gitignore

@@ -25,6 +25,8 @@ pip-wheel-metadata
 # Sphinx
 docs/api
 docs/_build
+docs/auto_examples
+docs/sg_execution_times.rst
 
 # Eclipse editor project files
 .project

docs/_static/astropy.css

@@ -1,79 +1,19 @@
 /* Copied from astropy repo */
 /* Main page overview cards */
 
-.sd-card {
-  background: #fff;
-  border-radius: 0;
-  padding: 30px 10px 20px 10px;
-  margin: 10px 0px;
-}
-
-.sd-card .sd-card-header {
-  text-align: center;
-}
-
-.sd-card .sd-card-header .sd-card-text {
-  margin: 0px;
-}
-
 .sd-card .sd-card-img-top {
   height: 52px;
   width: 52px;
   margin-left: auto;
   margin-right: auto;
-}
-
-.sd-card .sd-card-header {
-  border: none;
-  background-color: white;
-  color: #150458 !important;
-  font-size: var(--pst-font-size-h5);
-  font-weight: bold;
-  padding: 2.5rem 0rem 0.5rem 0rem;
-}
-
-.sd-card .sd-card-footer {
-  border: none;
-  background-color: white;
-}
-
-.sd-card .sd-card-footer .sd-card-text {
-  max-width: 220px;
-  margin-left: auto;
-  margin-right: auto;
+  margin-top: 10px;
 }
 
 /* Dark theme tweaking */
 html[data-theme=dark] .sd-card img[src*='.svg'] {
     filter: invert(0.82) brightness(0.8) contrast(1.2);
 }
 
-/* Main index page overview cards */
-html[data-theme=dark] .sd-card {
-  background-color:var(--pst-color-background);
-}
-
-html[data-theme=dark] .sd-shadow-sm {
-    box-shadow: 0 .1rem 1rem rgba(250, 250, 250, .6) !important
-}
-
-html[data-theme=dark] .sd-card .sd-card-header {
-  background-color:var(--pst-color-background);
-  color: #150458 !important;
-}
-
-html[data-theme=dark] .sd-card .sd-card-footer {
-  background-color:var(--pst-color-background);
-}
-
-html[data-theme=dark] h1 {
-  color: var(--pst-color-primary);
-}
-
-html[data-theme=dark] h3 {
-  color: #0a6774;
-}
-
 /* Flip the colours on graphviz graphs on dark mode */
 html[data-theme="dark"] div.graphviz > object.inheritance {
   filter: invert(0.82) brightness(0.8) contrast(1.2);

docs/conf.py

@@ -69,7 +69,10 @@
 """
 
 # extensions += ["sphinxcontrib.autodoc_pydantic"]
-
+extensions += [
+    "sphinx_design",
+    "sphinx_gallery.gen_gallery",
+]
 # -- Project information ------------------------------------------------------
 
 # This does not *have* to match the package name, but typically does

docs/dev/index.rst

@@ -1,5 +1,5 @@
-Contributing to ``stellarphot``
--------------------------------
+Contributing
+------------
 
 Installation for one-time testing
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -109,3 +109,8 @@ Some specific examples
 
     settings
     moving_code
+
+.. toctree::
+    :hidden:
+
+    testing_installation

docs/dev/testing_installation.rst

@@ -0,0 +1,9 @@
+Trying out test releases
+########################
+
+Thanks for being willing to try out a test release! We strongly recommend that you do this in a virtual
+environment. If you don't have one set up, you can create one with `conda` or `mamba` (use whichever one you have installed)::
+
+    mamba create -n stellarphot-test python=3.11
+    mamba activate stellarphot-test
+    pip install --pre stellarphot

docs/index.rst

@@ -1,117 +1,99 @@
-Documentation
-=============
-
 Stellarphot is a package for performing photometry on calibrated (reduced) astronomical images. It
 provides a simple interface for performing aperture photometry of either a single
 image or a directory with multiple images. It is designed to be easy to use for both
 non-programmers and programmers.
 
-Installation
-============
-
-If you are testing a pre-release version of stellarphot we recommend setting up
-a virtual environment and installing stellarphot in this environment.
-
-Only use one of the methods below for making a virtual environment.
-
-Creating an environment with `conda` or `mamba` (use whichever one you have installed)::
-
-    mamba create -n stellarphot-test python=3.11
-    mamba activate stellarphot-test
-    pip install --pre stellarphot
-
-Creating an environment with `virtualenv`::
-
-    python -m venv stellarphot-test
-    source stellarphot-test/bin/activate
-    pip install --pre stellarphot
 
-To install stellarphot without creating an environment, use::
+.. grid:: 1 1 2 2
 
-    pip install --pre stellarphot
+    .. grid-item-card::
+        :padding: 2
+        :text-align: center
 
-You can remove stellarphot with::
+        **Testing stellarphot?**
+        ^^^
 
-    pip uninstall stellarphot
+        Are you testing a pre-relase version of stellarphot?
+        There are special installation instructions for you.
 
-Getting Started
-===============
+        .. button-ref:: dev/testing_installation
+            :expand:
+            :color: primary
+            :click-parent:
 
-Overview
---------
+            To the pre-release testing instructions
 
-You will go through this process to do photometry.
+    .. grid-item-card::
+        :padding: 2
+        :text-align: center
 
-#. You need to make some settings, like camera properties, observatory information, and passband maps. You may only need
-   to do this step once if you use the same equipment for all of your observations.
-#. Settings specific to an object need to be made:
+        **Getting Started?**
+        ^^^
 
-   #. night of data, like the photometry aperture radius, need to be made.
-   #. a list of the sources for which you want to perform photometry. These lists can be re-used.
+        Installation instructions and a walk though of the process of doing photometry.
 
-#. Review all of the settings that the photometry routines will use.
-#. Once those settings have been done, you can perform photometry on your images.
+        .. button-ref:: stellarphot/getting_started
+            :expand:
+            :color: primary
+            :click-parent:
 
+            To the Getting Started guide
 
-Graphical interface for making settings and doing photometry
-------------------------------------------------------------
 
-A graphical interface is provided via JupyterLab to make settings. To start JupyterLab, run the following command
-in a terminal::
+    .. grid-item-card::
+        :padding: 2
+        :text-align: center
 
-    jupyter lab
+        **User guide**
+        ^^^
 
-If you open up JupyterLab, the launcher should have a section that looks like this:
+        A guide to using stellarphot, including how to make settings and perform photometry.
 
-.. image:: /_static/launcher.png
-    :width: 400px
-    :alt: JupyterLab Launcher with stellarphot notebooks
+        .. button-ref:: stellarphot/user_guide/index
+            :expand:
+            :color: primary
+            :click-parent:
 
-Each of the notebooks corresponds to the steps in the previous section. Open each notebook in order, and run
-all of the cells in the notebook. In each will be a graphical interface to enter the camera and other settings
-(in notebook 1), measuring the seeing and choose comparison stars (in notebook 2), review all of your settings
-(in notebook 3), and perform photometry (in notebook 4).
+            To the user guide
 
-When the photometry is done there will be a new notebook called `photometry_run.ipynb` that will have a record
-of the photometry that was done.
+    .. grid-item-card::
+        :padding: 2
+        :text-align: center
 
-Editing a settings file directly
---------------------------------
+        **Reference**
+        ^^^
 
-The settings file is a JSON file that can be edited in any text editor.
+        Detailed descriptions of every class and function in stellarphot.
 
+        .. button-ref:: stellarphot/api_reference
+            :expand:
+            :color: primary
+            :click-parent:
 
-Performing photometry from within a Python script
--------------------------------------------------
+            To the API reference
 
-Once you have made your settings doing photometry is a two line process. First, you
-create a photometry object::
+    .. grid-item-card::
+        :padding: 2
+        :text-align: center
 
-    from stellarphot.photometry import AperturePhotometry
-    from stellarphot.settings import PhotometryWorkingDirSettings
-    photometry_settings = PhotometryWorkingDirSettings().load()
-    phot = AperturePhotometry(settings=photometry_settings)
+        **Contributing**
+        ^^^
 
-Then you can perform photometry on a single image::
+        Thanks for your interest in contributing to stellarphot. Click here to learn how to get started.
 
-    phot(image)
-
-If you have a directory of images you can perform photometry on all of them at once like this::
-
-    phot(directory, object_of_interest="M13")
+        .. button-ref:: dev/index
+            :expand:
+            :color: primary
+            :click-parent:
 
+            To the contributing guide
 
 .. toctree::
-  :maxdepth: 3
+  :maxdepth: 1
+  :hidden:
 
-  stellarphot/index.rst
+  stellarphot/getting_started.rst
+  stellarphot/user_guide/index.rst
   stellarphot/settings.rst
-
-
-Developer Documentation
-=======================
-
-.. toctree::
-   :maxdepth: 1
-
-   dev/index.rst
+  stellarphot/api_reference.rst
+  dev/index.rst

docs/stellarphot/api_reference.rst

@@ -0,0 +1,20 @@
+.. _api_reference:
+
+Reference/API
+#############
+
+All of the classes and functions defined in `stellarphot` are listed below, grouped by module.
+
+.. automodapi:: stellarphot
+.. automodapi:: stellarphot.core
+.. automodapi:: stellarphot.differential_photometry
+.. automodapi:: stellarphot.gui_tools
+.. automodapi:: stellarphot.io
+.. automodapi:: stellarphot.photometry.photometry
+.. automodapi:: stellarphot.photometry.source_detection
+.. automodapi:: stellarphot.plotting
+.. automodapi:: stellarphot.transit_fitting
+.. automodapi:: stellarphot.transit_fitting.gui
+.. automodapi:: stellarphot.transit_fitting.io
+.. automodapi:: stellarphot.transit_fitting.plotting
+.. automodapi:: stellarphot.utils