agilab-docs

分类: 工具与效率 | 上传者: ThalesGroup | 下载: 0 | 版本: v1.0（最新）

Documentation workflow for AGILAB (sources vs generated HTML, public constraints, consistency checks).

更新日志: Source: GitHub https://github.com/ThalesGroup/agilab

目录结构

当前层级: .codex/skills/agilab-docs/

📄 SKILL.md 3.1 KB

SKILL.md

---
name: agilab-docs
description: Documentation workflow for AGILAB (sources vs generated HTML, public constraints, consistency checks).
license: BSD-3-Clause (see repo LICENSE)
metadata:
  updated: 2026-02-26
---

# Docs Skill (AGILAB)

Use this skill when editing docs content or docs build tooling for AGILAB.

## Source Of Truth

- Canonical editable docs source is `../thales_agilab/docs/source`.
- `docs/html` in this repo is generated output only (including `docs/html/_sources`).
- Never hand-edit files under `docs/html`.
- Do not change visible page labels directly in `docs/html` without regenerating from
  source: this is a frequent cause of stale/publication mismatches.

## Required Workflow (No Direct `docs/html` Edits)

1. Edit the canonical source file under `../thales_agilab/docs/source`.
2. Rebuild generated docs into this repo's `docs/html`.
3. Verify the generated page renders the updated labels in:
   - `docs/html/<page>.html`
   - any sidebar or navigation fragments in the same HTML build
4. Verify the change exists in both:
   - `../thales_agilab/docs/source/<file>`
   - `docs/html/<file>` (or `docs/html/_sources/<file>.txt`)

If you accidentally edit `docs/html` directly, discard that manual edit and regenerate from source.

## Source vs Published Pages

- The Pages site (`thalesgroup.github.io/agilab`) is deployed from committed
  `docs/html` artifacts in `agilab`, not from source.
- For a mismatch report (old labels still visible online), check:
  1. source in `../thales_agilab/docs/source` is updated,
  2. `../agilab/docs/html` has been regenerated,
  3. a publish/redeploy has been triggered after the commit (push to the branch path
     watched by `docs-publish.yaml`).
- Keep a habit of validating one canonical page after publish:
  - confirm `https://thalesgroup.github.io/agilab/agilab-help.html` and sibling pages
    show the new text.

## Commit Guardrail

- Do not stage or commit `docs/html/**` changes unless:
  1. a corresponding source edit exists under `../thales_agilab/docs/source/**`, and
  2. `docs/html/**` was regenerated from that source.
- If `docs/html/**` was modified by bulk replace/refactor unrelated to docs regeneration,
  revert those generated-file edits before committing.

## Public Docs Constraint

- Public documentation must not mention non-public apps/repositories.
- Keep examples generic and refer to “external apps repository” rather than naming private app modules.

## Build / Validate

- Local Sphinx build (from `agilab` repo root):
  - `uv --preview-features extra-build-dependencies run --project ../thales_agilab --group sphinx python -m sphinx -b html ../thales_agilab/docs/source docs/html`
- Regenerate run-config wrappers after `.idea/runConfigurations` changes:
  - `uv --preview-features extra-build-dependencies run python tools/generate_runconfig_scripts.py`

## Consistency Checklist

- Use consistent naming: “Pages”, “Page bundles”, “Apps-pages” (avoid near-duplicate headings).
- Keep diagrams (SVG) aligned with wording; remove stale labels when sections are removed.
- Ensure math renders via Sphinx math extension; keep equations in `.. math::` blocks when needed.

登录后下载/点赞/收藏 ❤ 4 | ★ 0

agilab-docs

目录结构

SKILL.md

举报内容

提示