elastic / elastic/ai-github-actions
[framework-best-practices] Use MkDocs File.generated for generated workflow docs
- Dominant language
- Python
- Stars
- 11
- Forks
- 16
- Avg merge
- 22h 9m
- Merged PRs (30d)
- 31
Description
## Finding
`docs/hooks.py` manually materializes generated MkDocs pages into a temp directory and appends them as regular `File` objects, even though the project depends on `mkdocs>=1.6.0,<2.0` and MkDocs 1.6 provides in-memory generated files.
## Evidence
- `pyproject.toml:7` pins `mkdocs>=1.6.0,<2.0`.
- `docs/hooks.py:9-12` imports `atexit`, `shutil`, and `tempfile` solely for generated-page temp-file lifecycle.
- `docs/hooks.py:17` stores `_tmp_dir` as module-level state.
- `docs/hooks.py:117-123` creates and later cleans a temp directory with `tempfile.mkdtemp(...)` and `atexit.register(...)`.
- `docs/hooks.py:139-149` writes each generated page to that temp directory, then appends `mkdocs.structure.files.File(...)` with `src_dir=_tmp_dir`.
## Library feature
MkDocs 1.6 added `mkdocs.structure.files.File.generated(config, src_uri, content=...)`, which creates a virtual generated file backed by in-memory content and sets generated-file metadata without needing a physical source file.
Docs: (www.mkdocs.org/redacted)
## What is wrong
The hook duplicates MkDocs' generated-file support by managing a temp directory, cleanup callbacks, and module-level state itself. In MkDocs 1.6's API, generated files are expected to use `src_dir=None` with in-memory `content`; the current code instead makes generated pages look like physical source files under a temp `src_dir`.
## Impact
This keeps unnecessary global lifecycle coupling between `on_pre_build` and `on_files`, writes generated docs to the filesystem on every build/rebuild, and relies on process-exit cleanup. In `mkdocs serve`, repeated rebuilds register repeated cleanup callbacks and create/remove temp dirs even though MkDocs can keep the content in memory.
## Suggested fix
Replace the temp-file path with MkDocs' generated file API:
```python
files.append(File.generated(config, rel_path, content=page_content))
```
Then remove `_tmp_dir`, `on_pre_build`, and the `atexit`/`shutil`/`tempfile` imports. Add or update a focused docs hook test to assert `on_files` appends generated workflow pages without requiring temp-dir setup.
---
[What is this?](https://ela.st/github-ai-tools) | [From workflow: Trigger Framework Best Practices](https://github.com/elastic/ai-github-actions/actions/runs/27555715854)
Give us feedback! React with 🚀 if perfect, 👍 if helpful, 👎 if not.
Contributor guide
Assessment
This issue has not been assessed yet.