elastic / elastic/ai-github-actions

[framework-best-practices] Use MkDocs File.generated for generated workflow docs

Open
#1,275 0 comments 0 reactions 0 assignees View on GitHub
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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.