[Sphinx] Sphinx 프로젝트 온라인 배포 (1)

Sphinx 프로젝트 온라인 배포 (Deploying a Sphinx project online)

 

문서화 프로젝트를 세상에 보여줄 준비가 되면 많은 옵션을 사용할 수 있다. Sphinx에서 생성한 HTML은 정적이기 때문에 HTML 문서를 작성하는 프로세스를 선택한 플랫폼에서 이러한 파일을 호스팅하는 것과 분리할 수 있다. Python을 실행하는 정교한 서버가 필요하지 않습니다. 거의 모든 웹 호스팅 서비스로 충분하다.

 

따라서 문제는 정적 HTML을 제공하는 방법 또는 위치가 아니라 소스 파일이 변경될 때마다 배포된 문서를 자동으로 업데이트하는 워크플로를 선택하는 방법이다.

 

온라인 설명서를 배포하는 데 사용할 수 있는 몇 가지 옵션에 대해 설명하고 몇 가지 배경 정보를 제공한다. 실제 부분으로 직접 이동하려면 문서 소스 게시로 건너뛸 수 있다.

 

Sphinx 친화적인 배포 옵션 (Sphinx-friendly deployment options)

 

Sphinx 문서를 호스팅할 수 있는 몇 가지 옵션이 있다. 그 중 일부는 다음과 같다.

 

1. Read Docs는 MkDocs 뿐만 아니라 Sphinx로 작성된 기술 문서 호스팅 전문 온라인 서비스이다. 버전 문서, 트래픽 및 검색 분석, 사용자 정의 도메인, 사용자 정의 리디렉션 등과 같은 여러 추가 기능이 있다. 2. GitHub Pages는 GitHub와 긴밀하게 통합된 간단한 정적 웹 호스팅이다. 정적 HTML은 프로젝트의 분기 중 하나에서 제공되며 일반적으로 소스가 다른 분기에 저장되므로 소스가 변경될 때마다 출력이 업데이트될 수 있다 (ex: GitHub 작업). 무료로 사용할 수 있으며 사용자 정의 도메인을 지원한다. 3. GitLab 페이지 GitLab Pages는 GitLab과 통합되고 일반적으로 대신 GitLab CI로 자동화 되는 GitHub Pages와 유사한 개념 이다. 4. 네틀리파이 (Netlify)는 JavaScript (소위 "Jamstack")와 같은 클라이언트 측 웹 기술로 강화된 정적 사이트를 위한 정교한 호스팅이다. 헤드리스 콘텐츠 관리 시스템과 서버리스 컴퓨팅을 지원한다. 5. 나만의 서버 (Your own server) 언제든지 자체 웹 서버를 사용하여 Sphinx HTML 문서를 호스팅할 수 있다. 더 많은 유연성을 제공하지만 더 많은 복잡성을 제공하는 옵션이다.

 

이러한 모든 옵션은 추가 기능에 대한 비용을 지불하는 옵션과 함께 비용이 없다.

 

Embracing the “Docs as Code” philosophy

 

위에 나열된 대부분의 옵션을 무료로 제공하려면 문서 소스를 공개적으로 사용할 수 있어야 한다. 또한 이러한 서비스 는 파일 컬렉션의 발전을 일련의 스냅샷 ("커밋")으로 추적하는 기술인 버전 제어 시스템을 사용할 것으로 기대한다. 소프트웨어 개발에 사용된 것과 동일한 도구를 사용하여 일반 텍스트 파일로 문서를 작성하는 관행은 일반적으로 "코드로서의 문서"로 알려져 있다.

 

오늘날 가장 인기 있는 버전 관리 시스템은 GitHub 및 GitLab과 같은 서비스의 백본인 무료 오픈 소스 도구인 Git이다. Read the Docs와 Netlify는 모두 GitHub 및 GitLab과 통합되어 있고 GitHub 및 GitLab에는 통합된 Pages 제품이 있으므로 온라인에서 문서를 자동으로 빌드하는 가장 효과적인 방법은 소스를 이러한 Git 호스팅 서비스 중 하나에 업로드하는 것이다.

 

https://www.sphinx-doc.org/en/master/tutorial/deploying.html

Appendix: Deploying a Sphinx project online — Sphinx documentation