Improvements to developer documentation (#161)

* first draft

* add doc8 to docs requirements

* more docs

Author: kelle

docs/pages/dev_docs/developer_installation.rst

@@ -1,8 +1,24 @@
 Developer Documentation
-================================
+=======================
+
+.. toctree::
+    :hidden:
+    :titlesonly:
+
+    ingest_functions
+    documentation
+
+
+Setup
+-----
+
+If you'd like to contribute to `astrodb_utils`, first, first make a fork of the repository. 
+Then, clone your fork of the repository to your local machine. 
+Contributions will be accepted via pull requests from your fork to the primary repository.
+
 
 Installation
----------------------
+------------
 
 If you'd like to run tests, make sure to install the package with the optional test dependencies. E.g.,
 
@@ -11,13 +27,14 @@ If you'd like to run tests, make sure to install the package with the optional t
     pip install -e ".[test]"
 
 Make sure you get the `astrodb-template-db`` submodule. This is required for running tests and building the documentation.
+
 .. code-block:: bash
 
     git submodule update --init --recursive
 
 
 Running Tests
----------------------
+-------------
 
 All contributions should include tests. To run the tests, use the command
 
@@ -26,28 +43,11 @@ All contributions should include tests. To run the tests, use the command
     pytest
 
 Linting and Formatting
----------------------
+----------------------
 
 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 built 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/>`_.
-
-.. code-block:: bash
-
-    pip install -e ".[docs]"
-    sphinx-autobuild docs docs/_build/html
-
-The docs will then be available locally at <http://127.0.0.1:8000>.

docs/pages/dev_docs/documentation.rst

@@ -0,0 +1,20 @@
+Documentation
+=============
+
+Build the Docs
+--------------
+The documentation is built 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/>`_.
+
+.. code-block:: bash
+
+    pip install -e ".[docs]"
+    sphinx-autobuild docs docs/_build/html
+
+The docs will then be available locally at <http://127.0.0.1:8000>.

docs/pages/dev_docs/ingest_functions.rst

@@ -0,0 +1,18 @@
+Ingest functions
+================
+
+Ingest function design guidelines
+--------------------------------- 
+* ingest one thing. E.g., one parameter, or one spectrum.
+* use `raise_error = True/False`. 
+  * use :py:mod:`exit_function<astrodb_utils.utils.exit_function>` to help
+  * If `True`, raise an error if the ingest fails. 
+  * If `False`, return `None` and log warning if the ingest fails and log warning.
+
+- use helper functions to get constrained values from the database such as regime, instrument, etc.
+- * :py:mod:`astrodb_utils.utils.get_constrained_value`
+
+Need to decide
+--------------
+- ways to accept input. E.g, parameter= parameter, value=value, OR paramet dict = {parameter: value}. See https://github.com/astrodbtoolkit/astrodb_utils/issues/13
+  

pyproject.toml

@@ -47,6 +47,7 @@ docs = [
     "pydata-sphinx-theme",
     "pandoc",
     "sphinx_mdinclude",
+    "doc8"
     ]
 all = ["astrodb_utils[test, docs]"]