Merge pull request #267 from xylar/add-spack-to-docs

Add documentation for `mache.spack`

Author: xylar

.github/pull_request_template.md

@@ -4,14 +4,17 @@ Please add a description of what is accomplished in the PR here at the top:
 -->
 
 <!--
-Below are a few things we ask you or your reviewers to kindly check. 
+Below are a few things we ask you or your reviewers to kindly check.
 ***Remove checks that are not relevant by deleting the line(s) below.***
 -->
 Checklist
-* [ ] Developer's Guide has been updated
-* [ ] API documentation in the Developer's Guide (`api.md`) has any new or modified class, method and/or functions listed
-* [ ] Documentation has been [built locally](https://docs.e3sm.org/mache/main/developers_guide/building_docs.html) and changes look as expected
-* [ ] `Testing` comment in the PR documents testing used to verify the changes
+- [ ] User's Guide has been updated if needed
+- [ ] Developer's Guide has been updated if needed
+- [ ] API documentation lists any new or modified class, method, or function
+- [ ] Documentation [builds](https://docs.e3sm.org/mache/main/developers_guide/building_docs.html) cleanly and changes look as expected
+- [ ] Tests pass and new features are covered by tests
+- [ ] PR description includes a summary and any relevant issue references
+- [ ] `Testing` comment, if appropriate, in the PR documents testing used to verify the changes
 
 <!--
 Please note any issues this fixes using closing keywords: https://help.github.com/articles/closing-issues-using-keywords

docs/conf.py

@@ -64,9 +64,9 @@
 
 intersphinx_mapping = {
     'geometric_features':
-        ('https://mpas-dev.github.io/geometric_features/stable', None),
+        ('https://mpas-dev.github.io/geometric_features/main', None),
     'matplotlib': ('https://matplotlib.org/stable', None),
-    'mpas_tools': ('https://mpas-dev.github.io/MPAS-Tools/stable', None),
+    'mpas_tools': ('https://mpas-dev.github.io/MPAS-Tools/master', None),
     'numpy': ('https://numpy.org/doc/stable', None),
     'python': ('https://docs.python.org', None),
     'scipy': ('https://docs.scipy.org/doc/scipy/reference', None),

docs/developers_guide/api.md

@@ -31,7 +31,7 @@ documentation.
 ## spack
 
 ```{eval-rst}
-.. currentmodule:: mache.spack.templates
+.. currentmodule:: mache.spack
 
 .. autosummary::
     :toctree: generated/

docs/developers_guide/contributing.md

@@ -0,0 +1,74 @@
+# Contributing to mache
+
+Thank you for your interest in contributing to `mache`! We welcome
+contributions of all kinds, including bug reports, feature requests, code, and
+documentation improvements.
+
+## How to Contribute
+
+- **Bug Reports & Feature Requests:**
+  Please use [GitHub Issues](https://github.com/E3SM-Project/mache/issues) to
+  report bugs or request features.
+
+- **Pull Requests:**
+  Fork the repository, create a new branch for your changes, and submit a pull
+  request (PR) to the `main` branch. Please provide a clear description of
+  your changes.
+
+## Development Environment
+
+1. **Set up an isolated environment:**
+    ```bash
+    conda config --add channels conda-forge
+    conda config --set channel_priority strict
+    conda create -y -n mache_dev --file spec-file.txt
+    conda activate mache_dev
+    python -m pip install --no-deps --no-build-isolation -e .
+    ```
+
+2. **Install pre-commit hooks:**
+    ```bash
+    pre-commit install
+    ```
+    This ensures code style and quality checks run automatically on each
+    commit.
+
+## Code Style and Linting
+
+- Follow [PEP8](https://peps.python.org/pep-0008/) and project code style.
+- The following tools are used (via [pre-commit](https://pre-commit.com/)):
+  - [ruff](https://docs.astral.sh/ruff/) for linting and formatting
+  - [flynt](https://github.com/ikamensh/flynt) for f-string conversion
+  - [mypy](https://mypy-lang.org/) for type checking
+
+If a pre-commit hook fails, fix the reported issues and recommit.
+
+## Testing
+
+- Add or update tests for new features or bug fixes.
+- Run the test suite before submitting a PR:
+    ```bash
+    pytest
+    ```
+
+## Documentation
+
+- Document all public functions and classes using docstrings.
+- Update the [API documentation](api.md) if you add or modify public APIs.
+- Build and preview the documentation locally:
+    ```bash
+    cd docs
+    DOCS_VERSION=test make clean versioned-html
+    ```
+
+## Pull Request Checklist
+
+- [ ] User's Guide has been updated if needed
+- [ ] Developer's Guide has been updated if needed
+- [ ] API documentation lists any new or modified class, method, or function
+- [ ] Documentation builds cleanly and changes look as expected
+- [ ] Tests pass and new features are covered by tests
+- [ ] PR description includes a summary and any relevant issue references
+- [ ] `Testing` comment, if appropriate, in the PR documents testing used to verify the changes
+
+Thank you for helping improve `mache`!