Development and documentation maintenance#

Work on the package#

Use the source installation to create an activated environment with gfortran, then run python -m pip install -e .. Fortran changes require a rebuild. Keep a clean output directory for each numerical configuration.

Run the focused TauP regression suite with:

python -m unittest discover -s tests -p test_pytaup_subprocess.py -v

The test suite checks Java subprocess queries, ObsPy fallback and installed-wheel JAR placement. It is not a numerical validation of every solver. The examples/ scripts provide small end-to-end calculations; the validation record describes what was actually run. Multi-node MPI requires a separate cluster test.

Build the documentation#

The documentation environment uses Python 3.12 independently of the package’s Python 3.9 support floor. Install only the locked documentation dependencies; Sphinx imports this checkout directly and does not run setup.py.

python3.12 -m venv .venv

Activate .venv using the command appropriate to your shell, then:

python -m pip install -r docs/requirements.txt
python docs/api/check_coverage.py
python -m sphinx -b html -W --keep-going docs docs/_build/html
python -m http.server 8000 --directory docs/_build/html

On Windows, create the environment with an available Python 3.12 interpreter (for example py -3.12 -m venv .venv), and activate it with .venv\Scripts\Activate.ps1. Open http://localhost:8000/ after starting the server.

HTML generation uses already checked-in example figures. It does not execute examples, start Java or compile the Fortran programs. Core modules are imported normally rather than replaced with mock objects.

docs/requirements.in describes the direct constraints. Refresh the lock deliberately using Python 3.12 resolution, review the changes, and rebuild before committing:

uv pip compile docs/requirements.in --python-version 3.12 --universal --no-header --output-file docs/requirements.txt

An optional external-link check is separate because publisher sites and other external servers can be temporarily unavailable:

python -m sphinx -b linkcheck docs docs/_build/linkcheck

Add or change an interface#

  1. Update the English NumPy-style docstring: purpose, parameter meanings and units, defaults, output shape/component order, side effects and errors.

  2. If it is a supported public interface, add it to the API inventory and the corresponding reference page. Internal helpers remain in the advanced reference.

  3. Explain changed scientific behavior in the relevant guide and update a small executable example when it illustrates that behavior.

  4. Rebuild with warnings treated as errors and run the relevant example/regression check. Update the English and Chinese quickstart together if its commands or output change.

  5. Record the user-visible change in the changelog.

Do not infer units from a variable name alone. Verify Python synthesis/rotation, the input template and the Fortran output definition together. In particular, unrotated tensors and wavelet durations differ between backends. Existing numerical defects are recorded in troubleshooting; documentation work must not silently change numerical behavior.

Example conventions#

Every backend script supports --output-dir and --reuse, includes a main guard and uses a model prepared from repository data. QSEIS2025 additionally accepts --observables all. The common helper validates arrays and writes machine-readable output and a run summary. Keep tutorial grids small. Generated solver libraries and logs are excluded from Git; the selected figures and validation report are reviewed artifacts.

GitHub Pages#

The documentation workflow builds on pull requests and uploads HTML for review. A successful build on main deploys to:

https://zhou-jiangcheng.github.io/pygrnwang/

Repository settings must select Settings → Pages → Build and deployment → Source: GitHub Actions. The deployment job uses the github-pages environment, pages: write and id-token: write. Fork pull requests build with read permissions and cannot deploy. See GitHub’s custom-workflow documentation.

The first site follows main and shows the package version. It does not archive historical versions. The package release workflow remains tag-triggered; publishing documentation does not create a PyPI release.

Package release checklist#

Before tagging, check the version in package metadata and pygrnwang.__version__, the changelog and dependency support matrix. Build source and wheel artifacts, inspect packaged executables/JARs, and test installation outside the checkout. The existing publishing workflow uses Trusted Publishing; the repository/workflow identity must match the PyPI configuration. Add release notes describing behavior and validation rather than assuming a successful import proves a solver works.