readthedocs

readthedocs는 documents나 get started에서 많이
나오는 설명서를 만드는 일종의 틀이다.

근데 간단한 설명서를 만드는걸로는 readthedocs의 일부 기능한 사용하는것이며 굳이 이걸 사용할 필요가 없다. 뒤에서 나오는 sphinx나 markdown만 사용해도 목표달성한다. readthedocs는 설명서의 버전을 관리하고 각 버전별로 설명서를 빠르게 전환해서 볼 수 있게 만들어둔 기능에 초점이 맞쳐져있다. 그래서 readthedocs는 다양한 소스버전관리 프로그램들에서 사용이 가능하고 이를 통해서 버전을 관리한다.

일단 기본적으로 설명서가 변경된다는 것은 사용방법이 달라졌다는 의미가 된다는 것에 주목해야한다. 하나의 프로그램은 그 기능이 바뀌고 없어지며 변화하고 추가되면서 그 사용법 또한 달라질 것이다. 근데 생각해보면 이상하다. 기능이 업그레이드되면 업그레이드해서 쓰면 되는데 과거의 기능에 관한 내용을 굳이 볼 수 있게 만들어 두었다. 아직까지도 예전 버전을 사용하는 사람이 있기때문있으며 모든 사람들이 항상 최신버전을 사용하지는 않기 때문이다. 이용하는 또 다른 방법도 있다. 과거의 기능의 문서가 아닌 다른 제품별로 다른 설명서를 만드는 것도 가능하다. 전자제품 홈페이지에서 제품을 검색하고 다운로드에서 설명서를 받지 않고 설명서를 만들수도 있다.

readthedocs의 사용의 간단한 흐름은 이렇다. readthedocs계정과 github 계정이 필요하다. 그리고 버전관리가 되고 있는 폴더가 하나 있다. 이 폴더에 설명서를 만들어둘 것이니까 원하는 문서를 생성하고 commit을 하면 되는데 매 commit마다 commit이 되었다는 것을readthedocs가 알 수 있도록 git hook를 걸어주면 된다. 그러면 매 commit마다 readthedocs가 눈치채고 version build를 자동으로 한다. 즉, 원하는 commit에다가 tag를 걸거나 브랜치명을 정해주면 곧 그것이 readthedocs에서 선택가능한 버전이 되는 것이다. 미리 사용해봐서 어느정도 익숙하면 무슨말인지 이해를 하겠지만 뭔가 좀 복잡해 보이기도 한다. 먼저 github 과 git에 대한 이해가 필요하다. commit은 현재상태를 저장하는것이고 hook는 commit 전/후 또는 push 전/후에 어떤 일을 할지 스크립트로 만들어두고 자동으로 실행되게 하는 것이라고 이해하면 된다. 그리고 문서 작성에서 많이 사용하는 sphinx나 markdown에 대해서 알고 있어야 한다. sphinx나 markdown을 쓰도록 readthedocs에서 가이드를 하고 있다.

readthedocs 하나 쓰자고 git도 알고 hook도 알아야하고 sphinx나 markdown같은 것들도 알아야하니 여간 번거로운게 아니다. 거기에다가 readthedocs 설정을 위한 yaml 파일과 sphinx나 markdown을 위한 yml파일도 작성을 해야 최종적으로 적용이 되니까 피로도가 꽤 높다. 그럼에도 불구하고 쓸 사람은 필요해서 배워서 쓰다는 세계라 필요하고 도움이 된다면 써야한다.

push를 하게되면 readthedocs가 버전을 자동으로 빌드하게 되는데 이때 .readthedocs.yaml 파일을 먼저 찾는다. 여기에 정의된 내용을 보고 sphinx인지 markdown인지 구분하며 그리고 python에 필요한 것도 정의가 필요하면 해둔다. yaml파일을 보고 문서가 markdown이라면 이젠 mkdocs.yml 파일을 찾는다. 이 파일에 정의된 문서의 주소나 형태 구조등을 파악해서 문서를 표현하게 된다.

commit - push - hook - readthedocs버전자동빌드시작 - yaml파일 - yml 파일 - build - 종료

다행인것은 readthedocs에서 프로젝트를 생성하면 github 레포지토리를 아주 쉽게 연결할 수 있도록 제공하며 연결되면 자동으로 webhook가 하나 생성되어서 특별히 할건 없다. yaml파일과 yml파일 정의해서 만들고 정의한대로 문서파일 만들어두면되고 이것을 commit push 하면 만들어지는 것이다. 같은 브랜치에서 계속 commit을 하면 브랜치명은 바뀌지 않아서 readthedocs에서는 버전별 문서를 볼 수 없으니 feature 브랜치를 버젼별로 분기 시키던가 아니면 같은 브랜치라도 원하는 commit을 checkout해서 tag를 달고 해당 tag를 push하면 tag도 하나의 문서버전으로 사용된다.