diff --git a/docs/index.rst b/docs/index.rst index 3fb3440..67ea332 100644 --- a/docs/index.rst +++ b/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 API documentation diff --git a/docs/pages/ingesting/getting_started_ingesting.rst b/docs/pages/ingesting/getting_started_ingesting.rst index f80be02..e19f1ce 100644 --- a/docs/pages/ingesting/getting_started_ingesting.rst +++ b/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 \ No newline at end of file diff --git a/docs/pages/ingesting/spectra/index.rst b/docs/pages/ingesting/spectra/index.rst index 664bec8..83def96 100644 --- a/docs/pages/ingesting/spectra/index.rst +++ b/docs/pages/ingesting/spectra/index.rst @@ -3,7 +3,10 @@ Spectra .. toctree:: :glob: - spectra/* + :maxdepth: 2 + :titlesonly: + + converting_spectra/* Check if spectra are plottable diff --git a/docs/pages/make_new_db/getting_started_new_database.rst b/docs/pages/make_new_db/getting_started_new_database.rst index 44d4c06..2abeb26 100644 --- a/docs/pages/make_new_db/getting_started_new_database.rst +++ b/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 `_ template repository. -2. :doc:`Modify the schema ` to suit your use case. -3. Ingest data using ``astrodb_utils`` functions. \ No newline at end of file +#. Make a new GitHub repository using the `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 ` 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. + + diff --git a/docs/pages/make_new_db/modifying_schema.rst b/docs/pages/make_new_db/modifying_schema.rst index 3e04dd6..2c1e203 100644 --- a/docs/pages/make_new_db/modifying_schema.rst +++ b/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 `_ 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 `_. 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 `_, 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. diff --git a/docs/pages/make_new_db/the_template_schema.rst b/docs/pages/make_new_db/the_template_schema.rst deleted file mode 100644 index a3da8ef..0000000 --- a/docs/pages/make_new_db/the_template_schema.rst +++ /dev/null @@ -1,2 +0,0 @@ -The template schema -===================== \ No newline at end of file diff --git a/docs/pages/template_schema/template_schema.rst b/docs/pages/template_schema/template_schema.rst index 65f5ec7..931f465 100644 --- a/docs/pages/template_schema/template_schema.rst +++ b/docs/pages/template_schema/template_schema.rst @@ -1,6 +1,6 @@ -################ -Template schema -################ +########################### +The AstroDB Template schema +########################### .. toctree:: :glob: