6/04/2021

ReadTheDoc 의 Doc Host (Mkdoc/Sphinx)

1. RST 파일 과 Markdown

기술문서작성 흐름이 RST or Markdown 기반으로 손쉽게 작성가능하도록 변경되어져 가며,
이를 지원하는 Python Package들이 존재하는 것을 그동안 알지 못했다. 
ESP-IDF 개발환경에 관련된 문서를 분석하면서 많은 부분을 알게되었는데, 쉽게 문서작업하는 방법과 
Python 기반의 Doxygen 연결부분을 알게되었지만, 
ESP-IDF의 경우, Espressif에서 독자적으로 많이 고쳐가면서 구현한걸로 보인다. 

ESP32/ESP-IDF Sphinx 의 구성 

점점 아래의 Markup Language기반으로 기술문서가 변화되어져가며, 이는 호환성과 문서의 간결성이 중요해질 것 같다. 
다양한 보조도구들이 등장하는데, 이들도 쉬운작성법과 호환성 및 Open Source를 기반으로 하기 때문에 많이 사용되어지는 것 같다.
 
RST 파일 (Sphinx 사용)

Markdown 


1.1 Python 기반의 기술문서작성(Sphinx 와 Mkdocs) 

현재 Python 기반으로 구성된 Program은 Sphinx 와 Mkdocs기반으로 크게 두 갈래로 방향이 나뉘어 작성되어지며 가는 것으로 보인다. 
대체적 보면, Sphinx 기반으로 많이 선택해서 사용하는 것으로 보이는데, 다양한 기능 과 확장성 때문이라고 생각되어진다.

RST 과 Markdown 지원으로 문서작성가능하지만, 기반이 RST기반으로 사용한다. 
둘다 Markup Language이므로 쉽게 도표 및 테이블이 쉽게작성 가능하며, 다양한 확장패키지들을 제공하고 있어, 기능확장되어
점점 더 많은 패키지들을 제공하고 있으므로, 아래의 링크로 확인가능 

Sphinx기반으로 문서작성법
재미있는 것은 Sphinx의 Theme도 ReadTheDoc에서 제공해주고 있는데, 이 기반으로 사용하면 좋은 것 같다. 
ESP32의 경우도 이 Theme을 기반으로 별도 수정해서 사용하고 있지만, 변경해서 사용하고 있다. 


Sphinx Extension

Sphinx Extension 중 유용할 것 같은것들 

반드시 다른 ReadTheDoc Github 내부사이트의 Python requirements.txt 확인 


Markdown 기반으로 문서작성 가능하며, 다루기는 이게 더 편할걸로 생각되어진다. 
하지만, 아직 확장패키지까지 다 설치를 해보지 못하여 완벽한 비교는 못하겠지만, Sphinx 만큼의 확장패키지를 제공못하는 걸로 생각되어진다. 

Mkdocs 기반으로 문서작성법 
Python 설치해보고 기본테스트만 해봄 

만약 Sphinx와 Mkdocs를 설치해서 테스트하고자 하면, virtualenv(venv)를 사용하거나 conda를 이용하여 하도록하자.

  • Sphinx 와 Mkdocs 비교 
솔직히 RST과 Markdown의 큰 차이성은 아직 잘 모르겠으나, RST가 좀 더 많은 기능을 가진것으로 보인다.  
예를들면 RST 파일의 toctree 구성이 될 것 같다. 
두개 다 비슷한 문법으로 사용되어진다고 생각되어지지만, 다르다고 하니, 
차차 문서를 직접 작성할 경우에, 다른점들을 비교해가면서 알아보도록하자. 

1.2 Sphinx 와 Doxygen 기능확장 

Doxygen기반으로 구축하며 문서작성을 한다면,  소스에 각 함수의 설명들을 쉽게 문서화가 가능하므로 
Sphinx와 Doxygen을 연결하여 사용가능하다. 
현재 대부분 이런형식으로 기술문서들이 구성되어 사용되어지는 것 같으며, Sphinx에서 Doxygen을 이용한다면,  
Breathe를 반드시 설치한 후 사용해야하며,  이 Breathe 역할은 Doxygen 부분을 연결해주는 것이라고 한다.  
아래의 링크처럼 최종적으로 모든것이 Cmake에서 관리되도록 구성하여 최종관리를 한다. 
 
  • Sphinx/Breathe/Doxygen/Cmake 기반의 문서구성 
Cmake기반으로 가장잘 설명된 좋은 예제 인것 같으며, Doxygen도 사용할 경우 괜찮을 것 같다. 


  • Sphinx 기반의 ESP32 Doxygen 분석 
처음에 Github의 Page에서 *rst를 인식해서 Web Host 하는 줄 알았다. 
ReadTheDoc 기반으로 구성되어진다는 것을 알게되었으며, 모든 것이 쉽게 풀리게되었다. 
앞으로 가급적 ReadTheDoc를 이용하도록 하겠다. 


물론 Doxygen까지 필요 없다면, 쉽게 Mkdocs구성도 괜찮을 걸로 생각되어진다. 


2. ReadTheDocs 의 Host 사용법

이 사이트는 이전에 Sphinx 기반으로 문서작성법을 알아보다가 알게된 사이트이며, 상위 Sphinx와 Mkdocs를 둘다 지원한다. 
Git사이트의 Web host 전문사이트라고 생각하면 되겠으며, Github에서 Page를 HTML기반으로 설정하면 되겠지만, 너무 불편하다.
그리고, Github의 Page Web Host는 한계가 있는것 같다. 

  • ReadTheDocs의 Doc Host 기능 
  1. Git(Github/Gitlab) 사이트에서 작성된 Sphinx or Mkdocs 기반으로 문서작성 
  2. Git 사이트에서 작성된 문서를 ReadTheDoc로 Import  
  3. .readthedocs.yml 설정기반으로 기본 Python 환경설정
  4. Git사이트의 Python의 requirements.txt 부분 확인 (ReadTheDoc는 가상환경에 설치)
  5. Sphinx or Mkdocs 기반으로 빌드하여, HTML로 환경구축
  6. Build에 문제없다면, 이를 Web Host 진행완료 

  • ReadTheDoc의 기본사용법과 특징 

  • ReadTheDocs (Sphinx/Mkdocs)
Sphinx 와 Mkdocs 둘자 지원가능 

  • .readthedoc.yml 
Git 사이트내에 반드시 존재해야하며, 이 설정값 기반으로 Python 환경구축하므로 반드시필요 

  • Github 의 Page 사용법 
만약 ReadtheDocs를 사용하지 않고 Github에서 host하고자 하면, HTML로 만들어서 이곳에서 설정 이부분 이전에 설명 



2.1 ReadTheDocs 의 사이트종류 

ReadTheDocs 사이트는 두개로 나뉘어지며, Community 와 Business Version으로 나뉘어지며, 사이트도 다르다 

  • Community ReadTheDocs 
무료로 사용가능하며 Custom Domain 지원가능도 가능하며, 오픈소스들위해서 무료로 제공해주고 있다
다만 광고를 봐야하며, 광고를 삭제하고자 하면 돈을 지불해야함 

  • Business ReadTheDocs
Business 용으로 유료버전으로 기능을 제공을하는데, 현재 사용해보지는 못해서 아래 지원기능만 링크 

Business ReadTheDocs 특징과 설명 
Google의 G Suit와 도 연결해서 사용가능한것 같다 

  • ReadTheDocs의 Custom domain 설정 
아래와 같이 쉽게 ReadTheDoc Community 에서 쉽게 Host가 가능하며, Community도 Custom Domain을 지원한다.


2.2 ReadTheDocs 와 Github 연결방법

나의 경우, Github 와 ReadTheDocs Comminity로 연결하여 아래와 같이 구성하였다. 

사용법은 어렵지 않으며, 우선 가입후 Github/Gitlab등 Git사이트와 연결을 하도록하자. 
이부분은 WebHook부분을 보면될 것이며, Github기반으로 가입하면 별도의 설정은 필요없다. 

  • ReadTheDocs 사이트
본인설정확인 
 
  • Github의 Setting Webhook 확인 



Integrations 부분은 설정만 확인했지만, Github에서 Automation 기능은 아직 설정해보지 못함
(Github application을 별도로 설치진행해야 할 것 같음)

ReadTheDocs Host 관련문서 및 Github와 연결방법  



2.3 ReadTheDocs의 Build 방법  

  • ReadTheDoc의 Build Example 
Build를 진행하면 시간이 상당히 많이 걸리며, 아래와 같이 쉽게 Build 과정을 볼수 있다.



Build가 Fail이 되면 관련부분 을 분석해서 보도록하며, 상위 설정파일(.readthedoc.yml) 같이 봐야하며, 
ReadTheDoc Server에서도 VirtualEnv기반으로 구성하며, 관련설치부분을 자세히 보도록하자.


Build가 된후 ViewDoc를 보면 되며, 관련링크로 Host가 진행됨 



사용후 가장 좋은 점 바로 수정 Github에서 수정가능하며, 이를 Github에서 확인이 가능하다. 


3. ReadTheDocs의 나의 Host예제   

상위와 같이 쉽게 빌드하여, 나도 아래와 같이 쉽게 ReadTheDocs를 이용하고 있으며, 
아래와 같이 간단하게 Examples들을 링크한다. 

  • Github 기반의 ReadTheDoc Host TEST Example 1
ReadTheDocs에서 제공해주는 Github Template을 가져와서 이를 Build후 Web Host 진행

ReadTheDoc의 WebHost Ex.1

ReadTheDoc의 Github 

  • Github 기반의 ReadTheDoc Host TEST Exampe 2 
현재 ReadTheDocs 관련문서도 Github기반으로 작성되어있으므로, 이를 Github에서 Fork를 하고 가져와서 
이를 ReadTheDocs로 가져온 후 Build 후 Web Host 진행 

ReadTheDoc의 WebHost Ex.2 

ReadTheDoc의 Github 


3.1 ReadTheDoc를 이용한 다른사이트의 예 

여러 사이트를 보면, Doxygen은 옵션으로 많이 사용하며, Doxygen 필요성도 크게 의문도 들기도한다. 
함수의 API의 설명과 관계도를 자세히 보고자 한다면 필요하겠다 (특히 , C++, Java)

나의 개인생각으로는 Doxygen까지 필요 없다면, Mkdocs를 이용해도 괜찮을 것 같다. 
다만, 다른 사이트들을 보면 거의 Sphinx 위주로 구성되어 작성되어지는 것을 볼 수 있다. 
개인생각으로는 확장성때문일 걸로 생각되어진다. 


ReadTheDoc Hosting 설정(Sphinx) 

  • Godot Docs (Github 연결)
추후 사용할 시 반드시 참고해야하며, 메뉴와 설정이 다양하게 구성되었으며, Sphinx 이용 

  • ESP-IDF (Github 연결)
ESP-IDF로 자세히 Manual을 사용하며, Sphinx 기반으로 작성 

  • Verilog-To-Routing (Github 연결)
오직 문서 구성과 방식 보며, 간단하며, 역시 Sphinx 기반으로 작성 


기타 
댓글 없음 :
Tags: , ,
피드 구독하기: 글 ( Atom )