sched-fern-openapi-docs

Files (1)

• SKILL.md

SKILL.md (first lines)

# Fern docs and generated files

## Do not hand-edit

- **`fern/openapi.json`** — generated from FastAPI.
- **`fern/docs/assets/combined-config.schema.json`** — generated from config models.
- **`fern/static/python-reference/`** — generated by Fern from `src/scheduler`; ignored and never committed.

## Regenerate after changes

| Change | Command |
|--------|---------|
| `server.py`, API models, routes | `uv run python scripts/export_openapi.py` |
| `CombinedConfig` / config schema | `uv run python scripts/export_config_schema.py` |
| Public APIs or docstrings | `fern docs md generate --local --library scheduler-python` |

Quick decision guide:

- Editing **`src/scheduler/server.py`** -> run `export_openapi.py`
- Editing **`src/scheduler/config.py`** or related config models -> run `export_config_schema.py`
- Editing public package APIs or docstrings under `src/scheduler/` -> run Fern's local library generator

## Authoring

- **Guides / prose**: `fern/docs/pages/` (MDX), navigation in `fern/docs.yml`.
- **Behavior contracts**: keep `concepts/scheduling-rules.mdx` aligned with solver/auditor rules and
  `concepts/diagnostics-auditing.mdx` aligned with diagnostic contracts and search bounds.
- **Site config**: `fern/fern.config.json`, `fern/generators.yml`.
- **Parity enforcement**: `tests/test_documentation_parity.py` discovers config fields, FastAPI routes, façade
  methods, compatibility exports, API environment limits, architecture claims, and canonical examples.

Use `tests/fixtures/minimal_config.json` and `example.json` as the complete validated examples. Do not copy another
full configuration into MDX or README unless a test parses and validates that copy.

## Local preview

Install Node.js 22, Docker, and Fern CLI 5.75.4 (`npm install -g fern-api@5.75.4`). Generate the Python
reference, run `fern check --warnings`, then run `fern docs dev` from the repository root (see CONTRIBUTING).

## CI

Docs deployment is in `.github/workflows/docs.yml`. Keep OpenAPI and JSON Schema artifacts committed; the workflow
generates the ignored Python reference from the checked-out source before validation and publishing.

Cross-skill references:

- [sched-maintain-scripts](../sched-maintain-scripts/SKILL.md) for script maintenance details
- [sched-fastapi-server](../sched-fastapi-server/SKILL.md) for route/model change workflow

From mucsci/Scheduler, MIT.

More from mucsci/Scheduler