Merge pull request #101 from xylar/expand-docs

A major expansion of the docs

Author: xylar

Diff for: LICENSE

@@ -1,11 +1,11 @@
 This software is open source software available under the BSD-3 license.
 
-Copyright (c) 2019 Triad National Security, LLC. All rights reserved.
-Copyright (c) 2019 Lawrence Livermore National Security, LLC. All rights reserved.
-Copyright (c) 2019 UT-Battelle, LLC. All rights reserved.
+Copyright (c) 2025 Triad National Security, LLC. All rights reserved.
+Copyright (c) 2025 Lawrence Livermore National Security, LLC. All rights reserved.
+Copyright (c) 2025 UT-Battelle, LLC. All rights reserved.
 
 
-Copyright (c) 2019 Triad National Security, LLC. This program was produced
+Copyright (c) 2025 Triad National Security, LLC. This program was produced
 under U.S. Government contract 89233218CNA000001 for Los Alamos National
 Laboratory (LANL), which is operated by Triad National Security, LLC for the
 U.S. Department of Energy/National Nuclear Security Administration. All rights
@@ -16,7 +16,7 @@ irrevocable worldwide license in this material to reproduce, prepare derivative
 works, distribute copies to the public, perform publicly and display publicly,
 and to permit others to do so.
 
-Copyright (c) 2019 Lawrence Livermore National Security, LLC. This work was
+Copyright (c) 2025 Lawrence Livermore National Security, LLC. This work was
 produced under the auspices of the U.S. Department of Energy by Lawrence
 Livermore National Laboratory under Contract DE-AC52-07NA27344. This work was
 prepared as an account of work sponsored by an agency of the United States

Diff for: README.md

@@ -1,5 +1,7 @@
 # pyremap
 
+![pyremap logo](docs/_static/logo.png)
+
 Python remapping tools for climate and earth system models.
 
 ## Documentation
@@ -24,44 +26,10 @@ python -m pip install --no-deps --no-build-isolation -e .
 
 ## Examples
 
-```
-cd examples
-```
-First, make mapping files for a lat-lon grid, and test it out by remapping
-temperature from the example file:
-```
-wget https://web.lcrc.anl.gov/public/e3sm/inputdata/ocn/mpas-o/oQU240/ocean.QU.240km.151209.nc
-./make_mpas_to_lat_lon_mapping.py
-```
-You should now see the mapping file:
-```
-map_oQU240_to_0.5x0.5degree.nc
-```
-as well as the input file (an initial condition for the MPAS-Ocean model) and
-an example of temperature from the initial condition remapped to the new grid.
-```
-ocean.QU.240km.151209.nc
-temp_0.5x0.5degree.nc
-```
+Detailed examples of how to use `pyremap` can be found in the [documentation](http://mpas-dev.github.io/pyremap/main/). These include:
 
-Second, let's try the same but to an Antarctic stereographic grid:
-```
-./make_mpas_to_antarctic_stereo_mapping.py
-```
-Now, there's a new mapping file and example output file:
-```
-map_oQU240_to_6000.0x6000.0km_10.0km_Antarctic_stereo.nc
-temp_6000.0x6000.0km_10.0km_Antarctic_stereo.nc
-```
+1. Creating mapping files for remapping to a lat-lon grid.
+2. Creating mapping files for remapping to an Antarctic stereographic grid.
+3. Remapping data between different stereographic grids.
 
-Finally, let's remap the temperature on the Antarctic grid to a lower
-resolution Antarctic grid:
-```
-./remap_stereographic.py -i temp_6000.0x6000.0km_10.0km_Antarctic_stereo.nc \
-    -o temp_6000.0x6000.0km_20.0km_Antarctic_stereo.nc -r 20
-```
-This created another mapping file and an output file:
-```
-map_6000x6000km_10km_Antarctic_stereo_to_6000x6000km_20.0km_Antarctic_stereo.nc
-temp_6000.0x6000.0km_20.0km_Antarctic_stereo.nc
-```
+For step-by-step walkthroughs, see the [examples section](http://mpas-dev.github.io/pyremap/main/examples/index.html).

Diff for: docs/.gitignore

@@ -1,3 +1,2 @@
 /generated
 /_build
-/quick_start.md

Diff for: docs/Makefile

@@ -33,6 +33,10 @@ clean:
 	rm -rf generated
 	@$(SPHINXBUILD) -M clean "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
+clean-versioned-html:
+	rm -rf $(BUILDDIR)/html/*
+	@echo "Cleaned versioned HTML builds."
+
 .PHONY: help Makefile
 
 # Catch-all target: route all unknown targets to Sphinx using the new

Diff for: docs/_static/logo.png

@@ -23,6 +23,6 @@
     </script>
 
     <!-- Load version switcher JS -->
-    <script src="../shared/version-switcher.js"></script>
+    <script src="{{ pathto("shared/version-switcher.js", True) }}"></script>
 
 {% endblock %}

Diff for: docs/_templates/layout.html

@@ -13,7 +13,6 @@
 from datetime import date
 
 from pyremap.version import __version__
-from pyremap.docs.parse_quick_start import build_quick_start
 
 # -- General configuration ------------------------------------------------
 
@@ -118,6 +117,9 @@
 #
 # html_theme_options = {}
 
+# Ensure the index is enabled
+html_use_index = True
+
 # -- Options for HTMLHelp output ------------------------------------------
 
 # Output file base name for HTML help builder.
@@ -180,8 +182,6 @@
     'numpy': ('http://docs.scipy.org/doc/numpy/', None),
     'xarray': ('http://xarray.pydata.org/en/stable/', None)}
 
-build_quick_start()
-
 github_doc_root = 'https://github.com/rtfd/recommonmark/tree/master/doc/'
 
 # Add any paths that contain custom static files (such as style sheets) here,
@@ -196,6 +196,6 @@
 }
 
 html_context = {
-    'current_version': version,
+    'current_version': version if 'DOCS_VERSION' in os.environ else 'main',
     # Other context variables
 }

Diff for: docs/conf.py

@@ -1,5 +1,7 @@
 # API reference
 
+:index:
+
 This page provides an auto-generated summary of the pyremap API.
 
 ## Mesh Descriptors

Diff for: docs/api.md renamed to docs/developer_guide/api.md

@@ -0,0 +1,87 @@
+# Contribution Workflow
+
+This document outlines the workflow for contributing to `pyremap`.
+
+## Step 1: Fork the Repository
+
+1. Navigate to the [pyremap repository](https://github.com/MPAS-Dev/pyremap).
+2. Click the "Fork" button in the top-right corner to create your own copy of the repository.
+
+## Step 2: Clone Your Fork
+
+1. Clone your forked repository to your local machine:
+   ```bash
+   git clone https://github.com/your-username/pyremap.git
+   ```
+2. Navigate to the project directory:
+   ```bash
+   cd pyremap
+   ```
+
+## Step 3: Create a Feature Branch
+
+1. Create a new branch for your changes:
+   ```bash
+   git checkout -b your-feature-name
+   ```
+
+## Step 4: Use a Worktree (Alternative to Step 3)
+
+1. Add a new worktree for your feature branch:
+   ```bash
+   git worktree add ../your-feature-name
+   ```
+2. Navigate to the new worktree directory:
+   ```bash
+   cd ../your-feature-name
+   ```
+
+   > **Note:** This allows you to work on multiple branches simultaneously in separate directories.
+
+## Step 5: Make Changes
+
+1. Implement your changes in the codebase.
+2. Write or update tests to cover your changes.
+3. Update documentation if necessary.
+
+## Step 6: Commit Your Changes
+
+1. Stage your changes:
+   ```bash
+   git add .
+   ```
+2. Commit your changes with a descriptive message:
+   ```bash
+   git commit -m "Add feature: your-feature-name"
+   ```
+
+   > **Note:** Please commit often and in small pieces.  You can
+   always `git rebase` later to consolidate pieces of your work into fewer
+   commits, but breaking commits into smaller pieces is very difficult.
+
+## Step 7: Push Your Changes
+
+1. Push your feature branch to your fork:
+   ```bash
+   git push origin your-feature-name
+   ```
+
+## Step 8: Submit a Pull Request
+
+1. Navigate to your fork on GitHub.
+2. Click the "Compare & pull request" button.
+3. Provide a detailed description of your changes.
+4. Submit the pull request.
+
+## Step 9: Address Feedback
+
+1. Review comments from maintainers on your pull request.
+2. Make necessary changes and push updates to your feature branch:
+   ```bash
+   git push origin your-feature-name
+   ```
+
+## Additional Resources
+
+- Refer to the [Contribution Guidelines](index.md#contribution-guidelines) for more details.
+- For help with Git, see the [Git documentation](https://git-scm.com/doc).

Diff for: docs/developer_guide/contribution_workflow.md

@@ -0,0 +1,36 @@
+# Developer Guide
+
+:index:
+
+Welcome to the Developer Guide for `pyremap`. This section provides resources and guidelines for contributors.
+
+## Coding Standards
+
+- Follow [PEP 8](https://peps.python.org/pep-0008/) for Python code style.
+- Use descriptive variable and function names.
+- Write clear and concise docstrings for all public functions and classes.
+- Ensure code is compatible with Python 3.8+.
+
+## Testing
+
+- Write unit tests for all new features and bug fixes.
+- Use the `pytest` framework for testing.
+- Place tests in the `pyremap/tests/` directory.
+- Run tests locally before submitting changes:
+  ```bash
+  pytest --pyargs pyremap
+  ```
+
+## Contribution Guidelines
+
+- Fork the repository and create a feature branch for your changes.
+- Write clear and concise commit messages.
+- Ensure all tests pass before submitting a pull request.
+- Include documentation updates for any new features or changes.
+- Submit a pull request with a detailed description of your changes.
+
+## Additional Resources
+
+- [API Reference](api.md)
+- [Testing Instructions](testing_instructions.md)
+- [Contribution Workflow](contribution_workflow.md)

Diff for: docs/developer_guide/index.md

@@ -0,0 +1,49 @@
+# Testing Instructions
+
+This document provides detailed instructions for testing `pyremap`.
+
+## Running Tests
+
+1. Ensure all dependencies are installed. You can use `conda` to install any missing dependencies:
+   ```bash
+   conda install --file dev-spec.txt
+   ```
+
+2. Install pyremap in edit mode:
+   ```bash
+   python -m pip install --no-deps --no-build-isolation -e .
+   ```
+
+3. Run the test suite using `pytest`:
+   ```bash
+   pytest --pyargs pyremap
+   ```
+
+4. To run a specific test file, provide the file path:
+   ```bash
+   pytest path/to/test_file.py
+   ```
+
+5. For more verbose output, use the `-v` flag:
+   ```bash
+   pytest -v --pyargs pyremap
+   ```
+
+## Writing Tests
+
+- Place all test files in the `pyremap/tests/` directory.
+- Use descriptive names for test functions and files.
+- Follow the `pytest` conventions for writing tests.
+
+## Debugging Failures
+
+- Use the `--pdb` flag to drop into the Python debugger on test failure:
+  ```bash
+  pytest --pdb --pyargs pyremap
+  ```
+
+- Review the stack trace provided by `pytest` to identify the source of the failure.
+
+## Additional Resources
+
+- Refer to the [pytest documentation](https://docs.pytest.org/en/latest/) for advanced usage and features.

Diff for: docs/developer_guide/testing_instructions.md

@@ -0,0 +1,11 @@
+# Examples
+
+Detailed walkthroughs of example scripts.
+
+```{toctree}
+:maxdepth: 2
+
+make_mpas_to_lat_lon_mapping
+make_mpas_to_antarctic_stereo_mapping
+make_mpas_vertex_to_antarctic_stereo_mapping
+```

Diff for: docs/examples/index.md

@@ -0,0 +1,52 @@
+# Make MPAS to Antarctic Stereo Mapping
+
+:index:
+
+This example demonstrates how to create a mapping file from an MPAS mesh to an Antarctic stereographic grid.
+
+## Script Overview
+
+The script uses `pyremap` to:
+- Read an MPAS mesh file.
+- Define a target Antarctic stereographic grid.
+- Generate a mapping file for regridding.
+
+## Example Code
+
+```python
+#!/usr/bin/env python
+
+"""
+Creates a mapping file to remap MPAS files to an Antarctic stereographic grid.
+"""
+
+from pyremap import Remapper, get_polar_descriptor
+
+# Input MPAS mesh file and name
+src_mesh_name = 'oQU240'
+src_mesh_filename = 'ocean.QU.240km.151209.nc'
+
+# Configure the remapper
+remapper = Remapper(ntasks=4, method='bilinear')
+remapper.src_from_mpas(filename=src_mesh_filename, mesh_name=src_mesh_name)
+
+# Define the target Antarctic stereographic grid descriptor
+remapper.dst_descriptor = get_polar_descriptor(
+    lx=6000.,  # Grid width in km
+    ly=5000.,  # Grid height in km
+    dx=10.,    # Grid cell size in x-direction (km)
+    dy=10.,    # Grid cell size in y-direction (km)
+    projection='antarctic'  # Antarctic stereographic projection
+)
+
+# Build the mapping file
+remapper.build_map()
+```
+
+## Expected Output
+
+The script generates a mapping file named:
+```
+map_oQU240_to_6000.0x5000.0km_10.0km_Antarctic_stereo_esmfbilin.nc
+```
+that can be used for regridding MPAS data to an Antarctic stereographic grid.