mirror of
https://github.com/hiyouga/LLaMA-Factory.git
synced 2026-09-27 01:45:42 +08:00
53 lines
3.9 KiB
Markdown
53 lines
3.9 KiB
Markdown
---
|
|
name: llamafactory-v1-docs
|
|
description: Write, review, update, build, or preview LlamaFactory v1 documentation. Use for docs work grounded in src/llamafactory/v1; not for running model training.
|
|
---
|
|
|
|
# LlamaFactory v1 Documentation
|
|
|
|
## Scope
|
|
|
|
- Work in the repository containing both `docs/` and `src/llamafactory/v1/`. Check the branch and existing changes first.
|
|
- Treat this branch's v1 implementation as the source of truth; do not infer behavior from v0 or upstream code.
|
|
- Maintain Chinese and English counterparts for pages touched by the task unless the user limits the language. Align relative page paths, structure, technical meaning, examples, and navigation; translate prose naturally while preserving code identifiers and commands. Report any remaining language gaps.
|
|
- Preserve unrelated edits and explicitly deferred issues. Review-only requests stay read-only; build-only requests do not rewrite content.
|
|
|
|
## Writing
|
|
|
|
- Explain features directly: behavior, configuration, execution, and constraints. Avoid assumed user goals, selection advice, rhetorical questions, and “use case” columns unless requested.
|
|
- Keep content ownership clear: feature guides explain usage; configuration pages define fields and semantics; developer guides explain internals. Link between them instead of repeating full sections.
|
|
- Use tables for factual comparisons. Keep examples short and distinguish complete configurations from partial snippets without repetitive setup reminders.
|
|
- Explain defaults, omitted versus explicit values, precedence, units, and conditional behavior—not just parameter names.
|
|
- In developer guides, show responsibilities, inputs, outputs, state ownership, and call order. Use a small example or tensor shapes when abstractions need clarification.
|
|
- Use one H1 per page, meaningful headings, language-tagged code blocks, relative links, and the appropriate `toctree` entry for new pages.
|
|
|
|
## Source and Examples
|
|
|
|
- Trace relevant configuration parsing, plugin registration, and call sites. A declared field or interface alone does not establish support.
|
|
- Distinguish related concepts, such as quantization plugins, backends, bit widths, and formats. Verify current support rather than hardcoding assumptions into this skill.
|
|
- Keep model IDs, adapter paths, model directories, and filenames consistent across training, inference, and export examples. Match each downstream input to the preceding output.
|
|
- Parse changed YAML examples and check their placement and composition. Examples described as runnable need the required imports, interfaces, and registration.
|
|
- Document confirmed behavior and limitations. Report unresolved implementation questions separately; do not insert speculation or conversation history into public documentation.
|
|
|
|
## Build and Preview
|
|
|
|
Use an existing Python environment with `docs/requirements.txt` installed. Build both languages from the repository root, or just the language explicitly requested:
|
|
|
|
```bash
|
|
for doc_language in zh en; do
|
|
env LC_ALL=C LANG=C python3 -m sphinx -b html -n -W --keep-going "docs/$doc_language" "docs/_build/html/$doc_language" || exit 1
|
|
done
|
|
```
|
|
|
|
Review the diff and build diagnostics; check changed pages, links, anchors, and table/code rendering. Fix issues introduced by authorized edits and rebuild. For review-only or build-only requests, report existing failures without expanding the scope. Do not disable strict checks or run model training merely to validate documentation.
|
|
|
|
When a preview is requested, reuse a server serving this output or start one on an available local port:
|
|
|
|
```bash
|
|
python3 -m http.server 8765 --bind 127.0.0.1 --directory docs/_build/html
|
|
```
|
|
|
|
Open the relevant pages under `/zh/` and `/en/` on the preview server and verify the served content and language-switch links. Do not stop unrelated servers or publish the site automatically.
|
|
|
|
Report the changed files and completed checks briefly; include a preview link if available. Distinguish a successful documentation build from validated model execution.
|