공들여 만든 라이브러리를 공개했는데, 정작 사용 설명서를 어디에 올려야 할지 몰라 난감하셨죠? 문서를 제대로 호스팅하려면 서버를 빌려야 하고, 서버를 빌리면 매달 요금이 나갑니다.
게다가 문서는 한 번 올리고 끝나는 게 아닙니다. 코드가 바뀔 때마다 문서도 새로 만들어 올려야 하고, 버전이 여러 개면 옛 버전 문서도 같이 남겨둬야 하지요. 이걸 손으로 관리하다 보면 문서가 코드보다 먼저 방치됩니다.
그런데 이 모든 과정을 자동으로 처리하면서, 오픈소스 프로젝트라면 요금을 한 푼도 받지 않는 곳이 있습니다.
이게 무료라는 게 믿기시나요?
핵심 요약
코드 저장소를 연결해두기만 하면, 코드가 바뀔 때마다 문서가 자동으로 다시 만들어져 웹에 올라갑니다. 문서를 빌드하고 서버에 업로드하는 수작업이 통째로 사라지는 것이지요.
여러 버전의 문서를 동시에 유지하는 것도 자동으로 됩니다. 최신판을 보다가 옛 버전으로 전환하는 선택 메뉴가 화면에 알아서 생기니, 버전별 문서를 따로 폴더로 관리하던 수고가 없어집니다.
여기에 문서 전용 검색 기능까지 붙어서, 사용자가 원하는 항목을 알아서 찾아갈 수 있습니다. 그리고 이 모든 게 오픈소스 프로젝트에는 언제나 무료입니다. 어떤 곳이길래 이런 게 되는 걸까요?
사이트 소개
이곳의 이름은 리드 더 독스(Read the Docs)이고, 주소는 [https://about.readthedocs.com](https://about.readthedocs.com**) 입니다. 실제 문서가 서비스되는 주소는 프로젝트마다 프로젝트이름.readthedocs.io 형태로 만들어집니다.
정체성은 "문서 전용 배포 플랫폼"입니다. 범용 웹 호스팅이 아니라, 기술 문서라는 한 가지 용도에만 집중해 만들어진 서비스라는 뜻이지요. 그래서 버전 관리, 검색, 다국어 같은 문서 특유의 요구사항이 기본 기능으로 들어가 있습니다.
규모가 신뢰의 근거가 됩니다. 이곳의 커뮤니티 서비스는 크고 작은 오픈소스 프로젝트 10만 개 이상의 문서를 무료로 호스팅하고 있습니다. 파이썬 생태계를 조금이라도 들여다본 분이라면 주소 끝에 readthedocs.io가 붙은 문서를 이미 여러 번 보셨을 겁니다.
운영 방식도 특이합니다. 이곳은 오픈소스 문서를 무료로 지원한다는 철학을 공개적으로 밝히고, 그 비용을 유료 상품과 광고로 감당하는 구조로 운영됩니다. 무료가 일시적인 프로모션이 아니라 서비스의 존재 이유에 해당한다는 뜻입니다.
기능 소개
가장 핵심은 자동 빌드입니다. 깃 저장소를 연결해두면 코드가 갱신될 때마다 문서 소스를 읽어 HTML로 변환하고 배포까지 알아서 마칩니다. 이 덕분에 문서를 만들고 서버에 올리는 반복 작업이 통째로 사라집니다.
두 번째는 버전 관리입니다. 브랜치나 태그별로 문서를 각각 만들어 보관하고, 화면 구석에 버전 선택 메뉴를 자동으로 붙여줍니다. 그래서 사용자가 "나는 옛 버전을 쓰는데 문서는 최신판뿐"이라며 겪던 혼란을 없앨 수 있습니다.
세 번째는 문서 내 검색입니다. 별도로 검색 엔진을 붙이거나 색인을 관리할 필요 없이, 문서 전체를 대상으로 한 검색창이 기본으로 제공됩니다.
네 번째는 여러 문서 포맷 지원입니다. 문서를 웹 페이지뿐 아니라 다른 형태로도 내려받을 수 있게 해주어서, 사용자가 오프라인에서 문서를 보고 싶을 때 별도 준비를 하지 않아도 됩니다.
다섯 번째는 미리보기 기능입니다. 문서 수정 제안이 들어왔을 때 실제로 어떻게 보일지 확인할 수 있어서, 반영해보고 나서야 잘못을 알아채는 일이 줄어듭니다.
사용법
먼저 사이트에서 계정을 만듭니다. 이때 깃허브 같은 코드 저장소 계정으로 바로 연결해 가입하는 편이 이후 과정이 훨씬 간단합니다. 저장소 목록을 자동으로 불러올 수 있기 때문입니다.
로그인하면 대시보드가 나오는데, 여기서 Import a Project(프로젝트 가져오기)를 누릅니다. 연결된 계정의 저장소 목록이 뜨고, 문서를 올릴 저장소를 고르면 됩니다.
프로젝트 이름과 기본 브랜치를 확인하는 화면이 나오는데, 이때 프로젝트 이름이 곧 문서 주소가 된다는 점을 확인하셔야 합니다. 나중에 바꾸기가 번거로우니 처음에 신중히 정하는 게 좋습니다.
그다음이 중요한 부분입니다. 저장소 안에 설정 파일(.readthedocs.yaml)이 있어야 어떤 방식으로 문서를 만들지 알려줄 수 있습니다. 이 파일이 없으면 빌드가 실패하는 경우가 많으니, 사이트가 안내하는 예시를 그대로 가져다 놓고 필요한 부분만 고치는 방식을 권합니다.
설정이 끝나면 Build Version(빌드) 버튼을 눌러 첫 빌드를 돌립니다. 진행 상황과 오류 메시지가 로그로 그대로 보이니, 실패했다면 이 로그에서 원인을 확인하시면 됩니다.
빌드가 성공하면 화면 위쪽의 View Docs 버튼으로 실제 문서 페이지가 열립니다. 이후로는 코드를 밀어 넣을 때마다 자동으로 갱신됩니다.
무료 범위는 어디까지일까요?
경계가 아주 명확한 편이라 오해할 여지가 적습니다.
커뮤니티 서비스는 오픈소스 문서 호스팅 전용이고, 오픈소스 문서는 언제나 무료입니다. 프로젝트 크기와 상관없이 무료라는 점이 명시되어 있고, 실제로 10만 개가 넘는 프로젝트가 그렇게 운영되고 있습니다. (2026년 8월 23일 확인 기준)
반대로 말하면 비공개 문서, 즉 사내 전용 문서는 커뮤니티 서비스의 대상이 아닙니다. 이 경우에는 별도의 유료 상품을 써야 합니다. 회사 내부 문서를 올릴 목적이라면 처음부터 이 점을 염두에 두셔야 합니다.
빌드 자원이나 세부 제한은 조정될 수 있으니, 정확한 조건은 사이트 내 요금 페이지에서 확인하시는 게 정확합니다.
이런 분들에게 특히 유용합니다
오픈소스 라이브러리를 공개했거나 공개할 계획인 개발자라면 사실상 표준에 가까운 선택지입니다. 사용자들이 이미 이 형태의 문서에 익숙하다는 점만으로도 값어치가 있습니다.
문서를 여러 버전으로 유지해야 하는 프로젝트 관리자에게도 잘 맞습니다. 버전별 문서를 손으로 나눠 관리하던 부담이 통째로 없어지니까요.
개인 프로젝트를 포트폴리오로 정리하려는 학생이나 취업 준비생에게도 좋습니다. 문서 주소가 있는 프로젝트는 완성도의 인상이 확연히 달라집니다.
서버를 빌릴 예산이 없는 소규모 팀이라면 매달 나가던 호스팅 비용을 그대로 아낄 수 있습니다.
장점과 아쉬운 점
장점은 문서 빌드와 배포의 완전 자동화, 버전 관리와 검색의 기본 제공, 그리고 오픈소스에 대한 항구적 무료 정책입니다. 특히 마지막 항목은 서비스 철학으로 공개되어 있어 신뢰도가 높습니다.
아쉬운 점을 정직하게 짚겠습니다. 우선 비공개 문서는 무료 대상이 아닙니다. 사내 문서를 올리려던 분에게는 결정적인 제약이 될 수 있습니다.
그리고 설정 파일을 직접 작성해야 한다는 문턱이 있습니다. 클릭 몇 번으로 끝나는 서비스에 익숙한 분이라면 첫 빌드 실패를 몇 번 겪을 수 있습니다.
또한 인터페이스와 안내 문서가 영어입니다. 한국어 화면은 제공되지 않아 오류 메시지를 영어로 읽어야 합니다.
마지막으로 무료 문서 페이지에는 광고가 노출될 수 있습니다. 무료 운영을 지탱하는 구조이니 감안하셔야 합니다.
요약
리드 더 독스는 오픈소스 프로젝트의 기술 문서를 무료로 만들어 배포해주는 전용 플랫폼입니다. 코드 저장소를 연결해두면 코드가 바뀔 때마다 문서가 자동으로 다시 만들어져 올라갑니다.
버전별 문서 관리와 문서 내 검색이 기본으로 붙어 있어, 서버를 빌려 직접 운영할 때 감당해야 했던 작업이 대부분 사라집니다. 실제로 10만 개가 넘는 오픈소스 프로젝트가 이 방식으로 문서를 운영하고 있습니다.
비공개 문서는 무료 대상이 아니고 설정 파일을 직접 써야 한다는 문턱은 있지만, 오픈소스 문서를 올릴 곳을 찾는 분에게는 매달 나가던 서버비를 0원으로 만들어주는 확실한 답이라고 할 수 있습니다.
4. 신(하나님)은 과연 존재하는가? 신이 존재한다는 증거가 있는가?
ChatGPT, 유튜브 프리미엄, 넷플릭스 구독료 80% 할인 받는 법 (클릭)
함께 보면 좋은 글
이 노트는 보도·비평·교육·연구 목적으로 작성되었습니다. 저작권 문의가 있으시면 에서 알려주세요.