HTML 문서
읽는 코드가 아니라 사람이 보는 데이터 문서를 생성 합니다. 어떤 테이블이 있고, 어떤 필드가 무슨 타입이며, 실제 값이 무엇이고, 그것이 시트의 어느 셀에서 왔는지.
생성되는 것
<Path>/
index.html 개요 — 통계 · 컬럼 분포 · 최대 테이블 · 원본 워크북
tables.html 테이블 목록 — 행 수 · 컬럼 수 · 시트
fields.html 전체 컬럼 색인 — 이름 · 소속 테이블 · 타입 · 측 · 존재 여부
enums.html enum 목록 — 레이블 수 · 사용 컬럼 수 · 시트
structs.html 구조체 목록 — 공통 멤버 수 · 변종 수 · 사용 그룹 수
constantsets.html 상수 세트 목록과 각 세트의 상수
references.html 참조 그래프 — 어느 테이블이 어느 테이블을 가리키는지
tables/<table>.html 테이블당 하나 — 스키마 · 데이터 · 피참조 목록
enums/<enum>.html enum당 하나 — 레이블 · 사용처
structs/<name>.html 구조체당 하나 — 공통 멤버 · 변종마다의 멤버 · 사용 그룹
테이블당 페이지 하나입니다. 예전에는 전부 한 페이지였고, 최대 테이블이 10만 행인 워크북에서 그 페이지가 37 MB였습니다. 그러면 그 테이블 하나 때문에 나머지를 볼 수 없습니다.
recipe 설정
"Targets": [
{
"Type": "html",
"Path": "docs/data",
"Sweep": true,
"TargetSide": "cs",
"MaxRowsPerTable": 1000
}
]
| 설정 | 기본값 | 무엇 |
|---|---|---|
Path | — | 출력 디렉터리. 비어 있으면 이 항목은 동작하지 않습니다 |
Sweep | true | 이번 실행이 쓰지 않은 생성 파일을 지웁니다. 이 도구의 헤더가 붙은 파일만 대상입니다 |
TargetSide | "cs" | "c"·"s"로 두면 그쪽에 가는 엔티티와 필드만 문서에 나옵니다 |
MaxRowsPerTable | 1000 | 테이블 페이지가 보여주는 행 수. 0은 무제한 |
MaxRowsPerTable이 적용되면 표 위에 「전체 몇 행 중 몇 행」이 적힙니다. 말 없이 자르면 전량을
본 것으로 읽히기 때문입니다.
규모가 큰 프로젝트에서는 이 값을 낮추십시오. 산출물 크기는 행 수 × 컬럼 수입니다 — 테이블 459개·행 57만 개·컬럼 1만 개인 워크북 묶음을 기본값 1,000행으로 내면 페이지 465개에 239 MB이고, 중간값은 118 KB인데 가장 넓은 테이블 하나가 24 MB를 차지합니다.
페이지가 제시하는 것
페이지 이동
모든 페이지가 상단 바(개요 · 테이블 · 컬럼 · 참조 · enum · 구조체 · 상수 세트)와 브레드크럼을 가지고, 옆에 같은 종류의 전체 목록이 있습니다. 그 목록에는 즉시 필터가 붙어 있습니다. 페이지 하나를 그대로 전달받아도 이동이 됩니다 — 목록이 그 페이지 안에 있기 때문입니다.
종류마다 목록 페이지가 있고(tables.html · fields.html · enums.html · structs.html · constantsets.html)
정렬과 필터가 됩니다. 기본 정렬은 이름 오름차순이고 대소문자를 가리지 않습니다. 개요의
카드가 각 목록으로 들어가는 입구입니다.
테마
상단 바 오른쪽 버튼이 시스템 → 밝게 → 어둡게를 순환하고, 선택은 브라우저의 localStorage에
남습니다. 페이지가 그려지기 전에 적용되므로 이동할 때 다른 테마가 번쩍이지 않습니다. 아무것도
고르지 않으면 운영체제 설정을 따릅니다.
전체 윤곽
index.html이 테이블·행·컬럼·enum·레이블·구조체·변종·상수 세트·상수·셀 개수를 먼저 제시하고,
그 아래에 컬럼의 타입별· 역할별(참조·배열·옵셔널·레코드 멤버·text·asset·집합과 맵·구조체
멤버)·측별 분포와 최대 테이블 목록이 나옵니다. 수치는 게이트가 페이지들과 대조합니다.
타입별 분포는 시트가 적은 이름으로 셉니다. 값의 타입으로 세면 bitset이 bigint로,
vec3f가 float 3개로 집계되어 그 표가 모델에 없는 타입을 열거하게 됩니다.
enum 미리보기
enum 값 칸에 커서를 올리면 그 enum 전체가 카드로 나타나고 해당 레이블이 표시됩니다.
이동하지 않고 확인할 수 있습니다. enum 정의는 페이지마다 한 번만 실려 있고 칸은 이름만 들고
있습니다 — 칸마다 title에 담으면 10만 행 테이블에서 enum 전체가 10만 번 반복됩니다.
상수 세트
constantsets.html이 세트의 목록과 각 세트의 상수를 한 페이지에 냅니다 — 세트는 수십 개 상수를
가지고 테이블은 수만 행을 가지므로 분량이 다릅니다.
배열 상수는 원소로 나옵니다. ["bronze", "silver", "gold"]이고, enum 배열이면 원소마다
레이블과 링크와 미리보기 카드가 붙습니다.
원본과 참조
- 원본으로 가는 링크. 각 테이블 제목이 그 엔티티가 정의된 시트의 셀을 가리킵니다. 구글 스프레드시트라면 실제로 열리는 URL이고, 로컬 파일이면 위치가 글로 적힙니다.
- 참조는 양방향입니다. 타입 칸이
→ ItemCategory로 그 테이블의 페이지를 가리키고, 테이블 페이지는 자기를 가리키는 컬럼 목록을 함께 냅니다. 값 칸은 저장된 인덱스입니다 — 문서가 기록하는 것은 저장된 것이기 때문입니다. - 참조 값에 커서를 올리면 그 행이 미리 보입니다. 대상 테이블의 앞 컬럼 다섯 개가 패널로 나오므로, 「이 키가 무엇인가」는 이동하지 않고 답이 됩니다.
- 참조 값을 누르면 그 행으로 갑니다. 대상이 여러 개인 컬럼은 후보 테이블이 함께 나오고 골라서 이동합니다. 행 상한 때문에 그 페이지에 그 행이 없으면 페이지까지 갑니다.
- 참조 그래프.
references.html은 규모에 따라 다르게 보여줍니다. 참조가 80개까지면 전체를 층으로 그리고(왼쪽에서 오른쪽, 자기 참조는 고리) 끌어서 이동·휠로 확대하며, 테이블을 누르면 그 테이블의 이웃만 남습니다. 그보다 크면 전체는 그리지 않습니다 — 창에 맞춘 수백 개는 읽히지 않으므로, 가장 연결이 많은 테이블의 이웃으로 열리고 「연결 정도」 표에서 다른 테이블을 고르며, 이웃을 눌러 걸어갑니다. 층마다 테이블이 몇 개인지도 함께 냅니다. - 그림 안의 테이블을 눌러도 됩니다. 눌린 포인터를 그림이 붙잡으면 뒤따르는 클릭이 그림에게 가므로, 붙잡는 것을 끌기가 시작될 때로 옮겼습니다. 끌기가 필요한 것이 붙잡기이고, 그것은 문턱이 판별합니다.
- 한 테이블의 이웃에서 자기 참조는 고리입니다. 이웃으로 두면 고른 테이블이 왼쪽과 오른쪽과 가운데에 3번 그려지고, 좌우의 사본에는 「이동」 화살표가 붙어 이미 보고 있는 그림으로 갔습니다. 전체 그래프가 자기 참조를 그리는 방법과 같아졌습니다.
enum의 다른 표기
레이블에 별칭이 있으면 enum 페이지에 「다른 표기」 열이 나옵니다. 별칭은 셀이 그 이름으로 적어도 같은 레이블로 해석되게 하는 것이고 내보내는 데이터에는 정수만 남으므로, 이 페이지가 그것을 읽을 수 있는 유일한 자리입니다.
- enum 페이지는 사용처를 냅니다. 그 enum을 타입으로 쓰는 컬럼 목록입니다.
- 컬럼 색인.
fields.html에서 이름으로 정렬하면 같은 컬럼 이름이 붙어 나오므로 타입이나 측이 어긋난 곳이 보입니다.
표 도구
행 필터와 컬럼 정렬(헤더 클릭)이 있습니다.
정렬은 5,000행까지 켜집니다. 그 위에서는 브라우저에서 도는 정렬이 멈춘 것처럼 보입니다.
문자열은 ""로 감싸고 편집기처럼 색을 달리하며, 값이 없는 칸은 기울인 null입니다.
빈 문자열 ""와 빈 배열 []은 값이므로 그대로 둡니다.
배열은 [1, 2, 3]처럼 대괄호로 감싸 원소 개수를 옆에 냅니다.
길면 잘리고 커서를 올리면 전체가 나옵니다.
논리값은 참이 초록 ✔, 거짓이 붉은 ✘입니다. 모양이 같고 색만 다르면 거짓만 이어진 컬럼이
전부 체크된 것처럼 읽힙니다 — 모양이 먼저이고 색이 그다음입니다. 상수 세트도 같은 표기입니다
— 한 문서에서 예·아니오를 두 가지로 적으면 읽는 사람이 문서를 먼저 익혀야 합니다.
설명의 강조
설명 칸에 적은 **굵게** · *기울임* · `코드` 를 그대로 냅니다. 먼저 이스케이프하고
그다음에 태그를 붙입니다 — 셀이 가진 것은 아무것도 마크업으로 페이지에 닿지 않고, 붙는 태그는
이 도구의 것입니다. 그 셋뿐이고 블록도 목록도 링크도 없습니다. 설명은 셀 하나의 한 문장입니다.
툴팁은 예외입니다 — 어트리뷰트는 마크업을 글자 그대로 냅니다.
긴 값은 자릅니다. 대사처럼 긴 문자열이 컬럼 하나의 폭을 화면 밖까지 밀어내지 않도록 …로
자르고, 커서를 올리면 전체가 패널로 나오고 누르면 그 자리에서 펼쳐집니다. 자르는 것은
표시뿐이므로 필터와 복사는 전체 값을 봅니다.
참조 컬럼의 타입은 int? → AdvSpcEffTermsGroup[]처럼 키의 타입 다음에 가리키는 테이블로
나옵니다. 필수 여부는 타입의 ?입니다. double?이면 그 컬럼은 값이 없을 수 있고, 레코드는
멤버마다 붙습니다. 원소가 없을 수 있으면 괄호 안쪽에 붙어 int?[]입니다.
인덱스는 타입 뒤에 🔑가 붙습니다. 시트가 키를 지정했으면 그 컬럼에, 여러 컬럼을 묶은 키면
그 전부에 붙고, 툴팁에 기본 인덱스인지 값만 유일한 인덱스인지 적힙니다. 행 앵커도 선언된
키에서 만듭니다 — 첫 컬럼에서 만들던 때는 X·Y·Z로 키를 이룬 테이블에서 같은 id가
여러 번 나왔고, 그 앵커로 오는 링크는 먼저 나온 행에 닿았습니다.
헤더 띠 전체와 첫 컬럼이 고정됩니다. 표가 하나뿐인 페이지(테이블·컬럼·enum·테이블
목록)에서는 창이 틀이 되고 표만 스크롤되므로, 세로로 내려도 컬럼 이름이 남고 가로로 밀어도 키
컬럼이 남습니다. 고정된 칸에는 z-index가 있어야 합니다 — 위치만 잡힌 요소는 문서 순서로
그려지므로, 없으면 오른쪽 칸들이 그 위에 그려져 두 글자가 겹칩니다.
컬럼 설명이 하나도 없는 시트에서는 설명 행을 그리지 않습니다. 목록 페이지의 Description 열도 같습니다.
시트가 적은 제약은 헤더 툴팁에 있습니다 — 최소·최대·최소 길이·최대 길이·패턴·빈 값 금지·허용값 개수·레코드 안 필수. 선언된 범위를 벗어난 값이 이 페이지에서 찾는 것이기 때문입니다.
깨진 참조는 컬럼 단위로
참조 컬럼의 타입 뒤에 ⚠ 25가 붙으면 그 컬럼의 키 25개가 대상 테이블에 없다는 뜻입니다. 커서를
올리면 어느 테이블에 몇 개인지 나옵니다. 값마다 붙는 ?는 그 한 칸의 이야기이고, 이것은 컬럼
전체의 이야기입니다 — 컬럼 페이지에서 정렬하면 깨진 참조가 많은 컬럼이 먼저 옵니다.
선언 위치는 워크북과 시트
목록의 「선언 위치」 열과 각 페이지의 머리줄이 퀘스트.xlsb · Achievement처럼 나옵니다.
워크북에 커서를 올리면 경로가 나옵니다.
컬럼은 페이지가 그리는 단위
개요·목록·테이블 페이지·색인이 세는 「컬럼」은 엔트리입니다 — 접힌 배열과 레코드는 컬럼 하나입니다. 워크북의 칸 수는 「시트 컬럼」이라는 이름으로 옆에 나옵니다.
레코드는 객체로
레코드 배열은 시트에서 원소마다 멤버마다 한 컬럼으로 적히지만, 페이지에서는 컬럼 하나입니다
— 셀은 [(0, 1077, 421), (0, 1122, 196)] ×2처럼 튜플이고, 커서를 올리면 멤버 이름이 붙은
들여쓴 형태가 나옵니다. 눌러 펼치면 셀 안에서도 원소 하나가 한 줄씩 보입니다.
시트의 형태
레코드 그룹(Group.Member) · 다중 중첩(Star1.Position.X) · 옵셔널 필드 · 옵셔널 원소를 모두
문서화합니다. 접힌 엔트리 하나가 컬럼 하나이고, 레코드는 (0, 1077, 421)처럼 튜플로 나옵니다 —
커서를 올리면 멤버 이름이 붙은 들여쓴 형태가 나옵니다.
컬럼 이름의 첫 단계까지가 헤딩입니다. 시트는 부분마다 한 칸을 적으므로
(Pos.X · Bag.Tags · statBonus[0]["Id"]) 그 뒤는 엔트리가 아니라 부분의 이름입니다.
번호가 붙은 단계(Slot1)는 원소이므로 모델의 이름(Slot)을 씁니다.
선언된 타입은 선언된 대로
이 타깃이 내는 것은 「시트가 무엇이라고 적었는가」입니다. 코어는 여러 타입을 파싱이 끝나는 지점에서 더 단순한 것으로 접습니다 — 와이어와 언어별 생성기를 그 기능에서 떼어놓는 장치입니다. 접힌 결과는 참인 서술이지만 이 타깃이 낼 것이 아니므로, 이 페이지들은 접기 전의 표기를 냅니다.
| 시트가 적은 것 | 코어가 접는 결과 | 페이지가 내는 것 |
|---|---|---|
vec3f · quat · color32 | 컴포넌트마다 컬럼 하나 | vec3f, 셀은 (1.5, -2.5, 0) |
color · color32 | 같음 | 색 견본과 튜플. #3399CC는 툴팁 |
bitset | bigint | bitset, 셀은 0x1F. 툴팁에 비트 수와 10진수 |
set<T> | 배열 컬럼 하나 | set<T>, 셀은 {"new", "sale"} |
map<K,V> | 길이가 같은 배열 둘 | map<K,V>, 셀은 {10: 100, 11: 120} |
int?[] | int[]와 같은 컬럼 | int?[] |
구조체($type) | 변종 전부의 합집합 | 아래 항목 |
구조체
structs.html이 선언된 추상 타입의 목록이고, 타입마다 페이지가 하나 있습니다. 그 페이지는
공통 멤버(모든 변종이 가지므로 옵셔널이 아닌 컬럼)와 변종마다의 멤버를 나눠서 냅니다.
합집합 하나로 그리면 그 구분이 없어지고, 선언에 적힌 것이 그 구분입니다.
테이블 페이 지에서는 이렇게 나옵니다.
$type칸은 변종의 이름입니다. 파일이 싣는 것은 번호이지만 시트에 적힌 것은 이름이고, 누르면 그 변종의 선언으로 갑니다. 어느 변종도 아닌 번호는 붉게 나옵니다.- 타입 칸의
$type은struct.Effect로 그 구조체를 가리킵니다. 그 옆의 옵셔널 멤버마다 어느 변종이 선언하는지가 붙습니다 —Damage: int? DamageEffect. - 그 행의 변종에 없는 멤버는
—입니다. 기울인null은 「값이 없다」이고 이것은 「이 행이 가진 타입의 일부가 아니다」입니다. 둘은 다른 사실이고, 이 페이지가 있는 이유가 그 구분입니다. 구조체 그룹이 있는 표에는 그 둘을 적은 줄이 표 위에 있습니다 — 대시와 기울인null은 듣지 않은 사람에게 너무 조금 다릅니다.
구조체 페이지의 구성은 관계를 그립니다. 공통 멤버는 패널이고 변종은 그 아래로 내려가는 레일에
붙은 카드입니다. 처음에는 h2 하나와 h3 여러 개였는데, 변종이 41개인 타입에서 그것은 같은
굵기의 제목이 늘어선 벽이고 무엇이 무엇에 매달렸는지 드러나지 않습니다. 변종이 6개를 넘으면
이름들이 칩 한 줄로 위에 함께 나옵니다.
구조체와 변종의 /// 설명도 나옵니다. 멤버의 설명은 그것을 담은 컬럼을 타고 오지만, 타입
자신의 설명은 어느 컬럼도 아닌 것을 서술하므로 모델이 따로 들고 있어야 합니다.
주의사항
네트워크에 아무것도 요청하지 않습니다. 스타일·파비콘·스크립트가 전부 인라인입니다. 이 도구는 폐쇄망에서 도는 것을 전제하고, 예전에는 CDN의 부트스트랩을 참조하다가 그 CDN이 문을 닫아 한동안 스타일 없이 렌더되고 있었습니다. 지금은 페이지를 파일 하나로 옮겨도 그대로 보입니다.
본문의 구글 스프레드시트 링크는 다릅니다 — 그건 내용이고, 따라갈지는 읽는 사람의 선택입니다.
페이지의 문구는 한국어입니다. 시트에서 온 이름과 설명은 그대로이고, 타입 이름과 측
표기(c·s·cs)는 recipe의 어휘라 번역하지 않습니다.
아이콘은 인라인 SVG입니다. 이모지가 아닌 것은 이모지가 폰트의 해석이라 플랫폼마다 다른 그림이 되기 때문입니다. 심볼은 페이지마다 한 벌만 실립니다.
선언이 없으면 없다고 적습니다. enum이나 구조체가 하나도 없는 모델이면 그 목록 페이지에 빈 표가 아니라 「선언된 것이 없습니다」가 나옵니다.
트러블슈팅
| 증상 | 원인과 조치 |
|---|---|
| enum 페이지에 「다른 표기」 열이 없음 | 그 enum의 레이블에 별칭이 없습니다. 별칭은 tabbit 레이아웃의 enum 블록이 alias 열로 읽습니다 |
| 스타일이 없음 | 생성물은 스타일을 인라인으로 담습니다. 페이 지를 손으로 편집했는지 확인하세요 |
| 링크가 아무 데도 안 감 | 생성물의 모든 내부 링크는 존재하는 페이지와 앵커를 가리키도록 검사됩니다. 재현되면 버그입니다 |
| 테이블이 안 보임 | TargetSide가 걸러냈을 수 있습니다 |
| 행이 일부만 보임 | MaxRowsPerTable입니다. 표 위에 몇 행 중 몇 행인지 적혀 있고, 0으로 두면 전량이 나옵니다 |
| 정렬이 안 됨 | 5,000행을 넘는 표에서는 켜지지 않습니다 |
| 필터·enum 카드·테마 버튼이 동작하지 않음 | 페이지의 스크립트가 하는 일입니다. 스크립트를 막는 환경에서도 값과 링크는 그대로 보이고, 테마는 운영체제 설정을 따릅니다 |
| 설명 열이 안 보임 | 그 종류에 설명이 하나도 없으면 열을 그리지 않습니다 |
구조체 목록이 비어 있음 | 시트가 추상 타입을 선언하지 않았습니다. 목록 페이지는 모델마다 있고, 없으면 없다고 적습니다 |
셀에 —가 있음 | 그 행의 변종이 선언하지 않는 멤버입니다. 값이 없는 것(기울인 null)과 다릅니다 |