Convert docs to sphinx
This commit is contained in:
Javanaut
21
docs/Makefile
Normal file
21
docs/Makefile
Normal 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
31
docs/api.rst
Normal 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
44
docs/conf.py
Normal 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
50
docs/development.rst
Normal 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
BIN
docs/esbonio.db
Normal file
Binary file not shown.
@@ -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
192
docs/file_formats.rst
Normal 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
25
docs/index.rst
Normal 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
52
docs/installation.rst
Normal 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
42
docs/make.bat
Normal 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
75
docs/usage.rst
Normal 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.
|
||||
Reference in New Issue
Block a user