docs/tools — 프로그램 문서 추출 (PLAN 478)
- 한 명령 =
./venv/Scripts/python.exe docs/tools/extract_all.py→docs/_data/(git 밖). - 처음 한 번 =
npm --prefix docs/tools install(ts-morph · 루트 npm install 금지). - 범위 =
scope.json한 곳 —roots폴더 전부 + 거기서 import 로 닿는follow폴더 파일(파이썬은 계산 등록부가 짚는follow파일도).
만드는 것
| 파일 | 내용 |
|---|---|
functions.json |
함수 [{id, lang, file, line, name, kind, exported, doc, params, returns, calls, called_by}] · 파이썬 라우트 함수 = routes · 다시 내보내기 = target |
session_keys.json |
세션 칸 [{key, reads, writes}] |
api.json |
서버 주소 [{method, path, handler, callers}] |
api_unmatched.json |
짝 없는 TS 주소 글자 · 부르는 TS 없는 범위 주소 |
registry.json |
계산 등록부(design_calc_registry*.ts) 항목 그대로 |
raw/ |
중간 결과(TS 함수 · 파이썬 함수 · TS 주소 글자) |
세는 규칙
- id =
ts:<파일>#<이름>·py:<파일>#<이름>· 이름 = 감싼 클래스 · 함수 · 변수 이름을 점으로 이음(Class.method·outer.inner·obj.prop) · 같은 id 가 또 나오면 소스 차례대로~2·~3. - TS 에서 세는 것: 몸통 있는
function(이름 없는 기본 export =default) · 변수 · 속성 · 클래스 칸에 담긴 화살표 · 함수 식 · 클래스 메서드 · 접근자 · 생성자(constructor) · 함수를 가리키는 다시 내보내기(export { a as b } from·export default foo→ kindreexport). - TS 에서 안 세는 것: 이름 없는 콜백(그 안의 부름은 감싼 함수 몫) · 오버로드 선언 · 타입 ·
export * from. - 파이썬에서 세는 것:
def·async def전부(메서드 · 안쪽 함수 포함). 안 세는 것:lambda(그 안의 부름은 감싼 함수 몫). - kind =
function·arrow·method·reexport. - exported = TS 맨 위
export· 내보낸 클래스의 private 아닌 메서드 · 파이썬 맨 위(또는 맨 위 클래스) 의_로 시작하지 않는 이름. - 기성 도구(TypeDoc · griffe)와 맞댈 때 =
exported가 참인 것만 · 파일 · 이름 · 줄 · kind 로. - calls = 범위 안 함수만(범위 밖 · 이름 못 푸는 부름은 뺌).
- doc = JSDoc · docstring 의 첫 줄(
@태그 줄 뺌) · 없으면 null. - 세션 칸 =
b_page_state의readState·readStateRaw·readByKey(읽기) ·writeState·writeStateRaw·writeByKey·clearState(쓰기) ·sessionStorage.getItem(읽기) ·setItem·removeItem(쓰기) · 열쇠를 글자로 못 풀면{식}. - 서버 주소 = 함수 안
/로 시작하는 글자 · 템플릿(${…}={}· 앞/api뗌 ·?뒤 뗌) → 경로 칸끼리 짝(서버{x}· TS{}= 아무 칸 · 어긋남 적은 것) · 메서드 = 옆 옵션의method(변수 · 펼침 = 아무 메서드 · 옵션에 없으면 GET). - api.json 범위 = 범위 파이썬이 받거나 범위 TS 가 부르는 주소.
- 모든 목록은 정렬 고정 — 다시 돌려도 같은 결과.
사이트 (478-2)
- 처음 한 번 =
./venv/Scripts/python.exe -m pip install -r docs/tools/requirements.txt(mkdocs · Material · mkdocstrings). - 원고 =
./venv/Scripts/python.exe docs/tools/build.py→docs/_build/src·--site=mkdocs build --strict까지 ·--stamp= 손글 지문을 지금 함수 목록으로. - 띄우기 =
cd docs && ../venv/Scripts/python.exe -m mkdocs serve -a 127.0.0.1:8090 - 묶음 규칙 =
groups.yml(계산 등록부 id · 파일 이름 무늬) · 손글 =docs/guide/<페이지>/page.md·groups/<묶음>.md· 손글 안[[함수]]·[[파일#함수]]= 함수 칸 링크. - 함수 화면 = TS
TypeDoc(HTML) · 파이썬mkdocstrings(griffe) — build 는 페이지 · 묶음 화면과 링크만.