Merge pull request #124 from LSSTDESC/skycat_doc2

Skycat doc2

.github/workflows/documentation.yml

@@ -0,0 +1,29 @@
+name: Docs
+# on: [push, pull_request, workflow_dispatch]
+# Make changes to "on:" just to force new build
+on: [push]
+jobs:
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-python@v4
+        with:
+          python-version: "3.12"
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install .
+          pip install sphinx sphinx_rtd_theme sphinx_toolbox sphinxcontrib-autoprogram sphinxcontrib.datatemplates
+      - name: Sphinx build
+        run: |
+          sphinx-build docs _build
+      - name: Deploy
+        uses: peaceiris/actions-gh-pages@v3
+        if: ${{ github.event_name == 'workflow_dispatch' && github.ref == 'refs/heads/main' }}
+        # if: ${{ github.ref == 'refs/heads/skycat_doc2' }}
+        with:
+          publish_branch: gh-pages
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: _build/
+          force_orphan: true

README.md

@@ -1,11 +1,14 @@
 # The skyCatalogs package
 
-This package will contain 
+This package contains 
 * code to create sky catalogs from input like cosmoDC2 (for galaxies) and similar catalogs for other source types
-* implement an API to access information in the catalogs and products, such as flux calculations, derived from the catalogs
+* an API to access information in the catalogs and products, such as flux calculations, derived from the catalogs
 
 Sky Catalogs are chiefly intended for use by simulation programs. The physical representation is meant to compactly represent information needed to compute fluxes at a given time, under specified conditions (e.g. band).
 
+For more complete information on installation and use see
+[https://lsstdesc.org/skyCatalogs/](https://lsstdesc.org/skyCatalogs/)
+
 ## Set-up and testing
 From bash
 ```

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     = .
+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/conf.py

@@ -0,0 +1,90 @@
+# 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 --------------------------------------------------------------
+
+
+# Add top-level directory to path so python modules can be referred to
+# using the normal relative path
+import os
+import sys
+import importlib.util
+sys.path.insert(0, os.path.abspath('..'))
+
+
+# -- Project information -----------------------------------------------------
+
+project = 'skyCatalogs'
+copyright = '2020-2024, LSSTDESC'
+author = 'LSSTDESC'
+
+# The full version, including alpha/beta/rc tags
+# release = '1.7.0rc2'
+# Use load_skycatalogs_version() to determine release dynamically
+
+def load_skycatalogs_version():
+    """Extract version of skyCatalogs without importing the whole module"""
+
+    spec = importlib.util.spec_from_file_location(
+        "skycatalogs_version",
+        os.path.join(os.path.dirname(__file__), "..", "skycatalogs",
+                     "_version.py"),
+    )
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module
+
+
+# -- General configuration ---------------------------------------------------
+
+pygments_style = 'sphinx'
+# 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_rtd_theme",
+    "sphinx.ext.autodoc",
+    "sphinx.ext.napoleon"
+    ]
+    #     "sphinxcontrib.autoprogram"     # for CLI; probably don't need
+    # ]
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# 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']
+
+skycatalogs_version = load_skycatalogs_version()
+release = skycatalogs_version.__version__
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+# Normally want this theme, but may need to comment out if module not available
+html_theme = 'sphinx_rtd_theme'
+
+# 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']
+
+# The sphinx_rtd_theme does not properly handle wrapping long lines in
+# table cells when rendering to HTML due to a CSS issue (see
+# https://github.com/readthedocs/sphinx_rtd_theme/issues/1505).  Until
+# the issue is fixed upstream in sphinx_rtd_theme, we can simply
+# override the CSS here.
+rst_prolog = """
+.. raw:: html
+
+   <style>
+   .wy-table-responsive table td,.wy-table-responsive table th{white-space:normal}
+   </style>
+"""

docs/contact.rst

@@ -0,0 +1,12 @@
+Contact
+=======
+
+If you need to contact someone directly for assistance we are happy to help!
+
+- Admin, developer: **Joanne Bogart** (`@JoanneBogart <https://www.github.com/JoanneBogart>`__)
+- Developer: **Jim Chiang** (`@jchiang87 <https://www.github.com/jchiang87>`__)
+
+For any bugs, or suggestions for additional features within the DESC data
+management software, please raise an issue via the GitHub repository
+(`https://github.com/LSSTDESC/skyCatalogs/issues
+<https://github.com/LSSTDESC/skyCatalogs/issues>`__).

docs/index.rst

@@ -0,0 +1,55 @@
+.. skyCatalogs documentation master file, created by
+   sphinx-quickstart on Fri Apr 12 13:47:18 2024.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+=======================================================
+skyCatalogs: provides API for simulated object catalogs
+=======================================================
+skyCatalogs both creates simulated object catalogs (from precursor catalogs)
+and provides a uniform API to the catalogs it makes and to certain other
+catalogs. These catalogs may be used as inputs to image simulation (originally
+only for the Rubin Observatory; since also used in simulations for the
+Roman Observatory) and as truth catalogs.
+
+This documentation covers installation and usage instructions for the package.
+
+The source code of *skyCatalogs* is hosted at
+https://github.com/LSSTDESC/skyCatalogs.
+
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   installation
+   usage_read
+   usage_create
+   ops-rehearsals-3-4/galaxies
+   ops-rehearsals-3-4/UW_stars
+   ops-rehearsals-3-4/SSO
+   roman-rubin-1.1.2/diffsky_galaxy
+   roman-rubin-1.1.2/UW_stars
+   roman-rubin-1.1.2/snana
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Reference:
+   :hidden:
+
+   reference_python
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contact:
+   :hidden:
+
+   contact
+
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`