Javanaut/ffx
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Convert docs to sphinx

Browse Source
This commit is contained in:
Javanaut
2026-06-15 11:14:21 +02:00
parent 12be6e985a
commit 1a11710df7
17 changed files with 1048 additions and 172 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
.gitignore vendored
View File

@@ -1,7 +1,6 @@
__pycache__/
*.py[cod]
junk/
.vscode
.ipynb_checkpoints/
tools/ansible/inventory/hawaii.yml
tools/ansible/inventory/peppermint.yml
@@ -17,6 +16,7 @@ dist/
*.egg-info/
.venv/
venv/
docs/_build/
.codex
@@ -24,4 +24,4 @@ venv/
*.webm
*.mp4
ffmpeg2pass-0.log
*.sup
*.sup

11
.vscode/extensions.json vendored Normal file
View File

@@ -0,0 +1,11 @@
{
"recommendations": [
"swyddfa.esbonio",
"ms-python.python",
"ms-python.vscode-pylance",
"ms-python.debugpy",
"tamasfe.even-better-toml",
"redhat.vscode-yaml",
"DavidAnson.vscode-markdownlint"
]
}

18
.vscode/settings.json vendored Normal file
View File

@@ -0,0 +1,18 @@
{
"esbonio.sphinx.pythonCommand": "${venv:.venv}/bin/python",
"esbonio.sphinx.buildCommand": [
"sphinx-build",
"-b",
"html",
"docs",
"docs/_build/html"
],
"python.defaultInterpreterPath": "${workspaceFolder}/.venv/bin/python",
"python.testing.pytestEnabled": true,
"python.testing.pytestArgs": [
"--ignore=tests/legacy",
"--ignore=tests/support",
"tests"
],
"restructuredtext.confPath": "${workspaceFolder}/docs"
}

8
SCRATCHPAD.md
View File

@@ -69,3 +69,11 @@
## Delete When
- Delete this scratchpad once the optimization backlog is either converted into issues/work items or distilled into durable project guidance.
<!--
DuplicatePatternMatchError: Filename 'conan_S01E727_amalgam.avi.mkv' matched more than one pattern: show #30983 pattern #123 'conan_([sS][0-9]+[eE][0-9]+)_amalgam.avi.mkv', show #30983 pattern #124
'conan_([sS][0-9]+[eE][0-9]+)_amalgam.avi'
-->

21
docs/Makefile Normal file
View File

@@ -0,0 +1,21 @@
SPHINXOPTS ?=
VENV_SPHINXBUILD = ../.venv/bin/sphinx-build
SPHINXBUILD ?= $(if $(wildcard $(VENV_SPHINXBUILD)),$(VENV_SPHINXBUILD),sphinx-build)
SOURCEDIR = .
BUILDDIR = _build
.PHONY: help clean html linkcheck
help:
@echo "Please use 'make <target>' where <target> is one of"
@echo " html to make standalone HTML files"
@echo " linkcheck to check all external links for integrity"
clean:
rm -rf "$(BUILDDIR)"
html:
@$(SPHINXBUILD) -b html "$(SOURCEDIR)" "$(BUILDDIR)/html" $(SPHINXOPTS)
linkcheck:
@$(SPHINXBUILD) -b linkcheck "$(SOURCEDIR)" "$(BUILDDIR)/linkcheck" $(SPHINXOPTS)

31
docs/api.rst Normal file
View File

@@ -0,0 +1,31 @@
API Reference
=============
This section exposes selected modules that are useful when working on tests,
diagnostics, process execution, metadata editing, and file probing.
CLI Helpers
-----------
.. automodule:: ffx.cli
:members:
:undoc-members:
Process Helpers
---------------
.. automodule:: ffx.process
:members:
:undoc-members:
File Probing
------------
.. automodule:: ffx.file_properties
Metadata Editing
----------------
.. automodule:: ffx.metadata_editor
:members:
:undoc-members:

44
docs/conf.py Normal file
View File

@@ -0,0 +1,44 @@
from __future__ import annotations
from importlib.metadata import PackageNotFoundError, version as package_version
from pathlib import Path
import sys
ROOT_DIR = Path(__file__).resolve().parents[1]
SRC_DIR = ROOT_DIR / "src"
sys.path.insert(0, str(SRC_DIR))
project = "FFX"
author = "javanaut@maveno.de"
copyright = "2026, Maveno"
try:
release = package_version("ffx")
except PackageNotFoundError:
release = "0.0.0"
version = release
extensions = [
"sphinx.ext.autodoc",
"sphinx.ext.napoleon",
"sphinx.ext.viewcode",
"sphinx_copybutton",
]
source_suffix = {
".rst": "restructuredtext",
}
templates_path = ["_templates"]
exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
html_theme = "sphinx_rtd_theme"
html_title = "FFX"
html_static_path = []
autodoc_typehints = "description"
autodoc_member_order = "bysource"
napoleon_google_docstring = True
napoleon_numpy_docstring = True

50
docs/development.rst Normal file
View File

@@ -0,0 +1,50 @@
Development
===========
The repo-local ``.venv`` is the preferred environment for contributors working
on tests or documentation:
.. code-block:: sh
tests/prepare.sh
The preparation script installs the package in editable mode with both test and
documentation extras:
.. code-block:: text
.[test,docs]
Run Tests
---------
Run the modern pytest suite:
.. code-block:: sh
.venv/bin/python -m pytest --ignore=tests/legacy --ignore=tests/support tests
The legacy harness remains available separately and is intentionally not part of
the default pytest run.
Build Docs
----------
Build HTML documentation:
.. code-block:: sh
.venv/bin/sphinx-build -b html docs docs/_build/html
The same command is wrapped by the Sphinx ``Makefile``:
.. code-block:: sh
make -C docs html
VS Code
-------
The repository includes ``.vscode/extensions.json`` with recommended
extensions, including Esbonio for Sphinx language-server support. The workspace
settings point Python tooling and Esbonio at the repo-local ``.venv``.

BIN
docs/esbonio.db Normal file
View File

Binary file not shown.

170
docs/file_formats.md
View File

@@ -1,170 +0,0 @@
# File Formats
This document captures source-file-format notes that complement the normative
requirements in `requirements/source_file_formats.md`.
The first documented format is a Matroska source that carries styled ASS/SSA
subtitle streams together with embedded font attachments.
## Styled ASS In Matroska With Embedded Fonts
These files are typically `.mkv` releases where subtitle rendering quality
depends on keeping both parts of the subtitle package together:
- one or more subtitle streams with codec `ass`
- one or more attachment streams that embed font files used by those subtitles
This matters because ASS subtitles are not plain text subtitles in the narrow
WebVTT sense. They can carry layout, styling, positioning, karaoke, signs, and
other typesetting effects. If the matching embedded fonts are lost, consumers
can still see subtitle text but the intended styling and sometimes glyph
coverage can be degraded.
For FFX this format is special because the ASS subtitle streams should remain
normally editable and mappable, while the related font attachments should be
transported unchanged.
## Observed Sample
Assessment date: `2026-04-17`
Observed sample file:
- `tests/assets/boruto_s01e283_ssa.mkv`
Commands used for assessment:
```bash
ffprobe tests/assets/boruto_s01e283_ssa.mkv
ffprobe -hide_banner -show_format -show_streams -of json tests/assets/boruto_s01e283_ssa.mkv
```
Observed stream layout:
| Stream index | Kind | Key details |
| --- | --- | --- |
| `0` | video | `codec_name=h264` |
| `1` | audio | `codec_name=aac`, `language=jpn` |
| `2` | subtitle | `codec_name=ass`, `language=ger`, default |
| `3` | subtitle | `codec_name=ass`, `language=eng` |
| `4`-`13` | attachment | `tags.mimetype=font/ttf`, `.ttf` filenames |
Observed attachment filenames:
- `AmazonEmberTanuki-Italic.ttf`
- `AmazonEmberTanuki-Regular.ttf`
- `Arial.ttf`
- `Arial Bold.ttf`
- `Georgia.ttf`
- `Times New Roman.ttf`
- `Times New Roman Bold.ttf`
- `Trebuchet MS.ttf`
- `Verdana.ttf`
- `Verdana Bold.ttf`
Important probe behavior from the real sample:
- Plain `ffprobe` lists the font streams as `Attachment: none`.
- Plain `ffprobe` also prints warnings such as `Could not find codec
parameters for stream 4 (Attachment: none): unknown codec` and later
`Unsupported codec with id 0 for input stream ...`.
- The JSON produced by `FileProperties.FFPROBE_COMMAND_TOKENS`
(`ffprobe -hide_banner -show_format -show_streams -of json`) still exposes
the attachment streams clearly through `codec_type="attachment"` and the
attachment tags.
- In that JSON, the attachment streams do not expose `codec_name`.
This last point is important for FFX: robust detection must not depend on
attachment `codec_name` being present.
## Detection Guidance
Current known indicators for this format are:
- one or more subtitle streams with `codec_type="subtitle"` and
`codec_name="ass"`
- one or more attachment streams with `codec_type="attachment"`
- attachment tags that identify embedded fonts, especially
`tags.mimetype="font/ttf"`
- attachment filenames that end in `.ttf`
The pattern can vary. FFX should therefore treat the above as a cluster of
signals rather than an exact signature tied to one file.
Inference from the observed sample plus FFmpeg documentation:
- MIME matching should not be limited to `font/ttf` alone.
- The Boruto sample uses `font/ttf`.
- FFmpeg's Matroska attachment example uses
`mimetype=application/x-truetype-font` for a `.ttf` attachment.
- Detection should therefore normalize multiple TTF-like MIME values rather
than depend on a single exact string.
## Processing Expectations In FFX
The format-specific requirements live in
`requirements/source_file_formats.md`. In practical terms, FFX should:
- recognize the ASS-plus-font-attachment pattern even when attachment probe
data is incomplete
- tell the operator that the pattern was detected and that special handling is
being used
- reject sidecar subtitle import for such sources, because converting or
replacing these subtitle tracks with ordinary external text subtitles would
break the intended subtitle package
- continue to allow normal manipulation of the ASS subtitle tracks themselves
- preserve the font attachment streams unchanged
## FFmpeg Notes
Relevant FFmpeg documentation confirms several behaviors that line up with
FFX's needs:
- FFmpeg documents `-attach` as adding an attachment stream to the output, and
explicitly names Matroska fonts used in subtitle rendering as an example.
- FFmpeg documents attachment streams as regular streams that are created after
the mapped media streams.
- FFmpeg documents `-dump_attachment` for extracting attachment streams, which
is useful for debugging or validating a source file's embedded fonts.
- FFmpeg's Matroska example requires a `mimetype` metadata tag for attached
fonts, which is consistent with using attachment tags as detection signals.
- FFmpeg also notes that attachments are implemented as codec extradata. That
helps explain why probe output for attachment streams can look different from
ordinary audio, video, and subtitle streams.
Implication for FFX:
- Attachment preservation is not an optional cosmetic feature for this format.
It is part of preserving the subtitle package correctly.
## Jellyfin Notes
Jellyfin's documentation also supports keeping this format intact:
- Jellyfin's subtitle compatibility table lists `ASS/SSA` as supported in
`MKV` and not supported in `MP4`.
- Jellyfin notes that when subtitles must be transcoded, they are either
converted to a supported format or burned into the video, and burning them in
is the most CPU-intensive path.
- Jellyfin's subtitle-extraction example for `SSA/ASS` first dumps attachment
streams and then extracts the ASS subtitle stream, which reflects the real
relationship between ASS subtitles and embedded fonts in MKV releases.
- Jellyfin's font documentation says text-based subtitles require fonts to
render properly.
- Jellyfin's configuration documentation says the web client uses configured
fallback fonts for ASS subtitles when other fonts such as MKV attachments or
client-side fonts are not available.
Inference from the Jellyfin compatibility tables:
- Keeping this subtitle format in Matroska is the safest interoperability
choice for Jellyfin consumers.
- Converting the subtitle payload to WebVTT would lose styled ASS behavior.
- Dropping the attachment streams would force client or fallback font
substitution and can change appearance or glyph coverage.
## References
- FFmpeg documentation: https://ffmpeg.org/ffmpeg.html
- Jellyfin codec support: https://jellyfin.org/docs/general/clients/codec-support/
- Jellyfin configuration and fonts: https://jellyfin.org/docs/general/administration/configuration/

192
docs/file_formats.rst Normal file
View File

@@ -0,0 +1,192 @@
File Formats
============
This document captures source-file-format notes that complement the normative
requirements in ``requirements/source_file_formats.md``.
The first documented format is a Matroska source that carries styled ASS/SSA
subtitle streams together with embedded font attachments.
Styled ASS In Matroska With Embedded Fonts
------------------------------------------
These files are typically ``.mkv`` releases where subtitle rendering quality
depends on keeping both parts of the subtitle package together:
* one or more subtitle streams with codec ``ass``
* one or more attachment streams that embed font files used by those subtitles
This matters because ASS subtitles are not plain text subtitles in the narrow
WebVTT sense. They can carry layout, styling, positioning, karaoke, signs, and
other typesetting effects. If the matching embedded fonts are lost, consumers
can still see subtitle text but the intended styling and sometimes glyph
coverage can be degraded.
For FFX this format is special because the ASS subtitle streams should remain
normally editable and mappable, while the related font attachments should be
transported unchanged.
Observed Sample
---------------
Assessment date: ``2026-04-17``
Observed sample file:
* ``tests/assets/boruto_s01e283_ssa.mkv``
Commands used for assessment:
.. code-block:: bash
ffprobe tests/assets/boruto_s01e283_ssa.mkv
ffprobe -hide_banner -show_format -show_streams -of json tests/assets/boruto_s01e283_ssa.mkv
Observed stream layout:
.. list-table::
:header-rows: 1
* - Stream index
- Kind
- Key details
* - ``0``
- video
- ``codec_name=h264``
* - ``1``
- audio
- ``codec_name=aac``, ``language=jpn``
* - ``2``
- subtitle
- ``codec_name=ass``, ``language=ger``, default
* - ``3``
- subtitle
- ``codec_name=ass``, ``language=eng``
* - ``4``-``13``
- attachment
- ``tags.mimetype=font/ttf``, ``.ttf`` filenames
Observed attachment filenames:
* ``AmazonEmberTanuki-Italic.ttf``
* ``AmazonEmberTanuki-Regular.ttf``
* ``Arial.ttf``
* ``Arial Bold.ttf``
* ``Georgia.ttf``
* ``Times New Roman.ttf``
* ``Times New Roman Bold.ttf``
* ``Trebuchet MS.ttf``
* ``Verdana.ttf``
* ``Verdana Bold.ttf``
Important probe behavior from the real sample:
* Plain ``ffprobe`` lists the font streams as ``Attachment: none``.
* Plain ``ffprobe`` also prints warnings such as ``Could not find codec
parameters for stream 4 (Attachment: none): unknown codec`` and later
``Unsupported codec with id 0 for input stream ...``.
* The JSON produced by ``FileProperties.FFPROBE_COMMAND_TOKENS``
(``ffprobe -hide_banner -show_format -show_streams -of json``) still exposes
the attachment streams clearly through ``codec_type="attachment"`` and the
attachment tags.
* In that JSON, the attachment streams do not expose ``codec_name``.
This last point is important for FFX: robust detection must not depend on
attachment ``codec_name`` being present.
Detection Guidance
------------------
Current known indicators for this format are:
* one or more subtitle streams with ``codec_type="subtitle"`` and
``codec_name="ass"``
* one or more attachment streams with ``codec_type="attachment"``
* attachment tags that identify embedded fonts, especially
``tags.mimetype="font/ttf"``
* attachment filenames that end in ``.ttf``
The pattern can vary. FFX should therefore treat the above as a cluster of
signals rather than an exact signature tied to one file.
Inference from the observed sample plus FFmpeg documentation:
* MIME matching should not be limited to ``font/ttf`` alone.
* The Boruto sample uses ``font/ttf``.
* FFmpeg's Matroska attachment example uses
``mimetype=application/x-truetype-font`` for a ``.ttf`` attachment.
* Detection should therefore normalize multiple TTF-like MIME values rather
than depend on a single exact string.
Processing Expectations In FFX
------------------------------
The format-specific requirements live in
``requirements/source_file_formats.md``. In practical terms, FFX should:
* recognize the ASS-plus-font-attachment pattern even when attachment probe data
is incomplete
* tell the operator that the pattern was detected and that special handling is
being used
* reject sidecar subtitle import for such sources, because converting or
replacing these subtitle tracks with ordinary external text subtitles would
break the intended subtitle package
* continue to allow normal manipulation of the ASS subtitle tracks themselves
* preserve the font attachment streams unchanged
FFmpeg Notes
------------
Relevant FFmpeg documentation confirms several behaviors that line up with
FFX's needs:
* FFmpeg documents ``-attach`` as adding an attachment stream to the output, and
explicitly names Matroska fonts used in subtitle rendering as an example.
* FFmpeg documents attachment streams as regular streams that are created after
the mapped media streams.
* FFmpeg documents ``-dump_attachment`` for extracting attachment streams, which
is useful for debugging or validating a source file's embedded fonts.
* FFmpeg's Matroska example requires a ``mimetype`` metadata tag for attached
fonts, which is consistent with using attachment tags as detection signals.
* FFmpeg also notes that attachments are implemented as codec extradata. That
helps explain why probe output for attachment streams can look different from
ordinary audio, video, and subtitle streams.
Implication for FFX:
* Attachment preservation is not an optional cosmetic feature for this format.
It is part of preserving the subtitle package correctly.
Jellyfin Notes
--------------
Jellyfin's documentation also supports keeping this format intact:
* Jellyfin's subtitle compatibility table lists ``ASS/SSA`` as supported in
``MKV`` and not supported in ``MP4``.
* Jellyfin notes that when subtitles must be transcoded, they are either
converted to a supported format or burned into the video, and burning them in
is the most CPU-intensive path.
* Jellyfin's subtitle-extraction example for ``SSA/ASS`` first dumps attachment
streams and then extracts the ASS subtitle stream, which reflects the real
relationship between ASS subtitles and embedded fonts in MKV releases.
* Jellyfin's font documentation says text-based subtitles require fonts to
render properly.
* Jellyfin's configuration documentation says the web client uses configured
fallback fonts for ASS subtitles when other fonts such as MKV attachments or
client-side fonts are not available.
Inference from the Jellyfin compatibility tables:
* Keeping this subtitle format in Matroska is the safest interoperability choice
for Jellyfin consumers.
* Converting the subtitle payload to WebVTT would lose styled ASS behavior.
* Dropping the attachment streams would force client or fallback font
substitution and can change appearance or glyph coverage.
References
----------
* FFmpeg documentation: https://ffmpeg.org/ffmpeg.html
* Jellyfin codec support: https://jellyfin.org/docs/general/clients/codec-support/
* Jellyfin configuration and fonts: https://jellyfin.org/docs/general/administration/configuration/

25
docs/index.rst Normal file
View File

@@ -0,0 +1,25 @@
FFX Documentation
=================
FFX is a local command-line and Textual terminal UI for inspecting TV episode
files, storing normalization rules, and converting media into predictable
archive-ready outputs.
This documentation covers operator setup, day-to-day command usage, contributor
workflow, format-specific notes, and generated API references for the smaller
utility modules.
.. toctree::
:maxdepth: 2
:caption: User Guide
installation
usage
file_formats
.. toctree::
:maxdepth: 2
:caption: Contributor Guide
development
api

52
docs/installation.rst Normal file
View File

@@ -0,0 +1,52 @@
Installation
============
FFX is designed for a Linux-like workstation with local command execution. The
runtime media tools must be available on ``PATH``:
* ``ffmpeg``
* ``ffprobe``
* ``cpulimit``
User Bundle
-----------
The persistent user installation is prepared with the two-step flow described in
the project README:
.. code-block:: sh
bash tools/setup.sh
bash tools/configure_workstation.sh
``tools/setup.sh`` creates the long-lived bundle virtualenv at
``~/.local/share/ffx.venv`` and exposes the ``ffx`` command. The workstation
script checks system tools and seeds local config directories.
Local Test And Docs Environment
-------------------------------
Contributor test and documentation work uses the repo-local virtualenv:
.. code-block:: sh
tests/prepare.sh
The script creates ``.venv``, installs FFX in editable mode with test and docs
extras, and verifies the Sphinx toolchain. Use check-only mode when you only
want to inspect readiness:
.. code-block:: sh
tests/prepare.sh --check
Documentation Build
-------------------
After preparation, build the documentation with:
.. code-block:: sh
.venv/bin/sphinx-build -b html docs docs/_build/html
The generated site starts at ``docs/_build/html/index.html``.

42
docs/make.bat Normal file
View File

@@ -0,0 +1,42 @@
@ECHO OFF
pushd %~dp0
if "%SPHINXBUILD%" == "" if exist ..\.venv\Scripts\sphinx-build.exe (
set SPHINXBUILD=..\.venv\Scripts\sphinx-build.exe
)
if "%SPHINXBUILD%" == "" set SPHINXBUILD=sphinx-build
set SOURCEDIR=.
set BUILDDIR=_build
%SPHINXBUILD% >NUL 2>NUL
if errorlevel 9009 (
echo.
echo The 'sphinx-build' command was not found. Make sure Sphinx is installed,
echo then set SPHINXBUILD to the full path if needed.
exit /b 1
)
if "%1" == "" goto help
if "%1" == "html" goto html
if "%1" == "linkcheck" goto linkcheck
echo.
echo Unknown target "%1".
goto help
:html
%SPHINXBUILD% -b html %SOURCEDIR% %BUILDDIR%\html %SPHINXOPTS%
goto end
:linkcheck
%SPHINXBUILD% -b linkcheck %SOURCEDIR% %BUILDDIR%\linkcheck %SPHINXOPTS%
goto end
:help
echo.
echo Please use 'make.bat ^<target^>' where ^<target^> is one of
echo html to make standalone HTML files
echo linkcheck to check all external links for integrity
:end
popd

75
docs/usage.rst Normal file
View File

@@ -0,0 +1,75 @@
Usage
=====
FFX exposes a single ``ffx`` command with subcommands for inspection,
conversion, metadata editing, setup, and maintenance.
Inspect Files
-------------
Open the inspection workflow for one or more files:
.. code-block:: sh
ffx inspect /path/to/episode.mkv
Print resolved season-shift mappings without opening the TUI:
.. code-block:: sh
ffx inspect --shift /path/to/episode.mkv
Convert Files
-------------
Convert one or more source files using stored rules where available:
.. code-block:: sh
ffx convert /path/to/episode.mkv
Useful overrides include:
* ``--no-pattern`` to skip database pattern matching
* ``--show``, ``--season``, and ``--episode`` for explicit episode identity
* ``--output-directory`` for generated output placement
* ``--subtitle-directory`` and ``--subtitle-prefix`` for sidecar subtitle
imports
* ``--copy-video`` or ``--copy-audio`` to preserve selected stream types
* ``--rename-only`` for filename normalization without media rewriting
Manage Shows And Patterns
-------------------------
Open the Textual interface for show and pattern management:
.. code-block:: sh
ffx shows
Extract Streams
---------------
Extract streams from a file:
.. code-block:: sh
ffx unmux /path/to/episode.mkv
For subtitle-only extraction:
.. code-block:: sh
ffx unmux --subtitles-only --label show-name /path/to/episode.mkv
Detect Crop
-----------
Ask FFmpeg to suggest crop parameters:
.. code-block:: sh
ffx cropdetect /path/to/episode.mkv
The default sampling window is controlled by the application defaults and can be
overridden with command options.

6
pyproject.toml
View File

@@ -31,6 +31,12 @@ Issues = "https://gitea.maveno.de/Javanaut/ffx/issues"
test = [
"pytest",
]
docs = [
"esbonio",
"sphinx",
"sphinx-copybutton",
"sphinx-rtd-theme",
]
[build-system]
requires = [

471
tests/prepare.sh Executable file
View File

@@ -0,0 +1,471 @@
#!/usr/bin/env bash
set -u
SCRIPT_DIR="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)"
ROOT_DIR="$(cd -- "${SCRIPT_DIR}/.." && pwd)"
VENV_DIR="${FFX_TEST_VENV_DIR:-${ROOT_DIR}/.venv}"
VENV_BIN_DIR="${VENV_DIR}/bin"
VENV_PYTHON="${VENV_BIN_DIR}/python"
VENV_PIP="${VENV_BIN_DIR}/pip"
CHECK_ONLY=0
READINESS_FAILURES=0
INSTALL_FAILURES=0
MISSING_REQUIRED_SYSTEM=()
COLOR_RESET=""
COLOR_GREEN=""
COLOR_YELLOW=""
COLOR_RED=""
if [ -t 1 ]; then
COLOR_RESET="$(printf '\033[0m')"
COLOR_GREEN="$(printf '\033[32m')"
COLOR_YELLOW="$(printf '\033[33m')"
COLOR_RED="$(printf '\033[31m')"
fi
usage() {
cat <<EOF
Usage: $(basename "$0") [--check] [--help]
Prepare the repo-local FFX test environment at:
${VENV_DIR}
Actions:
- verify or install required system commands for tests
- create or reuse the repo-local test virtualenv
- install this repository into the venv with Python test and docs extras
Options:
--check Report readiness only. Do not create, install, or modify.
--help Show this help text.
Environment overrides:
FFX_TEST_VENV_DIR Override the test virtualenv path. Defaults to ${ROOT_DIR}/.venv.
Notes:
- This script prepares a project-local test environment, not the persistent user bundle.
- The persistent bundle setup remains owned by tools/setup.sh.
EOF
}
status_ok() {
printf '%sok%s' "${COLOR_GREEN}" "${COLOR_RESET}"
}
status_warn() {
printf '%swarn%s' "${COLOR_YELLOW}" "${COLOR_RESET}"
}
status_fail() {
printf '%sfailed%s' "${COLOR_RED}" "${COLOR_RESET}"
}
report_component() {
local level="$1"
local label="$2"
local detail="$3"
local rendered_status=""
case "${level}" in
ok)
rendered_status="$(status_ok)"
;;
warn)
rendered_status="$(status_warn)"
;;
*)
rendered_status="$(status_fail)"
;;
esac
printf '[%s] %s%s\n' "${rendered_status}" "${label}" "${detail:+: $detail}"
}
command_exists() {
command -v "$1" >/dev/null 2>&1
}
check_python_venv_support() {
python3 -m venv --help >/dev/null 2>&1
}
check_system_command() {
command_exists "$1"
}
check_venv_python() {
[ -x "${VENV_PYTHON}" ]
}
check_venv_pip() {
check_venv_python && "${VENV_PIP}" --version >/dev/null 2>&1
}
check_venv_ffx() {
check_venv_python && "${VENV_PYTHON}" -m ffx version >/dev/null 2>&1
}
check_venv_pytest() {
check_venv_python && "${VENV_PYTHON}" -m pytest --version >/dev/null 2>&1
}
check_venv_sphinx() {
check_venv_python && "${VENV_BIN_DIR}/sphinx-build" --version >/dev/null 2>&1
}
check_venv_docs_packages() {
check_venv_python && "${VENV_PYTHON}" - <<'PY' >/dev/null 2>&1
import esbonio
import sphinx
import sphinx_rtd_theme
PY
}
check_editable_install() {
check_venv_python && FFX_REPO_ROOT="${ROOT_DIR}" "${VENV_PYTHON}" - <<'PY' >/dev/null 2>&1
from __future__ import annotations
import os
from pathlib import Path
import ffx
repo_root = Path(os.environ["FFX_REPO_ROOT"]).resolve()
package_path = Path(ffx.__file__).resolve()
raise SystemExit(0 if repo_root in package_path.parents else 1)
PY
}
check_python_environment_ready() {
check_venv_python &&
check_venv_pip &&
check_venv_pytest &&
check_venv_sphinx &&
check_venv_docs_packages &&
check_venv_ffx &&
check_editable_install
}
command_detail() {
command -v "$1" || printf "command '%s' not found" "$1"
}
python_venv_detail() {
if check_python_venv_support; then
printf 'python3 -m venv is available'
else
printf 'python3 venv support is unavailable'
fi
}
venv_python_detail() {
if check_venv_python; then
printf '%s' "${VENV_PYTHON}"
else
printf 'missing %s' "${VENV_PYTHON}"
fi
}
venv_pip_detail() {
if check_venv_pip; then
"${VENV_PIP}" --version
else
printf 'missing pip in %s' "${VENV_DIR}"
fi
}
venv_ffx_detail() {
if check_venv_ffx; then
printf 'ffx import and CLI entry are available'
else
printf 'ffx is not installed in %s' "${VENV_DIR}"
fi
}
venv_pytest_detail() {
if check_venv_pytest; then
"${VENV_PYTHON}" -m pytest --version 2>/dev/null | head -n 1
else
printf 'pytest is not installed in %s' "${VENV_DIR}"
fi
}
venv_sphinx_detail() {
if check_venv_sphinx; then
"${VENV_BIN_DIR}/sphinx-build" --version 2>&1
else
printf 'sphinx-build is not installed in %s' "${VENV_DIR}"
fi
}
venv_docs_packages_detail() {
if check_venv_docs_packages; then
printf 'Sphinx, Read the Docs theme, and Esbonio packages are importable'
else
printf 'one or more docs packages are missing in %s' "${VENV_DIR}"
fi
}
editable_install_detail() {
if check_editable_install; then
printf 'ffx resolves from %s' "${ROOT_DIR}"
else
printf 'ffx does not resolve from the project source tree'
fi
}
report_required_command() {
local label="$1"
local command_name="$2"
if check_system_command "${command_name}"; then
report_component ok "${label}" "$(command_detail "${command_name}")"
else
report_component failed "${label}" "$(command_detail "${command_name}")"
MISSING_REQUIRED_SYSTEM+=("${command_name}")
READINESS_FAILURES=$((READINESS_FAILURES + 1))
fi
}
print_system_status() {
MISSING_REQUIRED_SYSTEM=()
echo "System toolchain status:"
report_required_command "git" "git"
report_required_command "python3" "python3"
if check_system_command "python3" && check_python_venv_support; then
report_component ok "python3 venv" "$(python_venv_detail)"
else
report_component failed "python3 venv" "$(python_venv_detail)"
MISSING_REQUIRED_SYSTEM+=("python3-venv")
READINESS_FAILURES=$((READINESS_FAILURES + 1))
fi
report_required_command "ffmpeg" "ffmpeg"
report_required_command "ffprobe" "ffprobe"
report_required_command "cpulimit" "cpulimit"
}
print_python_status() {
echo "Repo test and docs virtualenv status:"
if check_venv_python; then
report_component ok "test virtualenv" "$(venv_python_detail)"
else
report_component failed "test virtualenv" "$(venv_python_detail)"
READINESS_FAILURES=$((READINESS_FAILURES + 1))
fi
if check_venv_pip; then
report_component ok "test pip" "$(venv_pip_detail)"
else
report_component failed "test pip" "$(venv_pip_detail)"
READINESS_FAILURES=$((READINESS_FAILURES + 1))
fi
if check_venv_pytest; then
report_component ok "test pytest" "$(venv_pytest_detail)"
else
report_component failed "test pytest" "$(venv_pytest_detail)"
READINESS_FAILURES=$((READINESS_FAILURES + 1))
fi
if check_venv_sphinx; then
report_component ok "docs sphinx" "$(venv_sphinx_detail)"
else
report_component failed "docs sphinx" "$(venv_sphinx_detail)"
READINESS_FAILURES=$((READINESS_FAILURES + 1))
fi
if check_venv_docs_packages; then
report_component ok "docs packages" "$(venv_docs_packages_detail)"
else
report_component failed "docs packages" "$(venv_docs_packages_detail)"
READINESS_FAILURES=$((READINESS_FAILURES + 1))
fi
if check_venv_ffx; then
report_component ok "test ffx" "$(venv_ffx_detail)"
else
report_component failed "test ffx" "$(venv_ffx_detail)"
READINESS_FAILURES=$((READINESS_FAILURES + 1))
fi
if check_editable_install; then
report_component ok "editable source" "$(editable_install_detail)"
else
report_component failed "editable source" "$(editable_install_detail)"
READINESS_FAILURES=$((READINESS_FAILURES + 1))
fi
}
print_status_report() {
READINESS_FAILURES=0
print_system_status
echo
print_python_status
}
detect_package_manager() {
if command_exists apt-get; then
printf 'apt-get\n'
return 0
fi
if command_exists pacman; then
printf 'pacman\n'
return 0
fi
return 1
}
run_root_command() {
if [ "${EUID}" -eq 0 ]; then
"$@"
elif command_exists sudo; then
sudo -n "$@"
else
return 1
fi
}
install_system_requirements() {
local package_manager
if [ "${#MISSING_REQUIRED_SYSTEM[@]}" -eq 0 ]; then
return 0
fi
if ! package_manager="$(detect_package_manager)"; then
printf 'No supported package manager found for automatic system preparation.\n' >&2
INSTALL_FAILURES=$((INSTALL_FAILURES + 1))
return 1
fi
case "${package_manager}" in
apt-get)
printf 'Installing required system dependencies via apt-get...\n'
if ! run_root_command apt-get update; then
printf 'apt-get update failed or requires interactive sudo.\n' >&2
INSTALL_FAILURES=$((INSTALL_FAILURES + 1))
return 1
fi
if ! run_root_command apt-get install -y git python3 python3-venv ffmpeg cpulimit; then
printf 'apt-get install failed or requires interactive sudo.\n' >&2
INSTALL_FAILURES=$((INSTALL_FAILURES + 1))
return 1
fi
;;
pacman)
printf 'Installing required system dependencies via pacman...\n'
if ! run_root_command pacman -Sy --noconfirm git python ffmpeg cpulimit; then
printf 'pacman install failed or requires interactive sudo.\n' >&2
INSTALL_FAILURES=$((INSTALL_FAILURES + 1))
return 1
fi
;;
esac
return 0
}
ensure_test_venv() {
if ! check_venv_python; then
printf 'Creating repo test virtualenv at %s...\n' "${VENV_DIR}"
if ! python3 -m venv "${VENV_DIR}"; then
printf 'Failed to create test virtualenv at %s.\n' "${VENV_DIR}" >&2
INSTALL_FAILURES=$((INSTALL_FAILURES + 1))
return 1
fi
fi
if ! check_venv_pip; then
printf 'Missing pip in %s.\n' "${VENV_DIR}" >&2
INSTALL_FAILURES=$((INSTALL_FAILURES + 1))
return 1
fi
printf 'Installing FFX package with test and docs extras into %s...\n' "${VENV_DIR}"
if ! (
cd "${ROOT_DIR}" &&
"${VENV_PIP}" install --editable '.[test,docs]'
); then
printf 'Failed to install FFX package with test and docs extras into %s.\n' "${VENV_DIR}" >&2
INSTALL_FAILURES=$((INSTALL_FAILURES + 1))
return 1
fi
return 0
}
parse_args() {
while [ "$#" -gt 0 ]; do
case "$1" in
--check)
CHECK_ONLY=1
;;
--help|-h)
usage
exit 0
;;
*)
printf 'Unknown option: %s\n\n' "$1" >&2
usage >&2
exit 2
;;
esac
shift
done
}
main() {
parse_args "$@"
print_status_report
if [ "${CHECK_ONLY}" -eq 0 ]; then
if [ "${#MISSING_REQUIRED_SYSTEM[@]}" -gt 0 ]; then
echo
install_system_requirements
fi
if check_python_environment_ready; then
echo
report_component ok "Python package install" "repo test and docs virtualenv is already ready"
elif check_system_command "python3" && check_python_venv_support; then
echo
ensure_test_venv
fi
echo
print_status_report
fi
echo
if [ "${INSTALL_FAILURES}" -gt 0 ]; then
echo "One or more test preparation steps failed; see the status checks above." >&2
exit 1
fi
if [ "${READINESS_FAILURES}" -gt 0 ]; then
if [ "${CHECK_ONLY}" -eq 1 ]; then
echo "The FFX test and docs environment is incomplete." >&2
else
echo "Required test or docs components are still missing after preparation." >&2
fi
exit 1
fi
if [ "${CHECK_ONLY}" -eq 1 ]; then
echo "The FFX test and docs environment is ready."
else
echo "The FFX test and docs environment is prepared."
fi
}
main "$@"