Contributing#

Contributing to ospgrillage#

Thank you for considering a contribution to ospgrillage! This document explains how to set up a development environment, run the test suite, build the documentation locally, and submit a pull request.

Table of contents#

  1. Development setup

  2. Running the tests

  3. Code style

  4. Docstrings

  5. Building the documentation

  6. Submitting a pull request

  7. Reporting bugs and requesting features

Development setup#

ospgrillage uses a src layout and declares all metadata in pyproject.toml.

# 1. Fork the repository on GitHub, then clone your fork:
git clone https://github.com/<your-username>/ospgrillage.git
cd ospgrillage

# 2. Create and activate a virtual environment (Python 3.9 or later):
python -m venv .venv
source .venv/bin/activate        # Windows: .venv\Scripts\activate

# 3. Install the package in editable mode together with all optional extras:
pip install -e ".[dev,docs]"

If [dev] or [docs] extras are not yet declared in pyproject.toml, install the dependencies manually:

pip install pytest pytest-cov sphinx pydata-sphinx-theme nbsphinx sphinx-autodoc-typehints

Running the tests#

The test suite uses pytest. Run it from the repository root:

python -m pytest tests/

To see a coverage report:

python -m pytest tests/ --cov=ospgrillage --cov-report=term-missing

All tests must pass before a pull request will be merged.

Code style#

ospgrillage uses black for formatting. Before committing, format changed files with:

black src/ tests/

A CI check will fail if the formatting does not match black’s output.

Docstrings#

All public functions and classes must have docstrings in NumPy style. A minimal example:

def create_grillage(bridge_name, long_dim, width, **kwargs):
    """Create and return an OspGrillage model object.

    Parameters
    ----------
    bridge_name : str
        Name label for the grillage model.
    long_dim : float
        Longitudinal span length in metres.
    width : float
        Transverse width in metres.
    **kwargs
        Additional keyword arguments forwarded to :class:`OspGrillage`.

    Returns
    -------
    OspGrillage
        Configured grillage model ready for meshing.

    Examples
    --------
    >>> import ospgrillage as og
    >>> bridge = og.create_grillage("My bridge", long_dim=20, width=8,
    ...                             num_long_grid=7, num_trans_grid=5,
    ...                             edge_beam_dist=1, mesh_type="Ortho")
    """

Building the documentation#

The documentation is built with Sphinx and requires pandoc to convert the Jupyter notebook examples.

Install pandoc via your OS package manager or from https://pandoc.org/installing.html, then:

cd docs
pip install -r requirements.txt   # installs Sphinx extensions
make html                          # output appears in docs/build/html/

Open docs/build/html/index.html in a browser to preview.

If you see nbconvert/pandoc errors, ensure pandoc is on your PATH:

pandoc --version

Submitting a pull request#

  1. Create a feature branch from main:

    git checkout -b feature/my-improvement

  2. Make your changes, add tests for any new behaviour, and ensure pytest passes.

  3. Update CHANGELOG.md under the [Unreleased] section.

  4. Push your branch and open a pull request against MonashSmartStructures/ospgrillage on GitHub.

  5. A maintainer will review the PR. Please be patient — this is a volunteer project.

Reporting bugs and requesting features#

Please open an issue on GitHub. When reporting a bug, include:

  • The ospgrillage version (python -c "import ospgrillage; print(ospgrillage.__version__)").

  • A minimal reproducible example.

  • The full traceback.