update API reference and contributor's guide (#341)

angelapak · web-flow · commit 181857a1abc0 · 2025-06-11T14:33:25.000-06:00
* include BibTeX citation in citing and remove bibliography

* add sphinx interlink extension and link to musica

* update API reference modules and contributing page content
diff --git a/docs/source/api/acom_music_box.rst b/docs/source/api/acom_music_box.rst
@@ -1,8 +1,10 @@
 MusicBox
 ========
 
-Submodules
-----------
+.. automodule:: acom_music_box
+   :members:
+   :undoc-members:
+   :show-inheritance:
 
 acom\_music\_box.music\_box module
 ----------------------------------
@@ -60,10 +62,3 @@ acom\_music\_box.utils module
    :undoc-members:
    :show-inheritance:
 
-Module contents
----------------
-
-.. automodule:: acom_music_box
-   :members:
-   :undoc-members:
-   :show-inheritance:
diff --git a/docs/source/api/index.rst b/docs/source/api/index.rst
@@ -1,8 +1,11 @@
-###
-API
-###
+###############
+API Reference
+###############
+
+This documentation describes the Python API for MusicBox.
+For detailed information on the chemistry-related objects and reaction definitions used in MusicBox via MUSICA, see the :mod:`musica.mechanism_configuration`
 
 .. toctree::
    :maxdepth: 4
 
-   acom_music_box
+   acom_music_box
diff --git a/docs/source/citing/index.rst b/docs/source/citing/index.rst
@@ -1,13 +1,12 @@
 
+##########################
 Citing MusicBox
-===============
+##########################
 
-MusicBox is a group scientific and software effort. 
+.. toctree::
+   :maxdepth: 1
 
-Cite the software
------------------
-
-The software can be cited like this
+MusicBox is a group scientific and software effort. The software can be cited like this:
 
 .. code-block:: console
 
@@ -28,6 +27,4 @@ The software can be cited like this
     publisher    = {Zenodo},
     version      = {v2.8.0},
     doi          = {10.5281/zenodo.15427735},
-    url          = {https://doi.org/10.5281/zenodo.15427735},
-
-}
+    url          = {https://doi.org/10.5281/zenodo.15427735}
diff --git a/docs/source/citing_and_bibliography/bibliography.rst b/docs/source/citing_and_bibliography/bibliography.rst
diff --git a/docs/source/citing_and_bibliography/index.rst b/docs/source/citing_and_bibliography/index.rst
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -27,6 +27,7 @@
     'sphinx.ext.autodoc',
     'sphinx_copybutton',
     'sphinx_design',
+    'sphinx.ext.intersphinx'
 ]
 
 templates_path = ['_templates']
@@ -36,6 +37,13 @@
 exclude_patterns = []
 
 highlight_language = 'python'
+
+#-- link to MUSICA documentation ---
+
+intersphinx_mapping = {
+    'musica': ('https://ncar.github.io/musica/api/', None),
+}
+
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
diff --git a/docs/source/contributing/index.rst b/docs/source/contributing/index.rst
@@ -6,11 +6,52 @@ The code for MusicBox is hosted on `GitHub <https://github.com/NCAR/music-box>`_
 features, documentation updates, etc.), please start by opening an `issue <https://github.com/NCAR/music-box/issues/new/choose>`_
 describing your request or planned contribution.
 
-Testing
--------
+Creating a development environment
+-----------------------------------
+To contribute to MusicBox and test changes locally, we recommend making a `conda <https://www.anaconda.com/docs/getting-started/miniconda/main>`_ environment:
+
+.. code-block:: console
+
+    $ git clone https://github.com/NCAR/music-box
+    $ cd music-box
+    $ conda create --name musicbox python=<minimum-3.9> --yes
+    $ conda activate musicbox
+
+After the GitHub repository is cloned and the virtual environment made, MusicBox should be built and installed with an ediable installation:
+
+.. code-block:: console
+
+    $ pip install -e .
+
+
+Testing with continuous integration
+------------------------------------
+MusicBox uses GitHub Actions to automatically test and validate changes whenever a pull request is opened. 
+A pull request will be considered for merging when it passes all tests in the test suite, indicated by a green checkmark.
+
+Before pushing your changes, you can run the same tests locally using:
+
+.. code-block:: console
+
+    $ pytest
 
 Style guide
 -----------
+MusicBox follows the `PEP 8 <https://peps.python.org/pep-0008/>`_ style guide for Python code. Please attempt to do the same on any new contributions.
+To maintain consistency, we use a GitHub action that autoformats for PEP 8 conventions after each PR is pulled. 
 
 Documentation
--------------
+-------------
+All of our docs are stored in the ``docs`` directory and is built using `Sphinx <https://www.sphinx-doc.org/en/master/>`_. 
+There are several Python dependencies that are necessary to build the documentation locally. These dependencies can be installed by 
+running the following from your cloned ``music-box`` directory:
+
+.. code-block:: console
+
+    $ cd docs
+    $ pip install -r requirements.txt
+
+To build the documentation locally after edits:
+
+- On macOS/Linux: ``make html``
+- On Windows (cmd or PowerShell): ``.\make.bat html``
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -39,7 +39,7 @@ Welcome to Music Box's documentation!
 
         The source code for music box is heavily documented. This reference will help you understand the internals of music box.
 
-    .. grid-item-card::  Contributors guide
+    .. grid-item-card::  Contributor's guide
         :img-top: _static/index_contribute.svg
         :link: contributing/index
         :link-type: doc
@@ -56,7 +56,7 @@ Welcome to Music Box's documentation!
    user_guide/index
    api/index
    contributing/index
-   citing_and_bibliography/index
+   citing/index
 
 Indices and tables
 ==================
