sphinx-needs-req-ui

Lokale NiceGUI-Anwendung zur Pflege von sphinx-needs/ubCode-Anforderungen. Das Git-Repository ist die Datenbasis; Anforderungen werden aus req/requirements.rst gelesen und wieder dorthin geschrieben.

Die interne Projektstruktur und der Python-Code sind englisch benannt. Die Benutzeroberfläche bleibt deutsch.

Standard-Repository

Die Default-Konfiguration verwendet das Playground-Repository:

git@github.com:procitec/sphinx-needs-req-ui-playground.git

Das Repository wird bei Bedarf per SSH geklont. Es gibt keinen eingebetteten Repository-Seed mehr; ubproject.toml, ubschema.json, pyproject.toml und req/requirements.rst liegen ausschließlich im konfigurierten Projekt-Repository.

Funktionen

• lokaler Browserbetrieb mit NiceGUI
• konfigurierbare Requirement-Tabelle über config/columns.yaml
• Single-Row-Auswahl ohne Auswahl-Checkboxen
• Preview nur bei ausgewählter Requirement-Zeile
• Split-Editor mit editierbarem RST-Inhalt und Live-Preview
• Need-Felder und fachliche Regeln werden soweit möglich aus ubproject.toml und ubschema.json abgeleitet
• lokale Sofortvalidierung aus der Projektkonfiguration
• autoritative Projektvalidierung über ubCode
• Git-Status und aktueller Branch direkt in der UI
• Commit-Workflow für req/requirements.rst
• Push-Workflow für lokale Commits
• Pull-Workflow bei sauberem Working Tree
• Git und ubc bleiben externe Systemvoraussetzungen
• One-File-Builds für Linux und Windows über GitHub Actions

Git-Workflow in der UI

Der normale Ablauf ist:

Requirement bearbeiten
        ↓
requirements.rst geändert
        ↓
Commit
        ↓
ubCode-Validierung
        ↓
git commit
        ↓
Push
        ↓
git push

Die Git-Leiste zeigt z. B.:

Git   Branch: main   Git: 1 geänderte Datei(en)
[Commit] [Push] [Pull] [Neu laden] [Validieren]

Nach einem erfolgreichen Commit erscheint z. B.:

Git: 1 Commit(s) nicht gepusht

Dann wird Push aktiv.

Commit

• Commit ist aktiv, wenn die konfigurierte req/requirements.rst Änderungen enthält.
• Vor dem Commit wird ubCode ausgeführt.
• Die App staged und committet ausschließlich die konfigurierte Requirements-Datei.
• Bereits vorhandene fremde staged Änderungen blockieren den App-Commit, damit nichts unbeabsichtigt mitcommittet wird.

Push

• Push ist aktiv, wenn der lokale Branch Commits vor seinem Upstream enthält.
• Push überträgt ausschließlich Commits. Nicht commitete Working-Tree-Änderungen werden nicht mit übertragen.
• Bei einem normalen Clone wird der vorhandene Upstream verwendet.

Pull

• Pull verwendet git pull --ff-only.
• Pull ist nur bei sauberem Working Tree möglich. Lokale, noch nicht commitete Änderungen müssen zuerst committed oder anderweitig behandelt werden.

ubCode-Validierung

Die Default-Konfiguration enthält:

[validation]
command = ["ubc", "check", "."]
output_format = "json"

Da FILES... bei ubc check variadisch ist, erzeugt die Anwendung für die JSON-Ausgabe den Aufruf:

ubc check --output-format json .

Falls eine ältere ubCode-Version diese Option tatsächlich nicht unterstützt, fällt die Anwendung auf die normale Textausgabe zurück.

Voraussetzungen

Entwicklungsbetrieb

• Python 3.11+
• Git im PATH
• ubc im PATH
• funktionierender SSH-Zugriff auf GitHub
• empfohlen: uv

Gepackte Anwendung

Python und die Python-Abhängigkeiten werden in das Binary gepackt. Extern vorausgesetzt bleiben bewusst:

• Git im PATH
• ubc im PATH
• funktionierende SSH-Konfiguration für das konfigurierte Repository

Start im Entwicklungsmodus

uv sync --extra dev
uv run sphinx-needs-req-ui

Standardmäßig öffnet sich:

http://127.0.0.1:8080

Wird das letzte Browser-Tab bzw. Browserfenster der Anwendung geschlossen, beendet sich der lokale Python-Prozess nach einer kurzen Reconnect-Frist automatisch. Ein normales schnelles Neuladen der Seite beendet die Anwendung nicht.

Alternative Konfiguration:

uv run sphinx-needs-req-ui --config /pfad/zu/app.toml

Standardkonfiguration

[git]
server = "github.com"
username = "git"
repository = "procitec/sphinx-needs-req-ui-playground.git"
workspace = "@user_data/repositories/sphinx-needs-req-ui-playground"
pull_on_start = false

[project]
requirements_file = "req/requirements.rst"
ubproject_file = "ubproject.toml"
schema_file = "ubschema.json"

[ui]
columns_file = "config/columns.yaml"
host = "127.0.0.1"
port = 8080
open_browser = true
preview_debounce_ms = 350

[validation]
command = ["ubc", "check", "."]
output_format = "json"

pull_on_start bleibt standardmäßig deaktiviert, damit die Anwendung nicht ungefragt einen Netzwerkzugriff bzw. Pull durchführt.

Persistenter Workspace

Bei der gepackten Anwendung liegt das geklonte Repository standardmäßig im Benutzerprofil, z. B. unter Windows:

%LOCALAPPDATA%\sphinx-needs-req-ui\repositories\sphinx-needs-req-ui-playground

Build

Linux

./scripts/build-linux.sh

Ergebnis:

dist/sphinx-needs-req-ui

Windows

./scripts/build-windows.ps1

Ergebnis:

dist/sphinx-needs-req-ui.exe

Git und ubCode werden in beiden Fällen nicht eingebettet.

GitHub Release

Die Release-Version wird ausschließlich in pyproject.toml gepflegt. Ein dazu passender Tag startet den Release-Workflow:

VERSION="$(python3 -c 'import tomllib; print(tomllib.load(open("pyproject.toml", "rb"))["project"]["version"])')"
git tag "v${VERSION}"
git push origin "v${VERSION}"

GitHub Actions baut das Linux- und Windows-Binary auf nativen Runnern und veröffentlicht beide zusammen mit SHA-256-Prüfsummen im GitHub Release.

Projektstruktur

sphinx-needs-req-ui/
├── .github/workflows/
│   ├── ci.yml
│   └── release.yml
├── config/
│   ├── app.toml
│   └── columns.yaml
├── packaging/
│   └── entrypoint.py
├── scripts/
│   ├── build-linux.sh
│   ├── build-windows.cmd
│   └── build-windows.ps1
├── src/sphinx_needs_req_ui/
├── tests/
├── pyproject.toml
└── README.md

Code quality

Before pushing changes, format and check the Python sources with:

uv format
uvx ruff check .

GitHub Actions enforces the corresponding read-only checks on every pull request and on pushes to main:

uv format --check
uvx ruff check .

Release tags run the same quality checks before platform binaries are built.