Expansion of docs for making a new database

docs/index.rst

@@ -20,7 +20,7 @@ User Guide
    pages/make_new_db/getting_started_new_database
    pages/template_schema/template_schema
    pages/making_private_version
-   pages/converting_spectra/converting_spectra
+   pages/ingesting/spectra/converting_spectra/converting_spectra
    pages/getting_help/index
    Developer documentation <pages/dev_docs/developer_installation>
    API documentation <pages/api>

docs/pages/ingesting/getting_started_ingesting.rst

@@ -1,19 +1,29 @@
 Ingesting and Modifying Data
-====================================
+============================
 
 .. toctree::
     :glob:
+    :maxdepth: 2
+    :titlesonly:
+
     ingesting_publications
+    spectra/*
     ingest_scripts
-    spectra
+
 
 
 .. note::
     If you want to add or modify the tables or columns (rather than just add/modify database contents), see :doc:`/pages/make_new_db/modifying_schema`.
 
 
-API documentation
+API Documentation
 -----------------
+
 :py:mod:`astrodb_utils.sources.ingest_source`
+    Function to ingest source data
+
 :py:mod:`astrodb_utils.sources.ingest_names`
+    Function to ingest alternative name data
+
 :py:mod:`astrodb_utils.utils.ingest_instrument`
+    Function to ingest instrument data

docs/pages/ingesting/spectra/index.rst

@@ -3,7 +3,10 @@ Spectra
 
 .. toctree::
     :glob:
-    spectra/*
+    :maxdepth: 2
+    :titlesonly:
+
+    converting_spectra/*
 
 
 Check if spectra are plottable

docs/pages/make_new_db/getting_started_new_database.rst

@@ -1,15 +1,35 @@
 Making a New Database
-======================================
+=====================
 
 .. toctree::
-    the_template_schema
-    modifying_schema
+    :titlesonly:
+    :maxdepth: 2
 
+    ../template_schema/template_schema
+    modifying_schema
 
 
 Overview
 --------
 
-1. Make a new Github repository using the `astrodb-template-db <https://github.com/astrodbtoolkit/astrodb-template-db>`_ template repository.
-2. :doc:`Modify the schema <modifying_schema>` to suit your use case.
-3. Ingest data using ``astrodb_utils`` functions.
+#. Make a new GitHub repository using the `astrodb-template-db <https://github.com/astrodbtoolkit/astrodb-template-db>`_ template repository.
+
+#. Update the ``README.md`` file with your database name and description.
+
+   * Please retain the credit line to the AstroDB Toolkit.
+
+#. Update the ``LICENSE`` file with your license of choice.
+
+#. :doc:`Modify the schema <modifying_schema>` in ``schema/schema.yaml`` to suit your use case.
+
+   * We highly recommend using an AI coding assistant (like GitHub Copilot) when modifying this file.
+
+#. Generate a new entity relationship diagram (ERD) and documentation pages for your schema.
+
+   * To make a new ERD, run ``scripts/build_schema_docs.py``. This generates a PNG file in the ``docs/figures/`` directory.
+
+   * To make new documentation pages, run ``scripts/build_schema_docs.py``. This generates a new set of Markdown files in the ``docs/schema/`` directory.
+
+#. Ingest data by modifying the JSON files by hand (in the ``data/`` directory) or by using ``astrodb_utils`` functions.
+
+

docs/pages/make_new_db/modifying_schema.rst

@@ -1,5 +1,5 @@
 Modifying the schema
-======================
+====================
 
 The template database comes with an existing schema, consisting of a set of tables and columns.
 It is expected that every usecase will modify this schema to suit their needs.
@@ -12,7 +12,7 @@ The `Felis Data Model documentation <Felis documentation>`_ provides a detailed
 
 
 Required tables
-----------------
+---------------
 There are several tables which are expected by ``astrodb_utils`` and should be modified with great care: 
 
 * Sources 
@@ -23,26 +23,26 @@ There are several tables which are expected by ``astrodb_utils`` and should be m
 * Instruments
 
 Optional tables
-----------------
+---------------
 Optional tables are things like Spectra, Photometry, Radial Velocities, etc. 
 These are included in the template database and can be used as models for other data tables and can be removed/modified if not needed.
 
 
 
 Philosophy and guidelines
----------------------
+-------------------------
 
 We encourage users to follow the detailed best practices for astronomical databases outlined in `Chen et al. 2022 <https://iopscience.iop.org/article/10.3847/1538-4365/ac6268>`_.
 
 
 Long vs Wide tables
-~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~
 Think carefully about the structure of your tables.
 TODO: Need an example
 
 
 Column names
-~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~
 * **Use lowercase column names.** This is a convention.
 * **Include units in the column name.** Since we do not have a way of storing Quantities in the database, 
   we recommend including the units in the column name. 
@@ -52,7 +52,7 @@ Column names
 
 
 Units
----------------------------
+-----
 Per `Chen et al. 2022 <https://iopscience.iop.org/article/10.3847/1538-4365/ac6268>`_, we explicitly define the units
 for each table in their name (e.g., in the `Sources` table, the column with Right Ascension values
 is named `ra_deg`). Doing so removes unit ambiguity when querying and modifying the database.

docs/pages/template_schema/template_schema.rst

@@ -1,6 +1,6 @@
-################
-Template schema
-################
+###########################
+The AstroDB Template schema
+###########################
 
 .. toctree::
    :glob: