Skip to content

🧑‍💻 Development Guide

Set up Shellsmith for local development, testing, linting, and documentation.

Want to propose a fix, improve the CLI, or update the docs? This guide gets you started.

⚙️ Setup

Follow these steps to set up your development environment:

Clone the repository:

git clone https://github.com/ptrstn/shellsmith

Navigate into the project folder:

cd shellsmith

Create a virtual environment:

python -m venv .venv

Activate the virtual environment:

source .venv/bin/activate

.venv\Scripts\activate

Install the package in editable mode with test dependencies:

pip install -e .[test]

🚀 Running the App

You can run Shellsmith in two ways:

Using the aas CLI script

aas --help

Note

The aas command is installed when you install the project (e.g. via pip install -e .).
It's declared in pyproject.toml:

[project.scripts]
aas = "shellsmith.cli.app:main"

Running the module directly

python -m shellsmith --help

Note

This executes the package’s __main__.py entry point.

🧪 Running Tests

Start the BaSyx test environment (if needed):

docker compose up -d

Run the test suite with coverage:

pytest --cov

Generate an HTML coverage report:

pytest --cov --cov-report=html

Then open htmlcov/index.html in your browser.

🧼 Code Style

We use Ruff for linting, formatting, and import sorting.

Check code:

ruff check
What is being checked?

Ruff is configured to enforce modern Python code standards:

The following linting rules are enabled:

  • Type hints (ANN)
  • Common bugs (B)
  • Comprehension style (C4)
  • Docstring style (D)
  • PEP8 errors (E) and warnings (W)
  • Unused/undefined code (F)
  • Imports (I)
  • Naming conventions (N)
  • Pylint compatibility (PL)
  • Simplifications (SIM)
  • Modernization (UP)

Additional rules and ignores are set in pyproject.toml.

[tool.ruff]
target-version = "py310"

[tool.ruff.lint]
select = [
    "ANN",  # flake8-annotations
    "B",    # flake8-bugbear
    "C4",   # flake8-comprehensions
    "D",    # pydocstyle
    "E",    # pycodestyle errors
    "F",    # pyflakes
    "I",    # isort
    "N",    # pep8-naming
    "PL",   # pylint
    "SIM",  # flake8-simplify
    "UP",   # pyupgrade
    "W",    # pycodestyle warnings
]

[tool.ruff.lint.pydocstyle]
convention = "google"

Auto-fix issues:

ruff check --fix

Format code:

ruff format

📚 Docs

We use Material for MkDocs for documentation.

Serve the documentation locally:

mkdocs serve

Note

Documentation lives in the docs/ folder and uses Markdown with Material features like tabs, notes, and admonitions.

Then open http://localhost:8000

Build the static site:

mkdocs build