Development¶
Installation¶
The latest development version can be installed using pip, either directly from Git or after cloning the repository.
Install TeXact from Git
$ pip install "git+ssh://git@github.com/Theodor-Lindberg/texact.git"
Install TeXact after cloning the repository
$ pip install .
If TeXact has already been installed from Git via pip, chances are a cached version will be used instead of the latest. To be sure the latest is installed, do the following:
Install TeXact from git, avoiding caches
$ pip install --force-reinstall --no-cache-dir "git+ssh://git@github.com/Theodor-Lindberg/texact.git"
Local development¶
Install the project in editable mode, along with the tools used below:
$ python -m pip install -e ".[docs,dev]"
Editable installation makes the texact command available for CLI tests
while picking up source changes. The docs extra installs Sphinx, the
documentation extensions and theme, and pre-commit. The dev extra installs
pytest and pre-commit.
Building the documentation¶
From the repository root, build the current working tree as HTML:
$ python -m sphinx -b html docs docs/_build/html
Open docs/_build/html/index.html in a browser. Alternatively, run
make html from docs/. Generated files under docs/_build/ are not
documentation sources and should not be committed.
The documentation CI builds versioned documentation with make multiversion
from docs/. It selects compatible Git tags and branches, so its output is
based on Git refs rather than uncommitted changes. A full checkout with tags
is needed to reproduce the versioned build.
Running tests¶
From the repository root, run the regression suite as:
$ python -m pytest -q test
Installing pre-commit checks¶
After installing the development dependencies, install the Git hook from the repository root:
$ python -m pre_commit install
The hook runs the configured checks on staged files when committing. Some checks may modify files; review and stage those changes before committing again.
CI also tests TeXact’s published hook from the checked-out Git commit. To run that integration test locally, commit the hook changes first, then run:
$ python -m pytest -q test/pre_commit_hook.py
Code structure¶
The tool is implemented as a set of reviewers, each with its own focus. The reviewers keep track of their comments as the LaTeX file is processed line by line. Once the entire file has passed, all diagnostics are printed to the console, referencing line numbers. A summary is also outputted at the end. As the reviewers are independent of one another, adding new ones does not break existing features.
Reviewer implementations are located in source/reviewers/. All inherit
from the base class in source/reviewers/reviewer.py, and a central
rule registry is in source/reviewers/rules.py.
Rule identity¶
Every diagnostic refers to one immutable Rule in the central registry.
The registry contains the error code, name, message template, severity,
and documentation path. A Diagnostic adds the context for one
occurrence: source filename, line, and the rendered message.
Reviewer prefixes:
Reviewer_InthisusesINT.Reviewer_CasingusesCAS.Reviewer_UnsureusesUNS.Reviewer_RefLabelusesREF.Reviewer_FigureusesFIG.Reviewer_ChkTeXusesCHK.
Each reviewer owns the numeric suffixes in its prefix. For example,
CAS001 is the casing rule and FIG003 is the missing-figure-label
rule. Native ChkTeX diagnostics use CHK001 through CHK899 with the
Native ChkTeX diagnostics use CHK001 through CHK899 with the
native ChkTeX number preserved. Native numbers at or above 900 are shifted
into a disjoint range. TeXact’s ChkTeX lifecycle rules use CHK901 through
CHK904 so the two sources cannot collide.
Rule documentation is indexed at docs/rules/index.md. Each TeXact rule
has its own Markdown page under docs/rules/ with sections for what it
detects, why the issue matters, and a LaTeX example. When adding a rule, add
its registry entry, use the returned named rule handle when creating
diagnostics, add its dedicated page to the hidden rule toctree, and add tests.
Never reuse a published code.
Adding features¶
All reviewers inherit from the same base class, Reviewer, and
implement a set of methods: process_line, get_comments,
get_summary, get_status, and get_name. get_comments
returns Diagnostic objects linked to registry Rule objects.
Use a named Rule handle from source/reviewers/rules.py and
call its render_message method for dynamic values. Add a test that checks
the registry metadata, the diagnostic location, and the rendered code in CLI
output.
Adding a feature involves either modifying an existing reviewer
or adding a new one.
The easiest way to get started is by studying one of the existing
classes, e.g. Reviewer_Unsure. The main file, texact, must be
updated to include any new reviewer.
Options to the command-line interface and the parsing of the configuration
file can be added as well.