Merge pull request #102 from xylar/fix-docs

Several fixes to the docs following recent expansion

Author: xylar

Diff for: docs/.gitignore

@@ -1,2 +1,3 @@
 /generated
 /_build
+/developer_guide/generated

Diff for: docs/_templates/layout.html

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

Diff for: docs/conf.py

@@ -34,7 +34,7 @@
     'sphinx.ext.napoleon'
 ]
 
-autosummary_generate = ['api.md']
+autosummary_generate = ['developer_guide/api.md']
 
 # Otherwise, the Return parameter list looks different from the Parameters list
 napoleon_use_rtype = False

Diff for: docs/developer_guide/api.md

@@ -1,6 +1,6 @@
 # API reference
-
-:index:
+```{index} single: API reference
+```
 
 This page provides an auto-generated summary of the pyremap API.
 

Diff for: docs/developer_guide/contribution_workflow.md

@@ -1,4 +1,6 @@
 # Contribution Workflow
+```{index} single: Contribution Workflow
+```
 
 This document outlines the workflow for contributing to `pyremap`.
 

Diff for: docs/developer_guide/generate_preview_docs.md

@@ -0,0 +1,39 @@
+# Generating and Previewing Documentation
+```{index} single: Documentation; Generating and Previewing
+```
+
+This guide explains how to build and preview the documentation for `pyremap`.
+
+## Prerequisites
+
+Ensure you have the following installed:
+- [Miniforge](https://github.com/conda-forge/miniforge) or [Micromamba](https://mamba.readthedocs.io/en/latest/user_guide/micromamba.html)
+- The required dependencies listed in `dev-spec.txt`:
+  ```bash
+  conda create -n pyremap_dev --file dev-spec.txt
+  conda activate pyremap_dev
+  python -m pip install --no-deps --no-build-isolation -e .
+  ```
+
+## Building the Documentation
+
+To build the documentation, run the following command:
+```bash
+cd docs
+DOC_VERSION=main make versioned-html
+```
+This will generate the static site in the `_build/html/main` directory.
+
+## Previewing the Documentation
+
+To preview the documentation locally, open the `index.html` file in the `_build/html/main` directory with your browser or try:
+```bash
+cd _build/html
+python -m http.server 8000
+```
+Then, open http://0.0.0.0:8000/main/ in your browser.
+
+## Notes
+
+- Make sure all documentation changes are committed before building or previewing.
+- Verify the formatting and content in the generated HTML files before submitting changes.

Diff for: docs/developer_guide/index.md

@@ -1,6 +1,6 @@
 # Developer Guide
-
-:index:
+```{index} single: Developer Guide
+```
 
 Welcome to the Developer Guide for `pyremap`. This section provides resources and guidelines for contributors.
 
@@ -31,6 +31,11 @@ Welcome to the Developer Guide for `pyremap`. This section provides resources an
 
 ## Additional Resources
 
-- [API Reference](api.md)
-- [Testing Instructions](testing_instructions.md)
-- [Contribution Workflow](contribution_workflow.md)
+```{toctree}
+:maxdepth: 2
+
+contribution_workflow
+testing_instructions
+generate_preview_docs
+api
+```

Diff for: docs/developer_guide/testing_instructions.md

@@ -1,4 +1,6 @@
 # Testing Instructions
+```{index} single: Testing Instructions
+```
 
 This document provides detailed instructions for testing `pyremap`.
 

Diff for: docs/examples/index.md

@@ -1,4 +1,6 @@
 # Examples
+```{index} single: Examples
+```
 
 Detailed walkthroughs of example scripts.
 

Diff for: docs/examples/make_mpas_to_antarctic_stereo_mapping.md

@@ -1,6 +1,6 @@
 # Make MPAS to Antarctic Stereo Mapping
-
-:index:
+```{index} single: Examples; MPAS to Antarctic Stereo
+```
 
 This example demonstrates how to create a mapping file from an MPAS mesh to an Antarctic stereographic grid.
 

Diff for: docs/examples/make_mpas_to_lat_lon_mapping.md

@@ -1,4 +1,6 @@
 # Make MPAS to Lat-Lon Mapping
+```{index} single: Examples; MPAS to Lat-Lon
+```
 
 This example demonstrates how to create a mapping file from an MPAS cell mesh
 to a regular latitude-longitude grid.

Diff for: docs/examples/make_mpas_vertex_to_antarctic_stereo_mapping.md

@@ -1,6 +1,6 @@
 # Make MPAS Vertex to Antarctic Stereo Mapping
-
-:index:
+```{index} single: Examples; MPAS Vertex to Antarctic Stereo
+```
 
 This example demonstrates how to create a mapping file from MPAS mesh vertices to an Antarctic stereographic grid.
 

Diff for: docs/index.md

@@ -1,12 +1,13 @@
-![pyremap logo](../_static/logo.png)
+![pyremap logo](_static/logo.png)
 =(pyremap)
 
 # pyremap
 
 Python remapping tools for climate and earth system models.
 
 ## Introduction
-:index:
+```{index} single: Introduction
+```
 
 `pyremap` is a Python library designed to facilitate the remapping
 (interpolation) of data between different spatial representations, such as
@@ -36,7 +37,8 @@ custom spatial datasets, `pyremap` provides the tools you need to perform
 accurate and efficient remapping.
 
 ## Documentation Overview
-:index:
+```{index} single: Documentation; Overview
+```
 
 This documentation is organized into the following sections:
 
@@ -59,6 +61,7 @@ developer_guide/index
 - **Developer Guide**: Resources for contributors, including API references, testing instructions, contribution guidelines, and coding standards.
 
 # Indices and tables
-:index:
+```{index} single: Indices and tables
+```
 
 * {ref}`genindex`

Diff for: docs/mesh_descriptors/index.md

@@ -1,6 +1,6 @@
 # Mesh Descriptors
-
-:index:
+```{index} single: Mesh Descriptors
+```
 
 Overview of mesh descriptors used in pyremap.
 

Diff for: docs/mesh_descriptors/lat_lon_2d_grid_descriptor.md

@@ -1,4 +1,6 @@
 # LatLon2DGridDescriptor
+```{index} single: Mesh Descriptors; LatLon2DGridDescriptor
+```
 
 A descriptor for 2D latitude-longitude grids.
 

Diff for: docs/mesh_descriptors/lat_lon_grid_descriptor.md

@@ -1,4 +1,6 @@
 # LatLonGridDescriptor
+```{index} single: Mesh Descriptors; LatLonGridDescriptor
+```
 
 A descriptor for latitude-longitude grids.
 

Diff for: docs/mesh_descriptors/mpas_cell_mesh_descriptor.md

@@ -1,4 +1,6 @@
 # MpasCellMeshDescriptor
+```{index} single: Mesh Descriptors; MpasCellMeshDescriptor
+```
 
 A descriptor for MPAS cell meshes.
 

Diff for: docs/mesh_descriptors/mpas_edge_mesh_descriptor.md

@@ -1,4 +1,6 @@
 # MpasEdgeMeshDescriptor
+```{index} single: Mesh Descriptors; MpasEdgeMeshDescriptor
+```
 
 A descriptor for MPAS edge meshes.
 

Diff for: docs/mesh_descriptors/mpas_vertex_mesh_descriptor.md

@@ -1,4 +1,6 @@
 # MpasVertexMeshDescriptor
+```{index} single: Mesh Descriptors; MpasVertexMeshDescriptor
+```
 
 A descriptor for MPAS vertex meshes.
 

Diff for: docs/mesh_descriptors/point_collection_descriptor.md

@@ -1,4 +1,6 @@
 # PointCollectionDescriptor
+```{index} single: Mesh Descriptors; PointCollectionDescriptor
+```
 
 A descriptor for a collection of points.
 

Diff for: docs/mesh_descriptors/projection_grid_descriptor.md

@@ -1,4 +1,6 @@
 # ProjectionGridDescriptor
+```{index} single: Mesh Descriptors; ProjectionGridDescriptor
+```
 
 A descriptor for grids based on map projections.
 

Diff for: docs/polar_projections/index.md

@@ -1,6 +1,6 @@
 # Polar Projections
-
-:index:
+```{index} single: Polar Projections
+```
 
 This is a set of functions used to support polar projections from `pyproj` and associated mesh descriptors.
 

Diff for: docs/quick_start.md

@@ -53,4 +53,4 @@ remapper.ncremap(
 
 ## Additional Resources
 
-For more detailed examples and advanced usage, refer to the [documentation]({ref}`pyremap`).
+For more detailed examples and advanced usage, refer to the [documentation](index.md#pyremap).

Diff for: docs/remapper/building_mapping.md

@@ -1,4 +1,6 @@
 # Building the Mapping
+```{index} single: Remapper; Building the Mapping
+```
 
 How to build the mapping file for remapping.
 

Diff for: docs/remapper/destination_grid_setup.md

@@ -1,4 +1,6 @@
 # Destination Grid Setup
+```{index} single: Remapper; Destination Grid Setup
+```
 
 How to set up the destination grid for remapping.
 

Diff for: docs/remapper/index.md

@@ -1,6 +1,6 @@
 # Remapper
-
-:index:
+```{index} single: Remapper
+```
 
 Overview of the remapping process in pyremap.
 

Diff for: docs/remapper/remapping_data.md

@@ -1,4 +1,6 @@
 # Remapping Data
+```{index} single: Remapper; Remapping Data
+```
 
 How to remap data using the generated mapping file.
 

Diff for: docs/remapper/smoothing.md

@@ -1,8 +1,10 @@
-### Smoothing with `expand_dist` and `expand_factor`
+# Smoothing with `expand_dist` and `expand_factor`
+```{index} single: Remapper; Smoothing
+```
 
 `pyremap` provides a unique capability for controlled smoothing when writing out the destination mesh descriptor. This is achieved through the use of two optional attributes: `expand_dist` and `expand_factor`. These attributes can be specified either as part of the destination descriptor or as attributes of the `remapper`, which will then pass them along to the destination descriptor.
 
-#### Attributes Overview
+## Attributes Overview
 
 - **`expand_dist`**:
   Specifies a distance in meters by which each grid cell is expanded. This can be provided as:
@@ -16,11 +18,11 @@
 
 > **Note**: The default values are `expand_dist = 0.0` and `expand_factor = 1.0`, which result in no smoothing.
 
-#### Usage and Behavior
+## Usage and Behavior
 
 These attributes are particularly useful for producing highly controlled smoothing as part of the remapping process. By expanding grid cells either by a fixed distance (`expand_dist`) or by a fraction of their size (`expand_factor`), users can fine-tune the smoothing effect to meet specific requirements.
 
-#### Important Notes
+## Important Notes
 
 1. **Combination with the `conserve` Method**:
    The `expand_dist` and `expand_factor` attributes must be used in combination with the `conserve` remapping method. This is because they leverage the area-weighted interpolation mechanism inherent to this method.

Diff for: docs/remapper/source_grid_setup.md

@@ -1,4 +1,6 @@
 # Source Grid Setup
+```{index} single: Remapper; Source Grid Setup
+```
 
 How to set up the source grid for remapping.