16  Developer Guide

16.1 Prerequisites

The environment for developing Majordome requires at least a reasonably mondern version of Python and Rust. Documentation depends on Quarto. The exact versions may change over time, but as of the last update, the following (minimum) versions are recommended:

  • Python 3.12
  • Rust 1.90
  • Quarto 1.8

The development focuses on portability and ease of setup, so by default any dependency relying on a C/C++ compiler is forbidden. This means that the development environment can be set up on any platform without needing to install additional compilers or tools.

16.2 Command reference

16.2.1 Windows PowerShell

Windows development is performed using the build.ps1 script, you find it in the project root. It is fully documented, but for convenience, here is a quick reference to the most common commands.

Building the package:

# Install the Python package in development mode:
./build.ps1 -FromPip

# Install the Python package with release optimizations and create wheel:
./build.ps1 -FromPip -PackageDist -FlagRelease

Testing the package:

# Check Rust code with backtraces enabled.
./build.ps1 -RustCheck -FlagBacktrace

# Run Python tests.
./build.ps1 -TestRust

# Run Python tests.
./build.ps1 -TestPython

Documentation builds:

# Only HTML documentation:
./build.ps1 -PackageDocs

# Also generate PDF documentation:
./build.ps1 -PackageDocs -DocsPdf

# Erase everything and do not use any cached files:
./build.ps1 -PackageDocs -FreshDocs

# XXX Must be used alone, as build might fail.
# Publish the documentation to GitHub Pages:
./build.ps1 -PublishDocs

16.2.2 Unix-like shell

For developing the package, consider doing so from within a virtual environment; that will makes things easier to check versions and pin them properly in package dependencies, as needed. Following the next snippet, install, activate, upgrade pip, install build tools, and install the package in editable mode with all optional dependencies:

# Create a virtual environment
python -m venv venv

# Activate the virtual environment (Windows PowerShell)
. venv/Scripts/Activate.ps1

# Activate the virtual environment (Unix-like)
. venv/bin/activate

# Upgrade pip
python -m pip install --upgrade pip

# Install build tools
python -m pip install --upgrade --force-reinstall build wheel
python -m pip install --upgrade --force-reinstall setuptools
python -m pip install --upgrade --force-reinstall setuptools_rust

# Install the package in editable mode with all optional dependencies
pip install -e .[full]

16.3 Documentation

Majordome code is documented using Numpydoc style docstrings, and the documentation is generated by module majordome_utilities.documents using Quarto markdown. This design choice reflects the academic aim of the packaged, with reporting and notebook support as a first-class citizen. Differently from usual packages, the .qmd files live along the modules they document, except for the main documentation file developers.qmd, which is located in the _docs folder. This allows to keep the documentation close to the code, and to easily update it when the code changes.

16.4 Distribution

Note for now the distribution of binaries is being done only through GitHub. Once a stable version is reached, consider updating this section for PyPI.

For distribution, maintainers need to do the following:

python -m pip install --upgrade twine
python -m pip install --upgrade build
python -m build
python -m twine upload --repository majordome dist/*

16.5 Dependency management

Generate the list of full dependencies using the following snipped; make sure to sanitize the outputs and update the corresponding section in pyproject.toml. There might be some duplicate dependencies that shall agree between themselves.

from textwrap import indent
import tomllib


def get_full_deps(data):
    deps = data["project"]["optional-dependencies"]
    deps = [f'"{p}"' for pkgs in deps.values() for p in pkgs]
    deps = indent(",\n".join(sorted(set(deps))), "    ")
    return f"full = [\n{deps}\n]"


def gen_full_deps(project="pyproject.toml", output="sandbox-deps.toml"):
    with open(project, "rb") as fr:
        with open(output, "w") as fp:
            fp.write(get_full_deps(tomllib.load(fr)))


gen_full_deps()

16.6 Todo lists

16.6.1 Quick needs

  • Automate documentation builds with GitHub actions.

  • Update and simplify containerized builds for Linux.

16.6.2 Wishlist

  • Implement diffusional Grashof number in majordome_engineering.transport.SutherlandFitting, which is related to mass transfer arising because of the buoyant force caused by the concentration inhomogeneities.

  • Create a data converter to create Ansys Fluent SCM files directly from Cantera YAML (species data and reactions).

  • Add generation of TUI commands for Fluent expression generator (and further expand to general Fluent setup).

  • Migrate gpxpy usage to plain XML for better maintainability.