1. Doxygen 기반의 Document 구성
기존 Doxygen 관련구성
Doxygen Getting Started (전체구조)
Code 와 Comment
Markdown 문법
Doxygen Formulas (수학공식)
Table(HTML)
Graphs 와 Diagrams (Graphviz가 별도 필요)
1.1 ESP32/ESP-IDF Doxygen 전체구성설명
ESP32의 Doxygen 구성이 잘 되어있으며, 곧바로 Github에서 hosting하는 것으로 보아 Doxygen 구성이 너무 좋아
일단 각 개별구성의 역할만 파악하기로 했다.
- ESP-IDF Document 구성 분석 전 확인사항
- Espressif에서 사용하는 Doxygen Style Guide(Code Convention)
- 문서에 필요 Package (Doxygen 이외 UML or Diagram)
- Manual의 전체설명방법 및 구성
어떻게 보면 가장 중요한 곳은 Code convention이라고 생각할 수 있으며, 코드의 가독성과 협업을 위해서
최소한으로 지켜야할 규칙이자 프로그래머의 기본매너로, 팀단위 혹은 여러사람과 협업하여 같이 일할 경우,
특히 중요하다. 하지만, 국내회사들은 크게 신경쓰지 않으며, 규칙조차 없거나, 무시되는 경우가 태반이다.
솔직히 개인적으로 그런회사들은 별로 좋아하지 않는다.
- ESP-IDF의 Doxygen 구성에 필요한 Package들
- Doxygen - http://doxygen.nl/
- Sphinx - https://github.com/sphinx-doc/sphinx/#readme-for-sphinx
- Breathe - https://github.com/michaeljones/breathe#breathe
- Document theme “sphinx_idf_theme” - https://github.com/espressif/sphinx_idf_theme
- Custom 404 page “sphinx-notfound-page” - https://github.com/readthedocs/sphinx-notfound-page
- Blockdiag - http://blockdiag.com/en/index.html
- Recommonmark - https://github.com/rtfd/recommonmark
** shpinx_rtd_theme -> sphinx_idf_theme으로 수정하여 사용
** recommonmark (Markdown 문법관련 설정, 현재 Project 중단)
ESP-IDF의 경우, 아래와 같이 Github 기반으로 Markdown 문서기반으로 작성되어 운영되어진다.
그리고, 전체 Manual 구성이 쉽게 관리하는 구조이며, 물론 ESP-IDF 같이 종합적으로 작성을 위해서 좀 더 많은 Python구성(Sphinx) 설치했겠지만,
문서작성 후 관리를 비롯하여 Web으로 쉽게 Hosting 되어지기까지 해서 너무 매력적이다.
물론 Github에서 Page를 통해 Web Host도 가능할 것이지만, 아래의 주소는 달라 정확히 어떻게 하는지 아직 모르겠다.
Github을 통해서 하는 것 같지가 않다.
ESP-IDF Manual
ESP-IDF Doxygen
GitHub 의 Sphinx
1.2 Sphinx/Breathe/Cmake/Doxygen 구성
ESP-IDF의 Doxygen구성을 이해하려면 어쩔수 없이 각 Python Package 와 각 Package의 역할과
이에 결과물 및 관련소스들의 기능을 분석을 해야 할 것 같다.
그리고, Python의 Package가 어떻게 사용되는지를 알아야 할 것 같다.
현재 ESP-IDF의 Python은 3.x가 아님 주의
- Sphinx/Breathe/Doxygen 구성
- Python의 Sphinx Package가 가장 Main으로 구성되어 문서관리 작성
- Sphinx의 Manaul은 RST or Markdown or HTML 방식으로 작성되어 관리
- 이외 소스의 API는 Doxygen으로 연결되어짐
- 아래 그림에는 없지만, Diagram 과 UML도 연결해서 할 걸로 생각
 |
| https://indico.cern.ch/event/716909/contributions/2946822/attachments/1821901/2980311/The_sphinx-breathe-doxygen_combo.pdf |
- Sphinx 의 기본설명
Python에서 제공해주는 Sphinx Package인데, 손쉽게 문서작성이 가능하며, 편할걸로 생각되어진다.
우선 RST/Markdown 으로 기본문서를 설정하여 작성하여 이를 구성한다.
- Sphinx의 Input Files 및 설정
- *.rst 파일 (Markdown 형식으로 구성)
- conf.py
ESP-IDF의 Sphinx 기본구조
각 구조를 보면, Sphinx 기반으로 ESP 내부에서 많이 고쳐서 사용하고 있음을 대충 알수 있다.
- Sphinx/Breathe/Cmake/Doxygen 종합구성사용법
- Sphinx의 부가적으로 Doxygen을 쉽게 사용하기위해서 사용하는 것으로 보임
- Breathe는 Sphinx의 확장기능으로 사용
- Cmake 와 Sphinx는 연결이 가능하여 이를 쉽게 Doxygen으로 연결해주는 것으로 보임
- 아래의 예제도 Github와 연결하여 Hosting 함
1.3 Sphinx 기반으로 작성된 사이트의 다른 예
상위 구조를 좀 더 알기 위해서 ESP32 , ESP-IDF 이외에도 이와 비슷한 구조를 가진 사이트들을 좀 찾아보았다.
- Sphinx/Breathe/Doxygen 구성 예-A
Sphinx 기반으로 구성한 사이트들이며, Doxygen 연결하여 사용한다.
Manual 구성은 보면 거의 비슷하며, 좌측이 Index 우측 Manual 구성이다.
GitHub 사이트
상위 구성된 부분은 아래의 doc에서 sphinx에서 만들어지는 것으로 추측되어지며, 손쉽게 모두 Github 기반으로 문서작성을 한다.
- Sphinx 구성 예-B
Sphinx 기반으로 구성된 사이트로 추측되어지며, 다만 Github와 연동을 찾지를 못했다.
Manual 구성을 보면 상위 거의 비슷하지만, Doxygen는 미제공한다.
1.4 ESP32/ESP-IDF Sphinx 구성분석
ESP32 역시 상위 Sphinx/Breathe/Doxygen 기반으로 구성하지만, blockdiag를 별도로 추가하여 구성하였으며,
Graphviz는 이용하지 않는 것으로 보인다.
경우에 따라 본인들이 수정하여, 사용하는 것으로 보이며, 보면 볼수록 참 세련되게 잘 구성했다.
요즘 내가 좋아하는 구성으로 Github기반으로 구성하며, 문서도 이 기반으로 하려고 한다.
- ESP-IDF Python Package Requirement
ESP32/ESP-IDF의 Python Package 구성 대충 보면 Version이 낮을 걸로 사용
- Sphinx 의 설정 (conf.py 와 *.rst)
Sphinx의 theme에 설정되어지고 설정은 conf.py 와 index.rst 구조로 구성
https://github.com/espressif/esp-idf/blob/73db142403c6e5b763a0e1c07312200e9b622673/docs/en/index.rst
- Sphinx의 index.rst 세부분석
Sphinx는 RST파일이 거의 Main으로 관리되어지며, Markdown도 지원한다.
index.rst 의 경우, 좌측 Menu구성은 index.rst의 toctree로 구성
- ESP32 Document 전구조
- build_docs.py : doxygen 을 이용하여 document 생성
- generate_chart.py : doxygen과는 관련없으며, chart 생성
Github에 Host되기 때문에 docs가 어떻게 구성이 되었는지 전체구조기반으로 보자
- ESP32 Document 설명 (Comment Style Guide)
Comment Style Guide 중심으로 다시 한번 보도록 하고 Doxygen 생성된 부분을 확인
- ESP32 Doxyfile 설정
Doxyfile 부분의 설정부분은 왜 헤더파일은 넣었는지는 나중에 다시 봐야할 것 같으며, 자동으로 *.c 파일은 되는 것으로 추측
이부분의 Python 과 같이 분석해야 할 것 같으며, 각 API Manual을 어떻게 하는지 봐야함
- Python Blockdiag 활용
Block Diagram을 손쉽게 작성하는데, 편한 것 같으며, ESP32의 경우 이를 기반으로 쉽게표현
Blockdiag 의 기본예제
blockdiag 와 sphinx 설정
- ESP32의 Blockdiag의 실사용예제들
상위 diag파일들을 아래 사이트에서 직접 구성확인
- Eng/Markdown 으로 기본구성 (*.rst)
최종결과물로 Markdown 도 호환은 되는 것으로 보이며, 이것으로 전체화면구성(index.rst)
- ESP32의 그림파일들 과 기타파일
2. ESP32/ESP-IDF Sphinx Document 와 Github Host
Github기반으로 진행되기때문에, 최종결과물을 HTML로 안해도 되는 것으로 보이며, 이를 *.rst로 구성해서 하는 것으로 보이는 것으로 추측
실제로 내가 직접 구성을 해보면서 이해해야 제대로 알것 같다.
더불어 *.rst 파일들을 보면 구성들이 재미있게 구성되어 있는데, 이에 관련된 Markdown 문법도 세부적으로 알아야 할것 같다.
특히 toctree 구성부분과 sphinx의 theme은 더 자세히 분석을 해봐야할 것 같다.
- ESP32 Github 와 Web Host (현재 추측)
- Github기반으로 Hosting 하는 것으로 생각되며, 직접 고치는 것도 허용하며 영어와 중국어만 지원가능
- PDF 다운로드도 지원가능
- docs/en/index.rst 가 Main로 연결 (여러개의 index 파일로 구성)
2.1 Github의 Host 지원기능
- 이전에 내가 Github 기반으로 Host 한 테스트 예제
- Github에서 Host를 하기위해서는 docs 폴더가 별도구성
- Setting->Pages 에서 설정한 후 Theme 도 별도 설정
- 일반적인 Github의 Theme 기반구성
index.md 기반으로 Main 구성후 별도_config.yml 설정
index.md 기반으로 Main구성 _config.yml 설정 (Github의 Theme)
- 상위와 다른점은 직접 HTML기반으로 구성
docs/index.html 기반으로 Main구성 (ESP32도 이런식으로 구성)
