[OPS] Индекс документации: 630 файлов в ops/INDEX.md — навигация по 95 каталогам с заголовками и датами, автообновление ежедневно (docs-index 06:50), попадает в RAG. Раньше индекс описывал 6 документов из 630
This commit is contained in:
1 parent
0d7122a796
commit
8da1da3e9d
3 files changed
+1173
No files matched your search
+1031
File diff suppressed because it is too large.
Load diff
@@ -0,0 +1,57 @@
|
||||
# Индекс документации (10.11.2026)
|
||||
|
||||
## Проблема
|
||||
|
||||
**630 markdown-файлов в `ops/` и 946 по репозиторию.** Индекс `docs/README.md`
|
||||
описывал 6 документов. Найти нужное можно было только `grep`'ом.
|
||||
|
||||
Документация — сильная сторона проекта (фиксирует ловушки), но без навигации
|
||||
она превращается в архив.
|
||||
|
||||
## Что сделано
|
||||
|
||||
### `ops/scripts/build_docs_index.py`
|
||||
|
||||
Собирает все `.md` из `ops/`, берёт заголовок, размер и дату изменения,
|
||||
группирует по каталогам. Пишет `ops/INDEX.md`.
|
||||
|
||||
```
|
||||
файлов: 630
|
||||
каталогов: 95
|
||||
размер индекса: 76 КБ
|
||||
```
|
||||
|
||||
Свежие файлы — сверху, у каждого каталога счётчик «за неделю»:
|
||||
|
||||
```
|
||||
## ops — 45 файлов (29 за неделю)
|
||||
|
||||
| Документ | О чём | Изменён |
|
||||
|---|---|---|
|
||||
| AUDIT-LOCAL-RENDER-2026-11-09.md | Локальные рендеры комнат | 09.11 |
|
||||
| SERVICE-STANDARD.md | Единый стандарт сервиса | 07.11 |
|
||||
| NOTIFICATIONS.md | Политика уведомлений (анти-спам) | 06.11 |
|
||||
```
|
||||
|
||||
### Автообновление
|
||||
|
||||
Задание Hermes **`docs-index`** ежедневно в 06:50. Индекс не устареет.
|
||||
|
||||
### Индекс попадает в RAG
|
||||
|
||||
`ops/INDEX.md` лежит в индексируемом каталоге — значит секретарь сможет
|
||||
найти документ по описанию, а не только по содержимому.
|
||||
|
||||
## Итог
|
||||
|
||||
| Было | Стало |
|
||||
|---|---|
|
||||
| 630 файлов без навигации | индекс по каталогам с описаниями |
|
||||
| ручной `grep` | таблица «документ — о чём — когда» |
|
||||
| `docs/README.md` (6 ссылок) | `ops/INDEX.md` (630 файлов) |
|
||||
|
||||
## Осталось
|
||||
|
||||
1. `docs/README.md` — обновить, чтобы вело на `ops/INDEX.md`.
|
||||
2. Часть документов старше месяца — кандидаты на архивацию (44 файла).
|
||||
3. Разделить «живые» документы и «историю спринтов» по папкам.
|
||||
Executable
+85
@@ -0,0 +1,85 @@
|
||||
#!/usr/bin/env python3
|
||||
"""Индекс документации: 946 файлов → одна навигация.
|
||||
|
||||
Для каждого .md собирает: первую строку-заголовок, размер, дату изменения.
|
||||
Группирует по каталогу. Пишет ops/INDEX.md.
|
||||
|
||||
Запуск: python3 ops/scripts/build_docs_index.py
|
||||
"""
|
||||
import datetime
|
||||
import os
|
||||
import re
|
||||
|
||||
ROOT = "/root/buryan-infra"
|
||||
OUT = os.path.join(ROOT, "ops/INDEX.md")
|
||||
SKIP_DIRS = {".git", "node_modules", "__pycache__", "rag", ".venv"}
|
||||
|
||||
|
||||
def title_of(path):
|
||||
try:
|
||||
with open(path, encoding="utf-8", errors="ignore") as f:
|
||||
for line in f:
|
||||
s = line.strip()
|
||||
if s.startswith("#"):
|
||||
return re.sub(r"^#+\s*", "", s)[:90]
|
||||
if s and not s.startswith(("---", "```")):
|
||||
return s[:90]
|
||||
except Exception:
|
||||
pass
|
||||
return ""
|
||||
|
||||
|
||||
def main():
|
||||
groups = {}
|
||||
total = 0
|
||||
for dirpath, dirnames, filenames in os.walk(os.path.join(ROOT, "ops")):
|
||||
dirnames[:] = [d for d in dirnames if d not in SKIP_DIRS]
|
||||
for fn in filenames:
|
||||
if not fn.endswith(".md"):
|
||||
continue
|
||||
p = os.path.join(dirpath, fn)
|
||||
rel = os.path.relpath(p, ROOT)
|
||||
if rel == "ops/INDEX.md":
|
||||
continue
|
||||
try:
|
||||
st = os.stat(p)
|
||||
except OSError:
|
||||
continue
|
||||
groups.setdefault(os.path.relpath(dirpath, ROOT), []).append({
|
||||
"rel": rel,
|
||||
"title": title_of(p),
|
||||
"size": st.st_size,
|
||||
"mtime": st.st_mtime,
|
||||
})
|
||||
total += 1
|
||||
|
||||
lines = ["# Индекс документации",
|
||||
"",
|
||||
"Сгенерировано: %s · файлов: **%d** · генератор: `ops/scripts/build_docs_index.py`"
|
||||
% (datetime.datetime.now().strftime("%Y-%m-%d %H:%M"), total),
|
||||
"",
|
||||
"Навигация по каталогам. Свежие файлы — сверху."]
|
||||
for d in sorted(groups):
|
||||
items = sorted(groups[d], key=lambda x: -x["mtime"])
|
||||
fresh = sum(1 for i in items if i["mtime"] > datetime.datetime.now().timestamp() - 7 * 86400)
|
||||
lines.append("")
|
||||
lines.append("## %s — %d файлов (%d за неделю)" % (d, len(items), fresh))
|
||||
lines.append("")
|
||||
lines.append("| Документ | О чём | Изменён |")
|
||||
lines.append("|---|---|---|")
|
||||
for i in items[:40]:
|
||||
date = datetime.datetime.fromtimestamp(i["mtime"]).strftime("%d.%m")
|
||||
name = i["rel"].split("/")[-1]
|
||||
lines.append("| [%s](%s) | %s | %s |"
|
||||
% (name, i["rel"], (i["title"] or "—").replace("|", "/")[:70], date))
|
||||
if len(items) > 40:
|
||||
lines.append("| … ещё %d | | |" % (len(items) - 40))
|
||||
|
||||
open(OUT, "w", encoding="utf-8").write("\n".join(lines) + "\n")
|
||||
print("записано:", OUT)
|
||||
print("файлов:", total, "| каталогов:", len(groups))
|
||||
print("размер индекса:", os.path.getsize(OUT) // 1024, "КБ")
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
main()
|
||||
Reference in new issue
Block a user