97 lines
3.4 KiB
Markdown
97 lines
3.4 KiB
Markdown
# Шаблон страницы ресурса (документация)
|
|
|
|
> Актуально на 2026-07-18. Применять ко всем сервисам.
|
|
|
|
## Структура страницы
|
|
|
|
```markdown
|
|
# Resource nubes_SERVICE · Service ID: N · Service Name: DISPLAY_NAME
|
|
|
|
**Manual** · [Create params](SERVICE_params_create.md) · [Modify params](SERVICE_params_modify.md) · [Output params](SERVICE_outputs.md) · [Operations](SERVICE_ops.md) · [Example](SERVICE_example.md)
|
|
```
|
|
|
|
**Правила:**
|
|
- Заголовок — ОДНА строка, разделители `·`
|
|
- Табы — активная вкладка `**жирным**`, разделители `·`
|
|
- SERVICE = имя ресурса из YAML (`spec.Name`), DISPLAY_NAME = `spec.ServiceDisplayName`
|
|
|
|
## MAN
|
|
|
|
```markdown
|
|
## MAN
|
|
|
|
<div class="man-content" markdown="1">
|
|
|
|
# Инструкция ...
|
|
|
|
...
|
|
|
|
</div>
|
|
```
|
|
|
|
- Весь MAN-контент внутри `<div class="man-content" markdown="1">`
|
|
- Шрифт: 0.62rem (CSS: `.md-typeset .man-content`)
|
|
- Требует `md_in_html` в `mkdocs.yml`
|
|
|
|
## Таблицы параметров
|
|
|
|
### Основная (Create/Modify params)
|
|
|
|
5 колонок (ID скрыт): Code | Type | (Default) | Description | Constraints
|
|
|
|
```html
|
|
<table class="resource-table resource-table-compact resource-table-required">
|
|
<thead><tr><th>ID</th><th>Code</th><th>Type</th><th>Description</th><th>Constraints</th></tr></thead>
|
|
```
|
|
|
|
### Nested (map-fixed/array-map-fixed)
|
|
|
|
7 колонок: ID | Code | Type | Required | Default | Description | Constraints
|
|
ID скрыт, Required — ★ для непустых ячеек.
|
|
|
|
```html
|
|
<table class="resource-table resource-table-compact resource-table-nested">
|
|
<thead><tr><th>ID</th><th>Code</th><th>Type</th><th>Required</th><th>Default</th><th>Description</th><th>Constraints</th></tr></thead>
|
|
```
|
|
|
|
## CSS (глобальный, `docs/30_registry/assets/extra.css`)
|
|
|
|
| Элемент | Правило |
|
|
|---|---|
|
|
| ID колонка | `display: none` |
|
|
| Required | `td:not(:empty)::before { content: "★"; color: #e74c3c; }` |
|
|
| Code | 25% (main), 19% (nested), жирный |
|
|
| Type | 5%, 0.63rem |
|
|
| Default | 6% (nested), синий `#2c6f8c` |
|
|
| Description | line-clamp(2) на `td`, мелкий серый |
|
|
| Constraints | monospace 0.62rem, `word-break: break-word` |
|
|
| thead | sticky, nowrap, 0.72rem |
|
|
| tbody | zebra `tr:nth-child(even) { #fafafa }` |
|
|
| MAN | `.man-content { font-size: 0.62rem; }` |
|
|
| Заголовок h1 | 0.77rem |
|
|
| Табы p | 0.65rem |
|
|
| **Важно** | Все селекторы с префиксом `.md-typeset` |
|
|
|
|
## mkdocs.yml
|
|
|
|
Добавить в `markdown_extensions`:
|
|
```yaml
|
|
markdown_extensions:
|
|
- md_in_html
|
|
```
|
|
|
|
## Генератор (`TOOLS/docs-generator/internal/writers/writers.go`)
|
|
|
|
Функции для правки:
|
|
- `buildHeader()` — заголовок + табы (одна строка, `·`, активная жирным)
|
|
- `buildManualPage()` — MAN в `<div class="man-content" markdown="1">`
|
|
- `renderParamTable()` — классы таблиц
|
|
- `renderModifyTable()` — модифай без лишних колонок если пустые
|
|
|
|
## Порядок генерации
|
|
|
|
1. Правим `writers.go`
|
|
2. `cd TOOLS/docs-generator && go build -o ../bin/docs-generator .`
|
|
3. `./02_generate_resources_and_docs_v2.sh --profile TOOLS/config/test`
|
|
4. `mkdocs build` или `./04_build_and_publish_docs.sh`
|