Template schema docs

.gitmodules

@@ -0,0 +1,3 @@
+[submodule "astrodb-template-db"]
+	path = astrodb-template-db
+	url = https://github.com/astrodbtoolkit/astrodb-template-db.git

docs/conf.py

@@ -56,6 +56,7 @@
     "sphinx.ext.mathjax",
     "nbsphinx",
     "pydata_sphinx_theme",
+    'sphinx_mdinclude',
 ]
 
 

docs/doc_requirements.txt

@@ -4,4 +4,5 @@ markupsafe==2.0.1
 nbsphinx
 pydata-sphinx-theme
 mock
-sphinx-pyproject
+sphinx-pyproject
+sphinx_mdinclude 

docs/index.rst

@@ -18,6 +18,7 @@ User Guide
    pages/querying_existing_db/index
    pages/ingesting/getting_started_ingesting
    pages/make_new_db/getting_started_new_database
+   pages/template_schema/template_schema
    pages/making_private_version
    pages/converting_spectra/converting_spectra
    pages/getting_help/index

docs/pages/dev_docs/developer_installation.rst

@@ -30,13 +30,19 @@ All contributions should include tests. To run the tests, use the command
 Linting and Formatting
 ---------------------
 
-Use `ruff <https://docs.astral.sh/ruff/>`_ for linting and `black <https://black.readthedocs.io/en/stable/>`_ for formatting.
-(At some point, we will add a pre-commit hook to enforce this.)
+Use `ruff <https://docs.astral.sh/ruff/>`_ for linting and formatting.    
+A pre-commit hook is provided for automatic linting and formatting with ruff. To use it, run `pip install pre-commit` and then `pre-commit install --allow-missing-config`.
 
 VSCode setup instructions: `Formatting Python in VSCode <https://code.visualstudio.com/docs/python/formatting>`_
 
 Build the Docs
 ---------------------
+The documentation is build using files in the `astrodb-template-db` submodule. 
+Be sure to update the submodule before building the docs.
+.. code-block:: bash
+
+    git submodule update --init --recursive
+
 
 To build the docs, use `sphinx-autobuild <https://pypi.org/project/sphinx-autobuild/>`_.
 

docs/pages/ingesting/ingesting_publications.rst

@@ -1,3 +1,5 @@
+.. _ingesting_publications:
+
 Ingesting publications
 =======================
 Ingesting a publication is a process of creating a new publication in the database.
@@ -28,7 +30,11 @@ Ingesting publications
 Fill this in...
 
 
-API documentation
------------------
-:py:mod:`astrodb_utils.find_publication`
-:py:mod:`astrodb_utils.ingest_publication`
+.. seealso::
+
+  :doc:`../template_schema/lookup_tables/publications`
+      Documentation on the Publications table
+
+  :py:mod:`find publication <astrodb_utils.publications.find_publication>` function
+
+  :py:mod:`ingest_publication <astrodb_utils.publications.ingest_publication>` function

docs/pages/template_schema/data_tables/associations.rst

@@ -0,0 +1,13 @@
+Association
+###########
+
+.. seealso::
+    :doc:`../lookup_tables/associationlist`
+        Documentation on the Association List table
+
+Table Documentation
+===================
+
+.. mdinclude:: ../../../../astrodb-template-db/docs/schema/Associations.md
+
+

docs/pages/template_schema/data_tables/companion_relationships.rst

@@ -0,0 +1,26 @@
+CompanionRelationships
+#######################
+
+
+Notes
+=====
+Relationship types are not currently constrained but should be one of the following:
+
+* *parent*: The source is higher mass/brighter than the companion
+* *sibling*: The source is similar to the companion in the system heirarchy 
+* *child*: The source is lower mass/fainter than the companion
+* *unresolved parent*: The source is the unresolved, combined light source of an unresolved multiple system which includes the companion
+
+.. seealso::
+    :doc:`../lookup_tables/companionlist`
+        Documentation on the Companion List table
+
+
+Table documentation
+===================
+.. _source: https://github.com/astrodbtoolkit/astrodb-template-db/blob/main/docs/schema/CompanionRelationships.md
+
+The below table is built directly from the schema and is
+included here from the `astrodb-template-db` documentation: `source`_.
+
+.. mdinclude:: ../../../../astrodb-template-db/docs/schema/CompanionRelationships.md

docs/pages/template_schema/data_tables/companionparameters.rst

@@ -0,0 +1,20 @@
+CompanionParameters
+###################
+
+.. seealso::
+
+    :doc:`../lookup_tables/paramaterlist`
+        Documentation for the ParamaterList table
+
+    :doc:`companion_relationships`
+        Documentation for the CompanionRelationships table
+
+
+Table Documentation
+====================
+.. _source: https://github.com/astrodbtoolkit/astrodb-template-db/blob/main/docs/schema/CompanionParameters.md
+
+The below table is built directly from the schema and is
+included here from the `astrodb-template-db` documentation: `source`_.
+
+.. mdinclude:: ../../../../astrodb-template-db/docs/schema/CompanionParameters.md

docs/pages/template_schema/data_tables/index.rst

@@ -0,0 +1,14 @@
+*************
+Data tables
+*************
+These tables are examples and can be removed as needed.
+Helper functions in the `astrodb_utils` package are 
+designed to help with adding data to these tables.
+Additional tables can be added using these as templates.
+
+.. toctree::
+   :glob:
+   :titlesonly:
+   :maxdepth: 1
+
+   *

docs/pages/template_schema/data_tables/modeledparameters.rst

@@ -0,0 +1,16 @@
+ModeledParameters
+#######################
+
+.. seealso::
+
+    :doc:`../lookup_tables/parameterlist`
+        Documentation for the ParameterList table
+
+Table Documentation
+===================
+.. _source: https://github.com/astrodbtoolkit/astrodb-template-db/blob/main/docs/schema/ModeledParameters.md
+
+The below table is built directly from the schema and is
+included here from the `astrodb-template-db` documentation: `source`_.
+
+.. mdinclude:: ../../../../astrodb-template-db/docs/schema/ModeledParameters.md

docs/pages/template_schema/data_tables/parallaxes.rst

@@ -0,0 +1,11 @@
+Parallaxes
+##########
+
+Table Documentation
+===================
+.. _source: https://github.com/astrodbtoolkit/astrodb-template-db/blob/main/docs/schema/Parallaxes.md
+
+The below table is built directly from the schema and is
+included here from the `astrodb-template-db` documentation: `source`_.
+
+.. mdinclude:: ../../../../astrodb-template-db/docs/schema/Parallaxes.md

docs/pages/template_schema/data_tables/photometry.rst

@@ -0,0 +1,29 @@
+Photometry
+##########
+
+
+Notes
+=====
+* Band names refer to entries in the :doc:`../lookup_tables/photometryfilters` table and are 
+  listed at the `SVO filter profile service <http://svo2.cab.inta-csic.es/svo/theory/fps3/index.php?mode=browse&gname=Spitzer&asttype=>`_
+
+.. seealso::
+
+    :doc:`../lookup_tables/photometryfilters`
+        Documentation for the PhotometryFilters table
+
+    :doc:`../lookup_tables/regimelist`
+        Documentation for the RegimeList table`
+
+    :doc:`../lookup_tables/telescopes`
+        Documentation for the Telescopes table
+
+
+Table documentation
+===================
+.. _source: https://github.com/astrodbtoolkit/astrodb-template-db/blob/main/docs/schema/Photometry.md
+
+The below table is built directly from the schema and is
+included here from the `astrodb-template-db` documentation: `source`_.
+
+.. mdinclude:: ../../../../astrodb-template-db/docs/schema/Photometry.md

docs/pages/template_schema/data_tables/propermotions.rst

@@ -0,0 +1,11 @@
+ProperMotions
+#############
+
+Table Documentation
+===================
+.. _source: https://github.com/astrodbtoolkit/astrodb-template-db/blob/main/docs/schema/ProperMotions.md
+
+The below table is built directly from the schema and is
+included here from the `astrodb-template-db` documentation: `source`_.
+
+.. mdinclude:: ../../../../astrodb-template-db/docs/schema/ProperMotions.md

docs/pages/template_schema/data_tables/radialvelocities.rst

@@ -0,0 +1,11 @@
+RadialVelocities
+################
+
+Table Documentation
+===================
+.. _source: https://github.com/astrodbtoolkit/astrodb-template-db/blob/main/docs/schema/RadialVelocities.md
+
+The below table is built directly from the schema and is
+included here from the `astrodb-template-db` documentation: `source`_.
+
+.. mdinclude:: ../../../../astrodb-template-db/docs/schema/RadialVelocities.md

docs/pages/template_schema/data_tables/rotationalparameters.rst

@@ -0,0 +1,12 @@
+RotationalParameters
+#######################
+
+
+Table Documentation
+===================
+.. _source: https://github.com/astrodbtoolkit/astrodb-template-db/blob/main/docs/schema/RotationalParameters.md
+
+The below table is built directly from the schema and is
+included here from the `astrodb-template-db` documentation: `source`_.
+
+.. mdinclude:: ../../../../astrodb-template-db/docs/schema/RotationalParameters.md

docs/pages/template_schema/data_tables/sourcetypes.rst

@@ -0,0 +1,17 @@
+SourceTypes
+###########
+
+.. seealso::
+
+    :doc:`../lookup_tables/sourcetypelist`
+        Documentation for the SourceTypeList table
+
+
+Table documentation
+===================
+.. _source: https://github.com/astrodbtoolkit/astrodb-template-db/blob/main/docs/schema/SourceTypes.md
+
+The below table is built directly from the schema and is
+included here from the `astrodb-template-db` documentation: `source`_.
+
+.. mdinclude:: ../../../../astrodb-template-db/docs/schema/SourceTypes.md

docs/pages/template_schema/data_tables/spectra.rst

@@ -0,0 +1,29 @@
+Spectra
+#######
+
+.. seealso::
+
+    :doc:`../lookup_tables/telescopes`
+        Documentation for the Telescopes table
+
+    :doc:`../lookup_tables/regimelist`
+        Documentation for the RegimeList table`
+
+
+Relevant functions: `spectra.ingest_spectrum`, `spectra.spectrum_plottable`, `spectra.find_spectra`
+
+If the spectrum provided has been modified from the author-provided one, 
+a link to the original spectrum can be provided in the `original_spectrum` column.
+
+The local_spectrum is meant to store the path to a local copy of the spectrum with an 
+environment variable to define part of the path (so it can be shared among other users). 
+For example: `$ASTRODB_SPECTRA/infrared/filename.fits`
+
+Notes
+=====
+* An accurate observation date is required for a spectrum to be ingested.
+
+* Data based on data from multiple observation dates has 'Multiple observation dates' 
+  indicated in the *comments* field. One of the dates should be used for the *observation_date*.
+
+* Spectra for companions should be associated with individual sources and not grouped with the primary source.

docs/pages/template_schema/lookup_tables/associationlist.rst

@@ -0,0 +1,17 @@
+AssociationList
+###############
+
+.. seealso::
+    :doc:`../data_tables/associations`
+        Documentation on the Association table
+
+
+Table Documentation
+===================
+.. _source: https://github.com/astrodbtoolkit/astrodb-template-db/blob/main/docs/schema/AssociationList.md
+
+The below table is built directly from the schema and is
+included here from the `astrodb-template-db` documentation: `source`_.
+
+.. mdinclude:: ../../../../astrodb-template-db/docs/schema/AssociationList.md
+

docs/pages/template_schema/lookup_tables/companionlist.rst

@@ -0,0 +1,16 @@
+CompanionList
+###############
+
+.. seealso::
+    :doc:`../data_tables/companion_relationships`
+        Documentation on the Companion Relationships table
+
+
+Table Documentation
+===================
+.. _source: https://github.com/astrodbtoolkit/astrodb-template-db/blob/main/docs/schema/CompanionList.md
+
+The below table is built directly from the schema and is
+included here from the `astrodb-template-db` documentation: `source`_.
+
+.. mdinclude:: ../../../../astrodb-template-db/docs/schema/CompanionList.md

docs/pages/template_schema/lookup_tables/index.rst

@@ -0,0 +1,11 @@
+*************
+Lookup tables
+************* 
+
+These tables are expected and used by other tables
+
+.. toctree::
+   :glob:
+   :maxdepth: 1
+
+   *

docs/pages/template_schema/lookup_tables/instruments.rst

@@ -0,0 +1,17 @@
+Instruments
+###########
+
+.. seealso::
+
+    :doc:`../lookup_tables/telescopes`
+        Documentation for the Telescopes table
+
+
+Table Documentation
+===================
+.. _source: https://github.com/astrodbtoolkit/astrodb-template-db/blob/main/docs/schema/Instruments.md
+
+The below table is built directly from the schema and is
+included here from the `astrodb-template-db` documentation: `source`_.
+
+.. mdinclude:: ../../../../astrodb-template-db/docs/schema/Instruments.md

docs/pages/template_schema/lookup_tables/parameterlist.rst

@@ -0,0 +1,19 @@
+ParameterList
+###############
+
+.. seealso::
+    :doc:`../data_tables/companionparameters`
+        Documentation for the CompanionParameters table
+
+    :doc:`../data_tables/modeledparameters`
+        Documentation for the ModeledParameters table
+
+
+Table Documentation
+===================
+.. _source: https://github.com/astrodbtoolkit/astrodb-template-db/blob/main/docs/schema/ParameterList.md
+
+The below table is built directly from the schema and is
+included here from the `astrodb-template-db` documentation: `source`_.
+
+.. mdinclude:: ../../../../astrodb-template-db/docs/schema/ParameterList.md