python document 만들기

2025-08-04

유저에게 웹으로 된 document를 커맨드라인에서 띄울 수 있게 하고 싶어. 어떻게 웹을 빌드하는게 좋을것 같아?

웹 기반 문서를 커맨드라인에서 띄우는 것을 목표로 한다면, 웹 페이지를 어떻게 빌드 하고 서빙 할지에 대해 전략적으로 접근할 필요가 있습니다. 다음은 step-by-step으로 고려할 수 있는 방식입니다:

1. 📄 문서 포맷 결정

먼저 어떤 형태의 document를 띄우려는지 정해야 합니다.

HTML 문서인가? Markdown인가? PDF인가?
정적 페이지인지, 동적으로 렌더링되는 페이지인지?

예: Markdown 기반 문서를 HTML로 변환하여 웹에 서빙한 뒤 커맨드라인에서 브라우저를 열도록 할 수 있음.

2. 🛠 웹 빌드 방식 선택

문서를 웹에 띄우기 위한 최소한의 frontend를 구성합니다.

⛳ 가장 간단한 방법:

Static HTML Generator 사용 :
- 예: Docusaurus, VitePress, Hugo
- Markdown 문서를 static 웹 페이지로 자동 변환 가능.

⚙️ 빌드 예시 (VitePress):

npm create vitepress
# 문서 작성: docs/index.md 등
npm run docs:build  # static 사이트 빌드

3. 🌐 로컬 서버 구성

생성된 정적 웹 파일을 서버에서 서빙해야 합니다.

선택지:

python -m http.server
npx serve ./dist
Express, FastAPI 등으로 간단한 서버 구성

# 예시: dist 폴더 내 정적 파일 서빙
npx serve dist
# 또는
python3 -m http.server 8080 --directory dist

4. 🖥 CLI에서 브라우저 열기

이제 커맨드라인에서 웹 문서를 띄우는 명령어를 실행합니다.

# macOS / Linux
xdg-open http://localhost:8080

# macOS 전용
open http://localhost:8080

# Windows
start http://localhost:8080

이렇게 하면 커맨드라인에서 명령 한 줄로 문서를 열 수 있습니다.

5. 🚀 배포까지 고려한다면

Netlify, GitHub Pages, Vercel 등을 사용해서 호스팅 가능.
커맨드라인에서 curl 등으로 접속하거나 링크만 열도록 할 수도 있음.

✅ 정리

단계	설명
1. 문서 포맷	Markdown → HTML이 보편적
2. 빌드 방식	VitePress, Hugo, Docusaurus 등
3. 로컬 서버	`python -m http.server`, `serve`, Express 등
4. CLI 실행	`open`, `xdg-open`, `start` 명령으로 띄우기
5. 배포 옵션	Netlify, Vercel, GitHub Pages 등

필요하다면 예제 스크립트나 템플릿도 같이 만들어줄 수 있어요. 특정 툴이나 언어 선호가 있다면 알려줘요.

오프라인 환경임을 고려해줘

오프라인 환경이라면 외부 호스팅이나 CDN 의존 없이 문서를 로컬에서 웹으로 빌드하고, CLI에서 브라우저로 띄울 수 있도록 만드는 방식 이 적합합니다. 다음은 오프라인 환경에 최적화된 빌드 및 실행 절차 입니다.

🛠️ 1. 문서 포맷 → HTML 변환

✅ 권장 포맷: Markdown → HTML

Markdown으로 문서 작성 (.md)
Pandoc 이나 Marked 를 활용해 HTML로 변환 가능

예시: Pandoc 사용

# 설치 (오프라인용 바이너리 준비 가능): https://github.com/jgm/pandoc/releases
pandoc input.md -o output.html

🧱 2. 웹 문서 구조 구성

output.html을 포함한 디렉토리를 예시로 들어보면:

offline-doc/
├── index.html       # 변환된 문서
├── style.css        # 로컬 CSS (필요시)
└── assets/          # 이미지, JS 등

CSS와 JS는 외부 링크 없이 모두 로컬 경로로 포함 해야 합니다.

중요 : 절대 https:// CDN 같은 링크 쓰면 안 됩니다. 모든 리소스를 직접 보관.

🌐 3. 로컬 웹서버 실행

선택지 A: Python 내장 서버

cd offline-doc
python3 -m http.server 8080

선택지 B: Node.js가 있다면 `serve` 사용

# 오프라인 설치를 위해 serve npm 패키지를 미리 다운로드하거나, 내부 레포에 배포
npx serve .

🖥️ 4. CLI에서 웹 페이지 띄우기

OS별 브라우저 열기 명령어:

macOS: open
Linux: xdg-open
Windows: start

open http://localhost:8080/index.html
# 또는
xdg-open http://localhost:8080/index.html

또는 CLI 앱에 이 명령을 포함시켜 문서 뷰어처럼 동작하게 할 수 있습니다.

💡 보너스: 문서 뷰어 CLI 스크립트

예를 들어 view_doc.sh:

#!/bin/bash
DIR=$(dirname "$0")
cd "$DIR"
python3 -m http.server 8080 > /dev/null 2>&1 &
sleep 1
xdg-open http://localhost:8080/index.html

문서 디렉토리에 index.html 넣고 실행하면 바로 열림

✅ 요약

항목	방법
문서 포맷	Markdown (.md), Pandoc으로 HTML 변환
리소스 관리	CSS/JS 포함 리소스 모두 로컬 저장
웹서버	`python3 -m http.server`
브라우저 열기	OS별 `open`, `xdg-open`, `start` 명령
오토 실행	bash 또는 bat 스크립트로 자동화

필요하다면 예제 디렉토리 구조, Pandoc 템플릿, 실행 스크립트도 제공해줄게요. Python, Node.js, Shell Script 중 어떤 걸 선호하나요?

pandoc은 한 페이지로만 변환할 수 있나?

Pandoc은 기본적으로 하나의 Markdown 파일을 하나의 HTML 문서로 변환합니다. 즉, "한 페이지로 변환"이 기본 동작입니다. 하지만 여러 Markdown 파일을 각각 혹은 하나로 묶어서 다양한 방식으로 처리할 수 있습니다. 아래에서 그 경우를 구분해 step-by-step으로 설명할게요.

✅ 1. 기본: 단일 파일 → 단일 HTML (기본 동작)

pandoc chapter1.md -o chapter1.html

결과: chapter1.html이라는 한 페이지 HTML 문서 생성됨.
이 경우, 긴 문서도 스크롤 한 페이지에 모두 들어감.

✅ 2. 여러 Markdown → 하나의 HTML로 병합

pandoc intro.md chapter1.md chapter2.md -o full.html

full.html이라는 한 페이지짜리 완성 문서 생성.
각 파일은 구분되어 들어가지만, HTML은 단일 파일.

🔀 3. 여러 페이지(파일)로 나누고 싶다면?

Pandoc 자체는 기본적으로 "책갈피가 있는 단일 HTML"을 생성하며, 여러 개의 HTML 파일로 나누지는 않습니다. 하지만 아래 방법들을 쓸 수 있어요:

🔧 방법 A: 각 Markdown → 각 HTML (다중 페이지)

for f in *.md; do
  pandoc "$f" -o "${f%.md}.html"
done

이 방식으로 chapter1.md, chapter2.md → 각각의 HTML 페이지로 변환됨.
각각의 HTML은 독립적이며 링크로 서로 연결 가능.

🔧 방법 B: 단일 HTML 내에 목차 및 섹션 anchor 삽입

pandoc --toc --toc-depth=2 full.md -o full.html

목차 포함 (--toc)
각 헤더 (#, ##)에 자동으로 anchor link 가 붙어서 네비게이션 가능
결과는 여전히 한 HTML 파일 이지만 느낌상 섹션 분할 이 됨.

🔧 방법 C: Pandoc + Scripting 으로 Multi-Page 사이트 구성

Pandoc만으로는 완전한 다중 페이지 네비게이션은 어렵지만, 쉘 스크립트나 Makefile을 사용해 각 페이지를 생성하고 링크를 수동으로 삽입하면 됩니다.

예:

# 목차 페이지 생성
echo "# 목차" > index.md
echo "- [1장](chapter1.html)" >> index.md
echo "- [2장](chapter2.html)" >> index.md

pandoc index.md -o index.html

🧠 팁: 다중 페이지 웹사이트용 도구

pandoc은 "전자책" 또는 "보고서" 스타일에 적합
다중 HTML 페이지로 분리된 웹사이트 스타일을 원한다면:
- mkdocs, mdbook, Docusaurus 등을 고려

✅ 요약

목적	가능 여부	방법
한 Markdown → 한 HTML	✅ 기본 동작	`pandoc a.md -o a.html`
여러 Markdown → 하나의 HTML	✅	`pandoc a.md b.md -o merged.html`
여러 Markdown → 여러 HTML	✅	루프/스크립트 사용
HTML을 여러 페이지로 자동 분할	❌ (Pandoc만으론 어려움)	스크립트/도구 활용 필요
목차/섹션 anchor로 나누기	✅	`--toc` 옵션 사용

정리하자면 , Pandoc은 "한 Markdown = 한 HTML" 철학이 기본입니다. 여러 페이지로 나누려면 직접 여러 파일로 분할하여 개별 변환 하거나, 웹사이트 생성 도구와 조합하는 방식이 필요해요.

원하는 결과가 "책처럼 페이지가 나뉜 문서"인지, "목차 있는 긴 HTML 하나"인지 말해주시면 거기에 맞는 예제도 만들어줄 수 있어요!

이미지 등도 넣을 수 있어?

네, Pandoc으로 HTML 문서를 만들 때 이미지도 얼마든지 넣을 수 있습니다. 다만 오프라인 환경이므로, 이미지를 반드시 로컬 경로로 포함 해야 합니다. 아래에 step-by-step으로 설명드릴게요.

✅ 1. Markdown에서 이미지 삽입하기

Markdown에서 이미지를 삽입하는 기본 문법은 다음과 같습니다:

![이미지 설명](images/photo.png)

images/photo.png는 현재 Markdown 파일 기준의 상대 경로입니다.
설명은 <img alt="..."> 태그로 변환됨.

Tip: 경로에 띄어쓰기가 있으면 %20 대신 "..."로 감싸는 게 안전합니다.

✅ 2. Pandoc으로 HTML 변환

pandoc input.md -o output.html

이 경우 Pandoc은 <img src="images/photo.png"> 태그를 생성합니다.
주의 : 이미지 파일 자체는 output.html에 포함되지 않으며 링크로만 참조 됩니다.

🔐 3. 오프라인에서 완전한 단일 파일 만들기 (Base64 임베딩)

HTML 하나에 이미지도 모두 포함 시키고 싶다면 --self-contained 옵션을 사용합니다:

pandoc input.md -o output.html --self-contained

이미지, CSS, JS 등을 모두 base64로 인코딩하여 HTML 내부에 포함
완전히 독립된 .html 파일 하나로 배포 가능

단점: 파일 용량 커짐 (이미지 많을수록)

📦 4. 외부 리소스를 함께 배포할 경우 디렉토리 구조 예시

offline-doc/
├── index.html
├── style.css
└── images/
    ├── photo1.jpg
    └── diagram.svg

Markdown에선 images/photo1.jpg처럼 링크
HTML로 변환한 후에도 해당 경로를 유지해야 이미지가 정상 표시됨

🖼️ 5. 이미지 포맷 호환성

Pandoc은 브라우저가 지원하는 대부분의 이미지 포맷을 지원합니다:

포맷	지원 여부	비고
PNG	✅	일반 그래픽
JPG	✅	사진 등
GIF	✅	애니메이션 포함
SVG	✅	벡터 이미지
WebP	✅	최신 브라우저 호환 시

✅ 요약

목적	방법
이미지 삽입	`![설명](images/pic.png)`
로컬 이미지 표시	이미지 파일을 경로에 포함
완전한 단일 HTML 파일	`--self-contained` 사용
오프라인 배포	HTML + 이미지 폴더 같이 배포

필요하다면 실제 예제 Markdown + HTML + 이미지 구조까지 만들어서 템플릿을 드릴 수 있어요. 원하시는 방식(분리 vs 단일 파일) 알려주시면 거기에 맞게 구성해드릴게요!

html 경로를 주고 예를 들어 mytool doc 하면 document 폴더의 index.html 열리게 하는 방식 어때

아주 훌륭한 방식입니다!
명령어 mytool doc을 입력하면 특정 폴더의 index.html을 열도록 만드는 건 오프라인 문서 뷰어를 CLI 도구로 만드는 매우 실용적인 접근 입니다.

아래는 그 아이디어를 구현 가능한 방식으로 step-by-step 으로 정리한 것입니다.

✅ 목표

nginx

mytool doc

이 명령을 실행하면:

로컬 document/index.html을
시스템 기본 브라우저에서 자동으로 열고
필요하면 백그라운드에 로컬 서버까지 띄움

📁 디렉토리 구조 예시

mytool/
├── mytool.sh           # 메인 실행 스크립트
├── document/
│   ├── index.html
│   ├── style.css
│   └── images/

🔧 1. `mytool.sh` (Bash 스크립트 예시)

#!/bin/bash

CMD=$1

if [[ "$CMD" == "doc" ]]; then
  DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
  cd "$DIR/document"

  # 로컬 서버 백그라운드 실행
  python3 -m http.server 8976 > /dev/null 2>&1 &

  # 서버 PID 저장 (종료 시킬 때 사용 가능)
  SERVER_PID=$!

  # 브라우저 열기
  if command -v xdg-open > /dev/null; then
    xdg-open http://localhost:8976/index.html
  elif command -v open > /dev/null; then
    open http://localhost:8976/index.html
  elif command -v start > /dev/null; then
    start http://localhost:8976/index.html
  else
    echo "브라우저를 여는 명령어를 찾을 수 없습니다."
  fi

  # 서버가 계속 돌도록 대기 (선택사항)
  wait $SERVER_PID
else
  echo "사용법: mytool doc"
fi

🔨 2. 실행 가능한 CLI로 만들기

chmod +x mytool.sh
ln -s /path/to/mytool/mytool.sh /usr/local/bin/mytool

이제 mytool doc 명령어로 실행 가능
오프라인에서도 문서 폴더 열기 가능

🧩 응용 아이디어

mytool doc chapter1 → chapter1.html 열도록 확장
mytool doc --print → PDF로 저장 또는 출력
mytool doc edit → 원본 Markdown 열기

✅ 요약

구성 요소	설명
`document/`	정적 HTML 문서 폴더
`mytool.sh`	CLI 인터페이스 역할
`python3 -m http.server`	로컬 서빙
`xdg-open`, `open`, `start`	시스템 브라우저 실행
심볼릭 링크	명령어를 글로벌하게 등록

필요하면 이걸 .deb 패키지, .pkg, .exe로 만들거나 Python 기반으로 다시 구현하는 것도 가능합니다.
이걸 Shell이 아니라 Python CLI (예: typer, click)로 구현하는 게 더 편하신가요?

그냥 html로 여는거 아니었어? 서버도 열어야해?

좋은 질문이에요!
반드시 로컬 서버를 열 필요는 없습니다.
하지만 “서버를 열 것인가, 그냥 HTML 파일을 브라우저로 열 것인가”는 다음 조건에 따라 달라집니다:

🧠 핵심 차이점: 직접 여는 것 vs 서버로 여는 것

방식| 장점| 단점
—|—|—
그냥 열기 (file://)| ✅ 빠르고 간단
✅ 서버 불필요| ❌ JS 로딩, 경로 제한 있을 수 있음 (브라우저 보안 정책에 따라)
서버 열기 (http://localhost)| ✅ HTML, JS, 이미지 로딩 완벽하게 동작
✅ 현대 웹앱과 호환성↑| ❌ Python 필요
❌ 포트 충돌 가능

✅ 1. 그냥 HTML을 열고 싶다면 (가장 간단한 방식)

▶️ 추천 조건:

정적 HTML만 있고, JS 프레임워크를 쓰지 않음
SPA (Single Page App)가 아님
보안 제한 무관한 환경 (내 PC, 내 브라우저)

▶️ 예제 코드:

#!/bin/bash

CMD=$1

if [[ "$CMD" == "doc" ]]; then
  DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
  FILE="$DIR/document/index.html"

  if command -v xdg-open > /dev/null; then
    xdg-open "$FILE"
  elif command -v open > /dev/null; then
    open "$FILE"
  elif command -v start > /dev/null; then
    start "$FILE"
  else
    echo "브라우저를 여는 명령어를 찾을 수 없습니다."
  fi
else
  echo "사용법: mytool doc"
fi

브라우저에서 file:///.../index.html 경로로 열림
단일 HTML 문서라면 이 방식이 제일 간단하고 충분합니다!

❗ 그런데 서버가 필요한 경우는?

예: Vue, React, Vite, Webpack, 이미지 fetch API, 로컬 스크립트에서 XMLHttpRequest 사용하는 경우

이런 경우 브라우저가 file://에서는 CORS나 보안 오류 를 낼 수 있어서 로컬 HTTP 서버가 필요합니다.

✅ 결론

정적 문서(index.html, style.css, img.png)만 있으면 👉 서버 없이 직접 여는 방식이 정답 입니다.
JavaScript가 파일을 불러오거나 모듈화된 웹앱이면 👉 로컬 서버 필요 합니다.

원하시는 방향 정리:

✅ mytool doc → 그냥 HTML 열기만 하면 된다

그렇다면 로컬 서버는 불필요 하고, 위의 "그냥 열기" 방식으로 충분합니다.

필요하면 이 방식으로 깔끔한 bash 템플릿도 만들어드릴게요!

pandoc이 js도 필요해?

아니요, Pandoc 자체는 JavaScript(JS)를 필요로 하지 않습니다.
즉, 기본적인 HTML 변환 결과물은 JS 없이도 완전히 동작 합니다. 아래에서 자세히 설명드릴게요:

✅ Pandoc의 HTML 출력: 기본 성격

pandoc input.md -o output.html

생성되는 output.html은 정적 HTML 문서 입니다.
내부에 <script> 태그도 없고, JS 파일도 사용하지 않음.
CSS도 포함되지 않거나, 옵션을 주지 않으면 inline으로 최소화됨.

➕ 예외적으로 JS가 포함되는 경우는 다음과 같습니다:

기능	JS 필요 여부	설명
기본 Markdown → HTML	❌ 필요 없음
`--highlight-style` (문법 강조)	✅ 필요할 수 있음 (highlight.js 내장)
`--toc` (목차 생성)	❌ 필요 없음 (JS 아닌 anchor 링크로 처리됨)
Reveal.js 슬라이드 출력	✅ 필요 (슬라이드용 JS 프레임워크 포함)
MathJax 수식 표현	✅ 필요 (JS 수식 렌더링)

🔍 예시: JS 없이 변환

pandoc mydoc.md -o mydoc.html

이 파일은 아무런 JS 없이 file://로 브라우저에서 열 수 있음.
이미지, 링크, 헤더 등 HTML 기본 기능만으로도 충분히 표현됨.

🧠 그럼 언제 JS가 필요한가?

JS는 Pandoc과는 관계 없이 당신이 문서에 추가한 기능이나 스타일에 따라 필요할 수 있습니다. 예를 들어:

문서 내 인터랙션 (접었다 펴기, 탭 전환 등)
수식 렌더링 (LaTeX → MathJax)
Reveal.js 슬라이드 출력
검색 기능, 페이지 이동 등 SPA 느낌

이런 경우는 Pandoc에서 template을 바꾸거나, 후처리로 JS를 붙이는 거지 Pandoc 자체 요구사항은 아닙니다.

✅ 결론

질문	대답
Pandoc이 HTML 만들 때 JS 필요해?	❌ (기본 변환은 필요 없음)
언제 JS가 필요할 수 있어?	문법 강조, 수식, 슬라이드, 고급 UI 추가할 때
기본 문서 보기만 한다면?	그냥 `file://`로 HTML 열면 충분

원하시는 게 "그냥 Markdown → HTML 변환해서 문서 보기"라면, Pandoc만으로도 아주 충분하고, JS 없이 완전한 결과 를 만들 수 있습니다.

수식이나 슬라이드 같은 JS 기능을 붙이고 싶으면, 그에 맞는 설정도 도와드릴 수 있어요!

근데 click subcommand로 doc을 줄건데 어떻게 연결하는게 좋을까 doc이 배포되는 경로를 하드코딩하긴 좀 그런데 pyproject 로 html 빌드된 경로 주고 mytool doc 했을 때 그 리소스를 참조하게 할 수 있어?

좋은 질문이에요.
Python 프로젝트에서 click으로 mytool doc 서브커맨드를 만들고, HTML로 빌드된 문서를 자연스럽게 참조하게 하고 싶다 는 목표죠.
핵심은 “HTML 리소스를 하드코딩하지 않고, 패키지 내부에 포함된 리소스를 동적으로 참조하는 방식”입니다.

이를 해결하려면 패키징된 HTML 리소스를 접근할 수 있는 안정적인 방식 이 필요합니다.

✅ 해결 전략 요약

목표 : mytool doc → 패키지 안에 포함된 index.html 열기 (서버 없이 or 선택적으로 서버로)

📦 리소스를 패키지에 포함 + 안전하게 참조

Python의 importlib.resources 또는 pkg_resources를 사용하면
패키지 내부에 포함된 HTML 리소스를 안전하게 참조할 수 있습니다.

🧱 예시 구조 (pyproject.toml 기반 패키지)

mytool/
├── __init__.py
├── cli.py               # click entrypoint
├── docs/                # HTML 리소스 위치
│   ├── index.html
│   └── style.css
pyproject.toml

pyproject.toml 설정

[tool.setuptools.package-data]
mytool = ["docs/**/*"]

또는 MANIFEST.in이 필요한 경우:
recursive-include mytool/docs *

🧠 core: 리소스 파일을 참조해서 여는 방법

✅ Python ≥ 3.9: `importlib.resources.files`

from importlib.resources import files
import webbrowser

def open_docs():
    html_path = files("mytool").joinpath("docs/index.html")
    webbrowser.open(f"file://{html_path}")

files(...)는 설치된 wheel 안에서도 정상 동작
상대 경로 하드코딩 안 해도 됨
.joinpath(...)로 안정적으로 서브 디렉토리 접근 가능

⚠️ 주의: file:// 경로는 시스템에 따라 URI 인코딩에 주의

🧾 click CLI 예시

import click
from importlib.resources import files
import webbrowser

@click.group()
def cli():
    pass

@cli.command()
def doc():
    """Open HTML documentation in browser."""
    html_path = files("mytool").joinpath("docs/index.html")
    webbrowser.open(f"file://{html_path}")

if __name__ == "__main__":
    cli()

💡 서버를 선택적으로 띄우고 싶다면?

import http.server
import socketserver
import threading

@click.command()
@click.option("--serve", is_flag=True, help="Serve via local HTTP")
def doc(serve):
    if serve:
        from importlib.resources import files
        doc_dir = str(files("mytool").joinpath("docs"))
        port = 8000

        handler = http.server.SimpleHTTPRequestHandler
        httpd = socketserver.TCPServer(("", port), handler)

        thread = threading.Thread(target=httpd.serve_forever)
        thread.daemon = True
        thread.start()

        webbrowser.open(f"http://localhost:{port}/index.html")
    else:
        html_path = files("mytool").joinpath("docs/index.html")
        webbrowser.open(f"file://{html_path}")

✅ 요약

목적	방법
리소스를 하드코딩 없이 참조	`importlib.resources.files()`
HTML 포함	`package_data` 또는 `MANIFEST.in`
브라우저 열기	`webbrowser.open()` 사용
선택적 서버 서빙	`http.server` + `--serve` 옵션
pyproject.toml 패키징	`mytool/docs/*/` 경로 포함 설정 필요

필요하다면 pyproject.toml, MANIFEST.in, 실제 프로젝트 구조까지 예제 템플릿 드릴 수 있어요.
wheel로 배포될 경우도 포함해서 안정적인 접근 방식 원하시면 알려주세요!

잡혀있는 webbrowser path 보는 법

webbrowser 모듈에서 현재 잡혀있는(사용되는) 브라우저 경로를 직접 확인 하려면, 내부적으로 등록된 브라우저 객체를 살펴야 합니다.
다만 webbrowser.open()은 내부에서 자동으로 default 브라우저를 선택하거나, 환경변수에 따라 다르게 동작하기 때문에 직접 경로를 반환해주진 않습니다.

하지만 아래의 방법들로 어느 브라우저가 잡혀 있는지 유추하거나 명시적으로 확인 할 수 있습니다:

✅ 1. 사용 가능한 브라우저 리스트 확인

import webbrowser

print(webbrowser._browsers)

이 딕셔너리에는 webbrowser.register()로 등록된 브라우저들이 나옴

예시 출력:

{'chrome': [None, <webbrowser.BackgroundBrowser object at 0x...>],
 'firefox': [None, <webbrowser.Mozilla object at 0x...>]}

✅ 2. 기본으로 사용되는 브라우저 객체 확인

import webbrowser

browser = webbrowser.get()
print(browser)

결과:

<webbrowser.MacOSXOSAScript object at 0x...>
<webbrowser.BackgroundBrowser object at 0x...>

여기서는 객체 타입을 통해 기본 브라우저가 무엇인지 유추 가능

✅ 3. 명시적으로 브라우저 인스턴스를 가져올 때 (경로 확인 가능)

import webbrowser

chrome = webbrowser.get("chrome")
print(chrome)

또는:

import webbrowser

firefox = webbrowser.get("firefox")
print(firefox.name)
print(getattr(firefox, 'basename', None))  # 일부 브라우저에만 존재

BackgroundBrowser 클래스는 내부적으로 실행 경로를 들고 있음:

print(firefox._name)
print(firefox._executable)  # 등록된 실행 경로

✅ 4. 브라우저 경로 수동 등록 후 확인

webbrowser.register("mychrome", None, webbrowser.BackgroundBrowser("/usr/bin/google-chrome"))
browser = webbrowser.get("mychrome")
print(browser._executable)

💡 참고: 운영체제에 따라 기본 브라우저 확인하는 CLI

macOS:
```
open -a Safari
```
Linux:
```
xdg-settings get default-web-browser
```

Windows (PowerShell):

Get-ItemProperty 'HKCU:\Software\Microsoft\Windows\Shell\Associations\UrlAssociations\http\UserChoice'

✅ 결론

목적	방법
기본 브라우저 객체 확인	`webbrowser.get()`
등록된 브라우저 목록 보기	`webbrowser._browsers`
브라우저 실행 경로 확인	`BackgroundBrowser._executable`
명시 등록 시 경로 추적	`webbrowser.register(...)` 후 `.get(...)._executable`

필요하면 브라우저 경로 자동 탐지 및 fallback 등록 스크립트도 만들어드릴게요.
특정 OS에 대해 더 구체적인 경로 찾고 싶으시면 말씀해주세요!

내가 특정한 브라우저 바이너리를 지정해서 열게하고 싶어

완벽합니다 — 그럴 때는 Python의 webbrowser 모듈에서 원하는 브라우저 실행 바이너리를 직접 지정해서 등록 하면 됩니다.
즉, webbrowser.register()를 사용해 바이너리 경로를 지정하고, 그 브라우저로 .open()을 수행하면 돼요.

✅ 목표

내가 원하는 경로의 브라우저 (/opt/my-chrome/bin/chrome 등)로 문서를 열고 싶다.

🛠️ 방법: `webbrowser.BackgroundBrowser` 사용

import webbrowser

# 원하는 브라우저 바이너리 경로
browser_path = "/opt/my-chrome/bin/chrome"

# 'mybrowser' 이름으로 등록
webbrowser.register("mybrowser", None, webbrowser.BackgroundBrowser(browser_path))

# 가져와서 열기
browser = webbrowser.get("mybrowser")
browser.open("file:///path/to/your/index.html")

📎 옵션: `open_new_tab()` 또는 `open_new()`

browser.open_new_tab("file:///...")

✅ 전체 예제

import webbrowser
from pathlib import Path

def open_with_custom_browser(doc_path: Path, browser_bin: str):
    # 파일을 절대경로로 바꾸고 URL 스킴 추가
    abs_path = doc_path.resolve()
    url = abs_path.as_uri()  # e.g., 'file:///home/user/doc/index.html'

    # 브라우저 등록
    webbrowser.register("mybrowser", None, webbrowser.BackgroundBrowser(browser_bin))

    # 열기
    browser = webbrowser.get("mybrowser")
    browser.open_new_tab(url)

# 예시 사용
open_with_custom_browser(Path("./document/index.html"), "/opt/chromium/chrome")

💡 참고: 경로가 이상할 때 문제 해결 팁

경로에 공백이 있으면 Path(...).as_uri() 방식이 안전
브라우저 실행 권한이 없으면 PermissionError
브라우저가 headless 설정으로 실행되면 UI가 안 뜰 수 있음

✅ 정리

항목	설명
브라우저 바이너리 지정	`webbrowser.BackgroundBrowser('/my/path')`
등록 이름	`webbrowser.register('mybrowser', ...)`
파일 URL로 열기	`Path(...).as_uri()` 사용
새 탭으로 열기	`browser.open_new_tab(url)`

필요하면 macOS, Windows, Linux 별로 크롬이나 파이어폭스 기본 위치 자동 탐지하는 스크립트도 도와드릴게요.
지정하려는 브라우저가 특별한 환경 설정이 있다면 그것도 알려주세요!

BackgroundBrowser는 뭐야?

좋은 질문이에요! webbrowser.BackgroundBrowser는 Python의 webbrowser 모듈 내부에 있는 브라우저 실행 클래스 중 하나 로,
지정한 브라우저 실행 파일을 사용해 백그라운드에서 브라우저를 실행 하는 용도로 쓰입니다.

아래에서 step-by-step으로 설명할게요.

✅ `BackgroundBrowser`란?

from webbrowser import BackgroundBrowser

브라우저 실행 바이너리를 직접 지정해서 등록 할 때 사용하는 클래스입니다.
보통 webbrowser.register()와 함께 사용됩니다.
주로 사용자가 설치한 커스텀 브라우저 실행 파일 경로 를 지정할 때 쓰입니다.

✅ 언제 쓰냐?

webbrowser.get()은 시스템 기본 브라우저를 찾지만,
당신이 원하는 브라우저가 등록되어 있지 않거나,
특정 경로의 실행 파일을 직접 지정하고 싶을 때 사용합니다.

🔧 사용 예시

import webbrowser

# 크롬 바이너리 경로 예시
chrome_path = "/opt/google/chrome/chrome"

# 'custom-chrome'이라는 이름으로 등록
webbrowser.register(
    "custom-chrome",
    None,
    webbrowser.BackgroundBrowser(chrome_path)
)

# 해당 브라우저로 열기
browser = webbrowser.get("custom-chrome")
browser.open("file:///path/to/index.html")

⚙️ 내부적으로 하는 일

BackgroundBrowser는 .open(url)을 호출했을 때 다음을 수행합니다:

/path/to/your/browser "file:///..."

즉, 그냥 subprocess로 브라우저 실행 파일에 URL을 넘겨주는 역할이에요.

📘 실제 소스 코드 (요약)

class BackgroundBrowser(BaseBrowser):
    def __init__(self, name):
        self.name = name  # 경로 (예: "/usr/bin/firefox")

    def open(self, url, new=0, autoraise=True):
        command = [self.name, url]
        subprocess.Popen(command, ...)

✅ 요약

항목	설명
이름	`webbrowser.BackgroundBrowser`
역할	브라우저 실행 파일 경로를 직접 지정하여 URL 열기
사용 시기	시스템 기본 브라우저 대신 원하는 바이너리로 열고 싶을 때
대표 메서드	`.open(url)`, `.open_new_tab(url)`
등록 방법	`webbrowser.register("이름", None, BackgroundBrowser(경로))`

원하시면 Chrome/Firefox 경로 자동 탐지 후 BackgroundBrowser에 등록하는 유틸도 만들어드릴 수 있어요!

documentation page 작성용 라이브러리는 따로 없어? pandoc은 좀 범용적인 느낌

맞아요, 아주 날카로운 지적입니다!
Pandoc은 문서 포맷 변환에 특화된 범용 툴 이라서 정적 사이트로 된 documentation page 를 만들기엔 조금 무겁거나 유연성이 떨어질 수 있어요.

그래서 “문서 페이지(Documentation Site)” 전용으로 설계된 Python 친화적 도구들 이 있습니다.
아래에서 목적에 맞는 라이브러리를 분류하고 설명 해 드릴게요.

📚 목적: Markdown → 정적 웹 기반 문서 사이트 생성

✅ 1. MkDocs ⭐ 가장 추천

Python 기반
docs/ 폴더 안의 Markdown 파일을 읽어서 정적 사이트 생성
GitHub Pages 배포도 아주 쉬움
YAML로 구성 설정 (mkdocs.yml)

설치 및 사용

pip install mkdocs
mkdocs new my-project
cd my-project
mkdocs serve        # 로컬에서 미리보기
mkdocs build        # 정적 HTML 생성

장점

자동 목차, 검색, 테마 (Material theme 인기↑)
pyproject.toml 프로젝트와 잘 통합됨
문서 디렉토리와 빌드 결과물이 분리됨

📦 Material 테마 는 아래처럼 설치하면 더 강력해져요:

pip install mkdocs-material

✅ 2. Sphinx

원래는 Python 코드용 API 문서 생성기지만, 일반 문서 사이트도 가능
reStructuredText가 기본이지만 Markdown도 지원
대규모 문서, cross-reference, 수식 등에 강함

설치 및 사용

pip install sphinx
sphinx-quickstart
make html

📦 Markdown 사용하려면:

pip install myst-parser

장점

Python 프로젝트와 강하게 통합됨 (docstring → 문서 자동화)
표, 수식, cross-reference 등 기술문서 특화
HTML/PDF/EPUB 다 가능

✅ 3. Docusaurus (JS 기반이지만 언급)

Meta(구 Facebook)에서 만든 문서 전용 정적 사이트 생성기
JS/React 기반이지만 Markdown로 작성 가능
커스터마이징/검색/버전 관리에 강함

npx create-docusaurus@latest my-site classic
cd my-site
npm start

Python 기반 아니지만 대규모 문서 프로젝트 에 적합

🔍 비교 요약

이름	언어 기반	특징	추천 상황
MkDocs	Python	Markdown 중심, 빠름, 테마 다양	일반 문서 사이트, CLI 툴 문서에 강추
Sphinx	Python	reST 기반, API doc 자동화	Python 프로젝트 + API 자동 문서화
Docusaurus	JS (React)	깔끔한 UI, 버전관리 가능	고급 UI 문서, JS 친화 환경
Pandoc	CLI/범용	다양한 포맷 간 변환	보고서, 논문, eBook 스타일

✅ 추천 시나리오

CLI 툴, 경량 문서, Markdown 중심 → ✅ MkDocs + Material
Python 프로젝트에 포함된 코드 자동 문서화 → ✅ Sphinx + myst-parser
고급 UI, 다국어, 다중 버전 → ✅ Docusaurus
PDF, LaTeX, ePub 등 포맷 변환 → ✅ Pandoc

📌 결론

🟩 “Python 프로젝트에서 쉽게 문서 페이지 만들고 싶다.”
→ MkDocs + Material Theme 가 최선입니다.

필요하시면 pyproject.toml 통합 구조, mkdocs.yml 샘플, 배포 설정까지 한 번에 구성된 템플릿도 드릴 수 있어요!

이걸 배포하면 유저가 로컬 서버를 열게하는 식으로 해야하나

훌륭한 질문입니다.
문서 사이트(MkDocs 등)를 배포한 후, 유저가 어떻게 보게 할 것인가?
→ 이것은 “어떻게 문서를 열도록 할 것인가”에 대한 전략이고, 아래 3가지 방식 중에서 골라야 합니다:

✅ 선택지 요약

방식	유저가 해야 하는 일	브라우저 지원	설명
1. 그냥`file://`로 열기	`index.html` 더블클릭 or `open` 명령	일부 제한 있음	서버 필요 없음, HTML에서 JS 로딩 시 제한 가능
2. 로컬 서버 열기	`python -m http.server` 등	완벽 지원	가장 범용적이고 JS도 문제없음
3. 외부 서버 배포	URL 접속만	✅	GitHub Pages, Netlify, Vercel 등 필요 (오프라인 X)

🔍 당신이 말한 방식은:

“로컬에 문서 HTML을 포함해서 배포 하고, 유저가 mytool doc 명령어로 보기 원함”

→ 이건 “로컬 서버 열기” 방식(2번)이 가장 안정적이고 표준적인 방법 입니다. 이유는 아래와 같습니다:

✅ 왜 로컬 서버 방식이 적합한가?

🔒 보안 제한 문제 (file:// 경로)

현대 브라우저는 file://로 열었을 때:
- JS가 로드 안 되거나,
- 경로 문제 발생 (특히 CSS, 이미지, client-side routing)

js

// 예: MkDocs Material의 JS 검색기능 등이 안 될 수 있음

💻 로컬 서버를 열면?

python3 -m http.server 8000
# 또는
mkdocs serve

브라우저는 이를 정상적인 웹 페이지로 인식 함 (http://localhost:8000)
모든 기능 100% 작동 (검색, 라우팅, 이미지 등)

🎯 배포 방식 설계 제안

📦 1. 유저에게 HTML 빌드 결과 + 실행 스크립트 제공

mytool/
├── cli.py
├── docs/                 ← mkdocs build 결과 (site/)
│   ├── index.html
│   ├── js/
│   └── css/
├── __init__.py
└── ...

🛠 2. click 명령어 예시

@click.command()
def doc():
    """Open documentation in local browser."""
    import http.server
    import socketserver
    import threading
    import webbrowser
    import os
    from pathlib import Path

    doc_dir = Path(__file__).parent / "docs"
    os.chdir(doc_dir)

    port = 8000
    Handler = http.server.SimpleHTTPRequestHandler
    httpd = socketserver.TCPServer(("", port), Handler)

    # 백그라운드에서 서버 실행
    thread = threading.Thread(target=httpd.serve_forever)
    thread.daemon = True
    thread.start()

    # 브라우저 열기
    webbrowser.open(f"http://localhost:{port}/index.html")

📦 설치 or 배포 형태

방법	설명
pip 패키지 + docs 포함	`package_data`로 정적 파일 포함
wheel 배포	설치 후 CLI에서 바로 `mytool doc` 실행 가능
zip 배포	유저가 직접 실행 (`./run-doc.sh`) 등으로 열도록 안내

✅ 결론

조건	추천 방식
유저가 오프라인 + full 기능 보기 원함	✅ 로컬 서버 방식 (권장)
기능 제약 감수하고 단순히 보기만 원함	`file://`로 열기 가능 (제한 존재)
온라인 문서 배포하고 싶음	GitHub Pages 등 사용 가능

필요하다면 click + MkDocs 기반 배포 스크립트, 템플릿 구조, pyproject 통합까지 완성된 샘플 만들어 드릴 수 있어요!
유저 편의성 극대화하는 실행 UX도 같이 설계할 수 있습니다. 원하시나요?

python package 내의 docs 폴더는 일반 유저를 위한 걸까 개발자들을 위한 걸까

좋은 질문이에요.
Python 패키지 내의 docs/ 폴더는 "의도와 컨텍스트에 따라 다르게 쓰일 수 있는 디렉토리"입니다.
그렇기 때문에 정확히 말하면 "개발자용이냐, 일반 사용자용이냐"는 명확히 정해져 있지 않습니다.
하지만 현실에서는 용도에 따라 아래처럼 구분해서 쓰이는 경향이 강합니다.

✅ 1. 개발자용 `docs/` — 일반적 관례

📁 위치 : 프로젝트 루트 (pyproject.toml과 같은 레벨)

myproject/
├── pyproject.toml
├── src/
│   └── myproject/
├── tests/
├── docs/               👈 여기가 개발자 문서
│   ├── index.md
│   ├── api.md
│   └── usage.md

▶️ 주로 포함하는 내용:

설치 방법
사용 예제
개발 가이드 / 컨트리뷰션 안내
API 문서
빌드 방법, 환경 설정, 개발 히스토리

▶️ 작성 형식:

Markdown, reStructuredText
Sphinx, MkDocs 등 정적 사이트 생성기와 연동

✅ 2. 유저 가이드용 `docs/` — 사용자-facing 문서 포함하는 경우

📁 위치 : 패키지 내부에 포함 (src/myproject/docs/ 등)

src/
└── myproject/
    ├── __init__.py
    ├── core.py
    └── docs/           👈 여기가 사용자-facing HTML, Markdown
        └── index.html

▶️ 이 경우에는:

일반 사용자용 GUI 도움말 또는 웹 문서 포함
mytool doc 같은 커맨드에서 열리는 정적 문서 포함
종종 package_data에 포함하여 .whl로 배포

📦 관점 정리: 용도에 따른 차이

목적	위치	대상	예
개발자용 문서	루트 `/docs/`	프로젝트 개발자	Sphinx, MkDocs source
유저 가이드 문서 (빌드 결과)	패키지 내 `mytool/docs/`	일반 사용자	HTML, CSS 포함해서 브라우저로 열기
API doc (자동 생성)	루트 `/docs/` 또는 별도	개발자	Sphinx API, autodoc

💡 예: `mytool doc`을 통해 문서를 보여주고 싶다면?

그 문서는 “유저 가이드 ” → 따라서 패키지 내부의 docs/가 적합
mytool/
├── __init__.py
├── cli.py
├── docs/           👈 여기에 HTML 결과 포함
│   └── index.html

그리고 pyproject.toml에:

[tool.setuptools.package-data]
mytool = ["docs/**/*"]

✅ 결론

질문	답변
`docs/`는 원래 누구를 위한 폴더인가요?	루트`docs/`는 개발자용, 패키지 내 `docs/`는 사용자용으로 활용 가능
사용자 가이드 HTML을 패키지에 넣고 싶어요	패키지 내부에 넣고 `package_data`로 포함
`mytool doc`으로 열 문서를 넣을 곳은?	패키지 내부 `mytool/docs/`가 적절

필요하다면 프로젝트 구조 템플릿도 만들어드릴게요!
혹시 이걸 라이브러리로 쓸지, CLI 툴로 쓸지 명확하면 거기에 맞춰 더 구체적으로 도와드릴 수 있어요.

프로젝트 구조 만들어줘

좋습니다!
당신의 목적은:

✅ Python CLI 툴 프로젝트
✅ mytool doc 명령어로 사용자용 HTML 문서 를 열 수 있게 만들기
✅ 정적 문서는 패키지에 포함 되며, 로컬 브라우저에서 띄우도록 함

이에 맞는 프로젝트 구조, pyproject 설정, click CLI, docs 포함 방식까지 완성된 예제 를 아래에 제공합니다.

🧱 프로젝트 구조

mytool/
├── pyproject.toml
├── README.md
├── LICENSE
├── src/
│   └── mytool/
│       ├── __init__.py
│       ├── cli.py              ← main CLI entrypoint
│       └── docs/               ← 사용자-facing HTML 문서
│           ├── index.html
│           ├── style.css
│           └── images/
└── tests/
    └── test_cli.py

📦 pyproject.toml (setuptools 기반)

[build-system]
requires = ["setuptools>=61.0"]
build-backend = "setuptools.build_meta"

[project]
name = "mytool"
version = "0.1.0"
description = "A sample CLI tool with documentation viewer"
readme = "README.md"
requires-python = ">=3.7"
dependencies = ["click"]

[project.scripts]
mytool = "mytool.cli:cli"

[tool.setuptools.packages.find]
where = ["src"]

[tool.setuptools.package-data]
mytool = ["docs/**/*"]    # HTML 문서를 wheel에 포함

🧪 `src/mytool/cli.py` (Click + docs 오픈)

import click
import webbrowser
from importlib.resources import files
from pathlib import Path

@click.group()
def cli():
    pass

@cli.command()
def doc():
    """Open the local HTML documentation."""
    try:
        # docs/index.html 파일 위치 찾기
        html_path = files("mytool").joinpath("docs/index.html")
        # 브라우저에서 열기
        webbrowser.open(html_path.as_uri())
    except Exception as e:
        click.echo(f"문서를 열 수 없습니다: {e}")

📎 `src/mytool/init.py`

# 빈 파일 (패키지 인식용)

🧪 `tests/test_cli.py`

from click.testing import CliRunner
from mytool.cli import cli

def test_doc_command_runs():
    runner = CliRunner()
    result = runner.invoke(cli, ["doc"])
    assert result.exit_code == 0

🧾 사용 예시

패키지 설치:

pip install .

커맨드 실행:

mytool doc

→ 기본 브라우저에서 docs/index.html 열림

✅ 빌드 & 배포 준비

python -m build      # pyproject.toml 기반 wheel 생성
twine upload dist/*  # PyPI 배포 가능

🧠 유용한 추가 아이디어

기능	구현 포인트
`mytool doc --serve`	`http.server`로 로컬 서버 열기
문서 버전 나누기	`docs/v1/index.html`, `docs/v2/` 폴더 구성
CLI 자동 문서화 연동	MkDocs나 Sphinx의 자동 docstring 추출 활용

🎁 전체 템플릿이 필요하면?

필요하시면 전체 디렉토리 + 파일 내용 통으로 .zip 템플릿 만들거나, GitHub 템플릿 저장소로 구성해드릴 수 있어요. 원하시나요?

1. 📄 문서 포맷 결정

2. 🛠 웹 빌드 방식 선택

⛳ 가장 간단한 방법:

⚙️ 빌드 예시 (VitePress):

3. 🌐 로컬 서버 구성

선택지:

4. 🖥 CLI에서 브라우저 열기

5. 🚀 배포까지 고려한다면

✅ 정리

🛠️ 1. 문서 포맷 → HTML 변환

✅ 권장 포맷: Markdown → HTML

예시: Pandoc 사용

🧱 2. 웹 문서 구조 구성

🌐 3. 로컬 웹서버 실행

선택지 A: Python 내장 서버

선택지 B: Node.js가 있다면 serve 사용

🖥️ 4. CLI에서 웹 페이지 띄우기

OS별 브라우저 열기 명령어:

💡 보너스: 문서 뷰어 CLI 스크립트

✅ 요약

✅ 1. 기본: 단일 파일 → 단일 HTML (기본 동작)

✅ 2. 여러 Markdown → 하나의 HTML로 병합

🔀 3. 여러 페이지(파일)로 나누고 싶다면?

🔧 방법 A: 각 Markdown → 각 HTML (다중 페이지)

🔧 방법 B: 단일 HTML 내에 목차 및 섹션 anchor 삽입

🔧 방법 C: Pandoc + Scripting 으로 Multi-Page 사이트 구성

🧠 팁: 다중 페이지 웹사이트용 도구

✅ 요약

✅ 1. Markdown에서 이미지 삽입하기

✅ 2. Pandoc으로 HTML 변환

🔐 3. 오프라인에서 완전한 단일 파일 만들기 (Base64 임베딩)

📦 4. 외부 리소스를 함께 배포할 경우 디렉토리 구조 예시

🖼️ 5. 이미지 포맷 호환성

✅ 요약

✅ 목표

📁 디렉토리 구조 예시

🔧 1. mytool.sh (Bash 스크립트 예시)

🔨 2. 실행 가능한 CLI로 만들기

🧩 응용 아이디어

✅ 요약

🧠 핵심 차이점: 직접 여는 것 vs 서버로 여는 것

✅ 1. 그냥 HTML을 열고 싶다면 (가장 간단한 방식)

▶️ 추천 조건:

▶️ 예제 코드:

❗ 그런데 서버가 필요한 경우는?

✅ 결론

원하시는 방향 정리:

✅ Pandoc의 HTML 출력: 기본 성격

➕ 예외적으로 JS가 포함되는 경우는 다음과 같습니다:

🔍 예시: JS 없이 변환

🧠 그럼 언제 JS가 필요한가?

✅ 결론

✅ 해결 전략 요약

📦 리소스를 패키지에 포함 + 안전하게 참조

🧱 예시 구조 (pyproject.toml 기반 패키지)

pyproject.toml 설정

🧠 core: 리소스 파일을 참조해서 여는 방법

✅ Python ≥ 3.9: importlib.resources.files

🧾 click CLI 예시

💡 서버를 선택적으로 띄우고 싶다면?

✅ 요약

✅ 1. 사용 가능한 브라우저 리스트 확인

✅ 2. 기본으로 사용되는 브라우저 객체 확인

✅ 3. 명시적으로 브라우저 인스턴스를 가져올 때 (경로 확인 가능)

✅ 4. 브라우저 경로 수동 등록 후 확인

💡 참고: 운영체제에 따라 기본 브라우저 확인하는 CLI

✅ 결론

✅ 목표

🛠️ 방법: webbrowser.BackgroundBrowser 사용

📎 옵션: open_new_tab() 또는 open_new()

✅ 전체 예제

💡 참고: 경로가 이상할 때 문제 해결 팁

✅ 정리

✅ BackgroundBrowser란?

✅ 언제 쓰냐?

🔧 사용 예시

⚙️ 내부적으로 하는 일

📘 실제 소스 코드 (요약)

✅ 요약

📚 목적: Markdown → 정적 웹 기반 문서 사이트 생성

선택지 B: Node.js가 있다면 `serve` 사용

🔧 1. `mytool.sh` (Bash 스크립트 예시)

✅ Python ≥ 3.9: `importlib.resources.files`

🛠️ 방법: `webbrowser.BackgroundBrowser` 사용

📎 옵션: `open_new_tab()` 또는 `open_new()`

✅ `BackgroundBrowser`란?

✅ 1. 개발자용 `docs/` — 일반적 관례

✅ 2. 유저 가이드용 `docs/` — 사용자-facing 문서 포함하는 경우

💡 예: `mytool doc`을 통해 문서를 보여주고 싶다면?

🧪 `src/mytool/cli.py` (Click + docs 오픈)

📎 `src/mytool/init.py`

🧪 `tests/test_cli.py`