레이블이 DevOps-Doxygen인 게시물을 표시합니다. 모든 게시물 표시
레이블이 DevOps-Doxygen인 게시물을 표시합니다. 모든 게시물 표시

8/11/2023

Mkdoc 와 Github 문서정리

1. Mkdocs 

이전에 Sphinx 와 Mkdocs 기반으로 환경을 구축하여 간단하게 테스트를 한적이 있는데, 
Mkdocs만으로 쉽게 Github의 Markdown 문서를 관리하는 법을 간단히 소개한다. 

이유는 Mkdocs는 Markdown 으로만 사용하기 때문에 Github와 더 잘 어울린다. 
다만 아쉬운것은 Sphinx에 비해 Plugin이 좀 떨어질 뿐이다. 

  • ReadTheDoc (Mkdocs/Sphinx 둘 다 지원)
ReadTheDoc 사용법 및 Sphinx 와 Mkdocs 비교 (Doxygen 기본 사용법)

  • Mermaid.JS 사용예제
Github에서는 이미 Markdown에 mermaid를 제공하지만, 아래와 같이 Mermaid.js로 해도됨


  • 기본설치 및 테스트 진행
가급적 Linux 기반으로 설치하도록 하며, Window에서는 WSL를 통해서 하자  
$ pip install mkdocs
$ sudo apt install mkdocs 
$ mkdocs new mkdocs-project
$ cd mkdocs-project
$ ls docs mkdocs.yml $ cat mkdocs.yml #설정확인 site_name: My Docs $ mkdocs serve # 에러발생하여 아래 Package Version 변경으로 해결 INFO - Building documentation... INFO - Cleaning site directory INFO - Documentation built in 0.08 seconds INFO - [16:11:08] Watching paths for changes: 'docs', 'mkdocs.yml' INFO - [16:11:08] Serving on http://127.0.0.1:8000/ INFO - [16:11:11] Browser connected: http://127.0.0.1:8000/ INFO - Shutting down... $ mkdocs build # site에 webpapage 와 xml 생성확인 $ mkdocs build INFO - Cleaning site directory INFO - Building documentation to directory: /home/jhlee/project/mkdocs-project/site INFO - Documentation built in 0.03 seconds



1.1 Mkdocs PDF 배포 

아래와 같이  mkdocs-with-pdf를 별도 설치진행 
$ pip install mkdocs-with-pdf 

$ vi mkdocs.yml  #plugins 추가 pdf 
site_name: My Docs
plugins:
    - with-pdf

$ mkdocs build  # PDF 파일 과 HTML 파일 생성  
INFO     -  Cleaning site directory
INFO     -  Building documentation to directory: /home/jhlee/project/mkdocs-project/site
INFO     -  Number headings up to level 3.
INFO     -  Generate a table of contents up to heading level 2.
INFO     -  Generate a cover page with "default_cover.html.j2".
INFO     -  Converting  alignment(workaround).
INFO     -  Rendering for PDF.
INFO     -  Output a PDF to "/home/jhlee/project/mkdocs-project/site/pdf/document.pdf".
INFO     -  Converting 1 articles to PDF took 0.7s
INFO     -  Documentation built in 0.70 seconds

$ tree      # tree 명령어로 전체구성 다시 확인 
.
├── docs                # docs 밑에, Markdown 구성하여 문서 구성 , 이는 Github에서 호환사용가능
│   └── index.md          # 기본 문서확인
├── mkdocs.yml             # 상위 설정확인
└── site                # mkdocs build 결과 (HTML, PDF)             
    ├── 404.html
    ├── css
    │   ├── base.css
    │   ├── bootstrap.min.css
    │   └── font-awesome.min.css
    ├── fonts
    │   ├── fontawesome-webfont.eot
    │   ├── fontawesome-webfont.svg
    │   ├── fontawesome-webfont.ttf
    │   ├── fontawesome-webfont.woff
    │   └── fontawesome-webfont.woff2
    ├── img
    │   ├── favicon.ico
    │   └── grid.png
    ├── index.html
    ├── js
    │   ├── base.js
    │   ├── bootstrap.min.js
    │   └── jquery-1.10.2.min.js
    ├── pdf
    │   └── document.pdf
    ├── sitemap.xml
    └── sitemap.xml.gz


mkdocs-with-pdf


1.2 CHM (Window HTML 설명서)

chm파일은 Window에 주로 API 설명서를 구성하기 위해서 예전에 많이 사용했다. 

  • chm 파일 viewer 설치  (WSL 설치가능, Linux 지원)
sudo apt-get install xchm 

상위를 실행시키면 쉽게 Viewer 확인 


  • HTML -> CHM 파일 생성 방법 링크 
다 확인해보지 않고 링크만


1.3 mkdocs 문제사항 정리 

Linux에서는 거의 발견못했는데, 주로 Window 기반의 WSL에서 실행했을 경우 발생하였다.  
원인을 보면, 버전의 호환성문제로 각 버전을 맞춰 재설치를 진행

  • mkdocs serve 에러문제 
 AttributeError: 'zipimport.zipimporter' object has no attribute 'exec_module'
$ pip install markdown==3.2.2  # 

 AttributeError: 'EntryPoints' object has no attribute 'get
$ pip install importlib-metadata==4.13.0   # (5.0.0->4.13.0)

  • mkdocs build (plugin)에러문제 
Window에서 실행할 경우 발생 
 OSError: cannot load library 'gobject-2.0-0': error 0x7e.  Additionally, ctypes.util.find_library() did not manage to locate a library called 'gobject-2.0-0' 

보통 Doxygen을 사용하면, chm file을 많이 사용하는데, Linux에서도 아래와 같이 볼수는 있다.


2. mkdocs 쉬운구성환경 

  • Mkdocs 사용방법정보 
모든정보가 다 이곳에 있어, 간단히 여기서 정리끝날꺼 같다.   


Github 와 연동 예제 


현재 나의 경우, Sphinx 보다는 mkdocs가 좀 더 Github와 Markdown으로 잘되어 이게 더 편한 것 같다. 
설정이야, 본인 theme 부터 변경해서 차근차근사용하면 될꺼 같다. 

8/04/2021

Sphinx 기반의 문서정리2 (Doxygen)

1. Sphinx 기본사용법 


Sphinx 기본설치 및 기본사용법 
문서를 처음 5월/6월에 작성했으나, 너무 길어져서 확장하여 8월 분할작성 

Sphinx기반의 ReadTheDoc Hosting
ReadTheDoc Hosting 및 관리가 쉬워서 개인이라면 이방법을 강력추천

Sphinx 와 Github를 연결해보고 사용하겠다고 여러방법으로 테스트 해봤지만, 
가장좋은 것은 현재 ReadtheDoc 사이트에서 Hosting하는게 가장편한 것으로 보인다.  

1.1 Sphinx extension 확장사용 

요즘 Markdown File이 대세이므로, RST파일과 Markdown를 동시에 같이 사용하도록 기능을 확장하도록하자. 
기존에는Markdown은 recommonmark기반으로 사용했다고 하는데, 
myst가 이를 호환해준다고 하고 Sphinx 사이트에서도 이걸로 거의 권장하는 것 같다. 
그리고, 가장 큰 이유는 Github와 호환성때문이다. 


  • markdown 과 mermaid 관련설치
myst_parser만 사용진행 (recommonmakr는 생략사용법은 생략)
(py38-sphinx) $ pip3 install myst_parser
(py38-sphinx) $ pip3 install sphinxcontrib-mermaid  // 옵션이며, extensions 씨 필요없다면 삭제  (간단한 diagram 사용) 

  • mermaid 기본사용법
Mermaid는 Diagram Tool로 오래전부터 Doxygen과 같이 많이 사용되어진  프로그램으로, 가장 많이 사용되는 Tool 이다. 
최근 Github에서도 지원가능하므로, 알아두도록하자 


  • Markdown 관련설정변경 
Markdown 기반으로 하기 위해서 아래와 같이 설정을 변경
(py38-sphinx) $ vi conf.py

# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = [
        'sphinx.ext.autodoc',      # autodoc 안에 automodule 도 포함
        'sphinx.ext.autosummary',  # 현재미사용
        'myst_parser',            # Markdown을 위해서 사용
        'sphinxcontrib.mermaid',  # Mermaid Diagram을 위해서 사용  
]

# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']

# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
# This pattern also affects html_static_path and html_extra_path.
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']

## 옵션으로 markdown 안에 ::: 되는 것을 동작되기 위해서 설정 RST와 같이 사용가능할것 같음 
## :::{note}
## And here's a note with a colon fence!
## :::
myst_enable_extensions = [
  "colon_fence",
]

## Source Suffix 설정 (rst,md) 
source_suffix = {
    '.rst': 'restructuredtext',
    '.txt': 'restructuredtext',
    '.md': 'markdown',
}


Sphinx-markdown 설치 및 설정 

  • Markdown 예제구성
일반 Markdown이 아닌 RST에서도 사용가능한 기능으로 확장 및 이외 diagram 추가
class에 warning/note/이외 다양한 rst directive 추가가능    
(py38-sphinx) $ vi test1.md
## TEST MD 

Markdown 에서 RST의 directive를 사용해보자  

```{admonition} Here's my note
:class: note

Here's my admonition content 
```

```{admonition} TEST Title
:class: warning

Here's my admonition content 
```

:::{note}
상위에서 설정한 colon fence! 기능 ㅋㅋㅋ
:::


mermaid 사용법임 아래 링크 참조
```{mermaid}
sequenceDiagram
  participant Alice
  participant Bob
  Alice->John: Hello John, how are you?
  loop Healthcheck
      John->John: Fight against hypochondria
  end
  Note right of John: Rational thoughts <br/>prevail...
  John-->Alice: Great!
  John->Bob: How about you?
  Bob-->John: Jolly good!
```
Markdown에서 상위 directive 사용법 

  • Markdown 관련 주의사항
  1. markdown의 # 와 ## 와 ###에 따라 계층이 나누어지므로 조심해서 사용
  2. markdown 외부 Link (http) 동작확인
  3. markdown 내부 Link는 동작확인 (HTML로 자동변경)
  4. markdown 내부 title 링크가 제대로 동작안됨 (*.md->*.html로 변경안됨)

  • index.rst의 재구성 (Markdown 사용)
Markdown을 추가하여 index를 재구성한 후 다시 확인 
(py38-sphinx) $ vi index.rst
.. toctree::
   :maxdepth: 3
   :caption:  Table of Contents
   :numbered:
   
   intro
   test1.md   
   mytest/testa.md
   mytest/testb.md   

(py38-sphinx) $ make clean  //삭제 후 진행 
(py38-sphinx) $ make html   //_build/html/index.html 확인 

index.rst 의 toctree 설정구성 

  • Markdown 상위 결과확인 (Mermaid)
테스트 용으로 Github(Mermaid 지원) 일단 기본으로 동작확인




Github 기반으로 아래와 같이 구성 후 간단히 테스트만 해봤지만, Github의 docs/ 내부는 세부적으로 연결해줘야하는 것 같다.

(py38-sphinx) $ vi index.rst   //Github일 경우 아래 구성으로 구성후 기본테스트만함(불필요한 index 및 다 지움)
.. toctree::
   :maxdepth: 3
   :caption:  Table of Contents
   :numbered:
   
   README.md
              
(py38-sphinx) $ make clean  //삭제 후 진행 
(py38-sphinx) $ make html   //_build/html/index.html 확인 

1.2 Sphinx 의 Output 변경 (Latex/Others) 

HTML 이외의 Output은 구성은 어떻게 되는 지 궁금해서 일단 테스트 진행 
하지만 테스트 결과 HTML만 괜찮은 걸로 보임 

  • 관련 Tool 설치 
(py38-sphinx) $ sudo apt-get install -y latexmk //latexmk 필요   
(py38-sphinx) $ sudo apt-get install texlive-full  //texlive  필요   

  • Latex 설정변경 
Letex 관련설정하여 테스트만 해보고 괜찮게 나오는지만 파악 
(py38-sphinx) $ vi conf.py   // Latex 관련설정추가   

# -- Options for LaTeX output ------------------------------------------------
latex_engine = 'xelatex'
latex_elements = {
    # The paper size ('letterpaper' or 'a4paper').
    #
    'papersize': 'a4paper',

    # The font size ('10pt', '11pt' or '12pt').
    #
    'pointsize': '10pt',

    # Additional stuff for the LaTeX preamble.
    #
    'preamble': '',

    # Latex figure (float) alignment
    #
    'figure_align': 'htbp',


    # kotex config
    'figure_align': 'htbp',

    'fontpkg': r'''
\usepackage{kotex}
''',
} 

Sphinx Latex 관련설정 및 Font 설정 (출처)
  • Sphinx Builder 로 Output 변경 
(py38-sphinx) $ make latexpdf   // Latex로 출력  
(py38-sphinx) $ make epub   // epub로 출력  
(py38-sphinx) $ make man   // man로 출력  
(py38-sphinx) $ sphinx-build --help  //sphinx-build 사용법확인

일단 한글은 제대로 안되었는데, PDF 파일 뿐만 아니라 다른 Output도 구성이 너무 좋지 않음  

Sphinx의 다양한 output 지원
HTML를 빼고 Theme 및 구성이 제대로 되지 않아 거의 사용안할 듯 


2. Sphinx 와 doxygen 연결  

  • Sphinx 기반의 Doxygen 구성이해(필독)
Python Sphinx 기반의 Doxygen 구성분석 및 필요 Package들 파악 
toctree 예제 및 ESP-IDF이 구성을 자세히 이해할수가 있음 


2.1 ESP32의 Sphinx 와 doxygen 테스트

ESP의 Sphinx가 너무 잘 구현되어있어서, 그것을 그대로 한번 따라 해보려고 했는데, 
버전이 너무 낮아서 아래는 진행하지 않기로 했다. 
나와 같이 삽질하는 사람이 있을 거 같아 기록으로만 남김. 
  • ESP32 의 Sphinx 와 doxygen 사용
sphinx와 doxygen을 TEST을 위해서 기존의  ESP관련부분 참조 
(py38-sphinx) $ cp -a ~/esp/esp-idf/docs espdocs   //esp의 doc를 doxygen으로 만들예정 

(py38-sphinx) $ cd espdocs   //esp의 doc를 doxygen으로 만들예정 

(py38-sphinx) $ pip3 install breathe           //sphinx 와 doxygen 사이의 bridge 역할한다고 함

(py38-sphinx) $ cat requirements.txt 
# This is a list of python packages used to generate documentation. This file is used with pip:
# pip install --user -r requirements.txt
#
# matplotlib is currently required only by the script generate_chart.py
matplotlib==3.3.1 ; python_version>="3"
matplotlib==2.0.1 ; python_version=="2.7"
cairosvg==2.5.1 # required by sphinxcontrib-svg2pdfconverter[CairoSVG]
sphinx==2.3.1
breathe==4.14.1
sphinx-copybutton==0.3.0
sphinx-notfound-page
sphinxcontrib-blockdiag==2.0.0
sphinxcontrib-seqdiag==2.0.0
sphinxcontrib-actdiag==2.0.0
sphinxcontrib-nwdiag==2.0.0
sphinxcontrib-wavedrom==2.0.0
sphinxcontrib-svg2pdfconverter[CairoSVG]==1.1.0
nwdiag==2.0.0
recommonmark
future>=0.16.0 # for ../tools/gen_esp_err_to_name.py
sphinx_selective_exclude==1.0.3
sphinx_idf_theme==0.2.2

(py38-sphinx) $ pip3 install -r requirements.txt   //절대 실행하지 말자. 버전에 전부 너무 아래이며 오래된 package 사용 (venv 다시 설치, 젠장) 
(py38-sphinx) $ python3 build_docs.py   //확실히 기존의 sphinx 구조와 다르며 필요한 것은 다 직접구현 
IDF_PATH로 문제발생 

상위부분은 실패했으며, 분석해서 하려고 했으나 내가 원하는 방향하고 다른 것 같아 여기서 멈춘다 
상위 Sphinx는 ESP-IDF의 Sphinx인데, 너무 오래된 Version의 Sphinx를 사용하고 있다. 
그리고 부족한 부분들의 거의 직접구현하고 연결해서 사용하는 것으로 보인다. 

상위를 진행하면 전부 Version이 Downgrade 되므로 주의 
귀찮아서 기존의 venv를 지우고, 다시 venv 기반으로 sphinx 재설치
상위는 하지말도록하자. 

2.2  Doxygen 과 Sphinx를 Breath 연결구성 

  • ESP Exampel을 이용하여 Doxygen 생성 
일단 C소스가 필요하니, ESP Example을 가져와서 이 기반으로 doxygen을 생성하자. 
관련 package들은 우선 설치를 진행 
(py38-sphinx) $ sudo apt install doxygen     //doxygen 이 없어서 설치 
(py38-sphinx) $ sudo apt install doxygen-latex doxygen-doc  //doxygen 관련 package 설치
(py38-sphinx) $ doxygen-gui graphviz   //오래전부터 graphviz랑 같이사용 

(py38-sphinx) $ mkdir doxydocs   //venv로 이미 설치진행완료 

(py38-sphinx) $ cd doxydocs 

(py38-sphinx) $ cp -a ~/esp/esp-idf/examples  .    //esp32 examples 소스만 가져옴 

(py38-sphinx) $ cmake -version
cmake version 3.16.3

(py38-sphinx) $ doxygen -v
1.8.17 

(py38-sphinx) $ doxygen -g   //Doxyfile 생성 

(py38-sphinx) $ vi Doxyfile    //생성된 Doxyfile 의 설정들을 변경해주자 (소스위치/XML/기타등등)
PROJECT_NAME           = "ESP Sample"
INPUT                  = ./examples 
RECURSIVE              = YES
GENERATE_XML           = YES

(py38-sphinx) $ doxygen       //Doxyfile 기준으로 Doxygen 실행  

(py38-sphinx) $ ls    //html 와 xml 생성확인 HTML을 우선확인해보자  
Doxyfile  examples  html  latex   xml

  • 생성된 Doxygen 구성확인 
  1. 상위 HTML에서 쉽게 생성된 Doxygen 파일 확인 가능 (index.html)
  2. Latex에서는 PDF 파일 확인가능 
  3. XML은 breathe를 위해 사용예정 

나의 경우 Doxygen 자료가 없어서 ESP의 Sample 이용 



  • Sphinx 와 Breathe 기반으로 Doxygen 연결 
Breathe를 기반으로 Doxygen XML을 이용하여 Sphinx 와 연결 

(py38-sphinx) $ mkdir docs
(py38-sphinx) $ cd docs

(py38-sphinx) $ pip3 install breathe           //sphinx 와 doxygen 사이의 bridge 역할한다고 함

(py38-sphinx) $ sphinx-quickstart     //sphinx start 실행  

(py38-sphinx) $ vi conf.py 
## Extension을 위해서 설정 
import os
import sys
sys.path.insert(0, os.path.abspath('.'))

## 만약 Shell Script 형식으로 사용하고자 하면 사용 
#import subprocess
#subprocess.call('make clean', shell=True)
#subprocess.call('cd ../../doxygen ; doxygen', shell=True)

## breathe 설정으로 상위생성된 XML 연결  
breathe_projects = { "ESP Sample": "../xml/" }
breathe_default_project = "ESP Sample"


## Extension에 breathe 추가 및 기타 추가 (필요 없다면 빼자) 
extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.doctest',
    'sphinx.ext.mathjax',
    'sphinx.ext.viewcode',
    'sphinx.ext.imgmath',
    'sphinx.ext.todo',
    'breathe',
]

html_theme = 'sphinx_rtd_theme'

(py38-sphinx) $ vi index.rst      // 아래와 같이 설정하면 시간 엄청 오래걸리며 이상하게 생성됨  
.. toctree::
   :maxdepth: 2
   :caption: Contents:

.. doxygenindex::
.. doxygenfunction::
.. doxygenstruct::
.. doxygenenum::
.. doxygentypedef::
.. doxygenclass::

(py38-sphinx) $ make html

  • 결과확인 
비록 ESP의 Sample을 가지고 했지만, 아래와 같이 Doxygen 형태로 나옴




(py38-sphinx) $ vi test0.rst      // @breif 가 있는 함수를 찾아 함수명으로 추출  
C  Functions
-------------

.. doxygenfunction:: ws2812_rmt_adapter

(py38-sphinx) $ vi index.rst      // 확인  
.. toctree::
   :maxdepth: 2
   :caption: Contents:

   test0   
   
(py38-sphinx) $ make html

breathe 기본사용법 


2.3 기타 Doxygen 테스트 

  • Cmake 와 Doxygen 설치 및 확인 

$ cmake -version
cmake version 3.16.3

$ sudo apt install doxygen
$ sudo apt install doxygen-latex doxygen-doc doxygen-gui graphviz 
$ sudo apt install xapian-tools

$ doxygen -v
1.8.17 

https://github.com/jacking75/examples_CMake
git clone https://github.com/ttroy50/cmake-examples.git
//git clone https://github.com/sinairv/Cpp-Tutorial-Samples.git
//$ git clone https://github.com/googleapis/google-cloud-cpp
//$ git clone https://github.com/GoogleCloudPlatform/cpp-samples

https://github.com/GoogleCloudPlatform/python-docs-samples
https://github.com/GoogleCloudPlatform/nodejs-docs-samples
https://github.com/GoogleCloudPlatform/ai-platform-samples


https://breathe.readthedocs.io/en/latest/directives.html#doxygenstruct

$ mkdir docs
$ cd docs
$ doxygen -g   //Doxyfile 생성 

$ vi Doxyfile
PROJECT_NAME           = "Google CPP Sample"
INPUT                  = ../cpp-samples
RECURSIVE              = YES

$ doxygen         // 생성확인


$ cd ..
$ ls 
cpp-samples  docs  py38-sphinx

$ find . -name CMakeLists.txt
./cpp-samples/gcs-fast-transfers/CMakeLists.txt
./cpp-samples/iot/mqtt-ciotc/CMakeLists.txt
./cpp-samples/cloud-run-hello-world/CMakeLists.txt
./cpp-samples/populate-bucket/CMakeLists.txt
./cpp-samples/speech/api/CMakeLists.txt
./cpp-samples/gcs-indexer/CMakeLists.txt


$ vi CMakeLists.txt
cmake_minimum_required (VERSION 3.8)
project ("Sphinx Example")
add_subdirectory ("Cpp-Tutorial-Samples")
add_subdirectory ("docs")

$ vi docs/CMakeLists.txt
find_package(Doxygen REQUIRED)

#This will be the main output of our command
set(DOXYGEN_INDEX_FILE ${CMAKE_CURRENT_SOURCE_DIR}/html/index.html)

add_custom_command(OUTPUT ${DOXYGEN_INDEX_FILE}
                   DEPENDS ${CAT_CUTIFIER_PUBLIC_HEADERS}
                   COMMAND ${DOXYGEN_EXECUTABLE} Doxyfile
                   WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}
                   MAIN_DEPENDENCY Doxyfile
                   COMMENT "Generating docs")

add_custom_target(Doxygen ALL DEPENDS ${DOXYGEN_INDEX_FILE})

$ vi docs/Doxyfile.in
#...
INPUT = "@DOXYGEN_INPUT_DIR@"
#...
OUTPUT_DIRECTORY = "@DOXYGEN_OUTPUT_DIR@"
#...

$ vi docs/CMakeLists.txt
find_package(Doxygen REQUIRED)

set(DOXYGEN_INPUT_DIR ${PROJECT_SOURCE_DIR}/cpp-samples)
set(DOXYGEN_OUTPUT_DIR ${CMAKE_CURRENT_BINARY_DIR}/docs/doxygen)
set(DOXYGEN_INDEX_FILE ${DOXYGEN_OUTPUT_DIR}/html/index.html)
set(DOXYFILE_IN ${CMAKE_CURRENT_SOURCE_DIR}/Doxyfile.in)
set(DOXYFILE_OUT ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile)

#Replace variables inside @@ with the current values
configure_file(${DOXYFILE_IN} ${DOXYFILE_OUT} @ONLY)

file(MAKE_DIRECTORY ${DOXYGEN_OUTPUT_DIR}) #Doxygen won't create this for us
add_custom_command(OUTPUT ${DOXYGEN_INDEX_FILE}
                   DEPENDS ${CAT_CUTIFIER_PUBLIC_HEADERS}
                   COMMAND ${DOXYGEN_EXECUTABLE} ${DOXYFILE_OUT}
                   MAIN_DEPENDENCY ${DOXYFILE_OUT} ${DOXYFILE_IN}
                   COMMENT "Generating docs")

add_custom_target(Doxygen ALL DEPENDS ${DOXYGEN_INDEX_FILE})

$ cmake -Btest
$ cmkae --build test
$ cmake CMakeLists.txt

$ vi cpp-samples/CMakeLists.txt
cmake_minimum_required (VERSION 3.8)
project ("Google Sample")

add_subdirectory ("gcs-fast-transfers")
add_subdirectory ("iot/mqtt-ciotc")
add_subdirectory ("cloud-run-hello-world")
add_subdirectory ("populate-bucket")
add_subdirectory ("speech/api")
add_subdirectory ("gcs-indexer")



$ sudo apt-get install lynx    // HTML viewer로 설치했으나, 너무 좋지않아 필요없음 


bazel 사용법


Github Page 설정관련 (Web 관련부분)

RST 와 Markdown

Github 기반으로 Technical 관련문서를 만드는 사이트 

Github기반으로 Sphinx로 이용하여 문서만드는 예제 


8/01/2021

Sphinx 기반의 문서정리-1

1. Sphinx 설치 

  • Python venv기반으로 구성 
호환성문제로 virtualenv를 사용하기로 결정했으며, 상위참조하여 생성 
$ python -V  //python이 없다면 /us/bin 에서 확인 후 설치 
Python 3.8.5
# sudo ln -s /usr/bin/python3 /usr/bin/python   //나의 경우 이전에 python2를 python 심볼링크 사용 (옵션) 
# sudo apt-get install python3-venv     //venv 설치 (옵션)

$ mkdir works
$ cd works
$ python -m venv py38-sphinx      //py38-sphinx venv 생성

$ ls
py38-sphinx

$ ls py38-sphinx/bin/           //python 과 python3 는 symbollink 확인 
Activate.ps1  activate  activate.csh  activate.fish  easy_install  easy_install-3.8  pip  pip3  pip3.8  python  python3

$ source py38-sphinx/bin/activate   //virtual env의 python 사용 
매번 py38-sphinx 내부의 virtualenv를 사용하기위해서는 source를 진행하거나, .bashrc 등 기타 로그인때 자동으로 설정해도 된다.


  • venv 안에 Python package 설치 
sphinx package 설치 및 확인 
(py38-sphinx) $ pip list
Package       Version
------------- -------
pip           20.0.2 
pkg-resources 0.0.0  
setuptools    44.0.0 

(py38-sphinx) $ pip install sphinx   //venv에 sphinx 설치

(py38-sphinx) $ pip list
Package                       Version  
----------------------------- ---------
alabaster                     0.7.12   
Babel                         2.9.1    
certifi                       2021.10.8
charset-normalizer            2.0.7    
docutils                      0.17.1   
idna                          3.3      
imagesize                     1.2.0    
Jinja2                        3.0.2    
MarkupSafe                    2.0.1    
packaging                     21.0     
pip                           20.0.2   
pkg-resources                 0.0.0    
Pygments                      2.10.0   
pyparsing                     2.4.7    
pytz                          2021.3   
requests                      2.26.0   
setuptools                    44.0.0   
snowballstemmer               2.1.0    
Sphinx                        4.2.0    
sphinxcontrib-applehelp       1.0.2    
sphinxcontrib-devhelp         1.0.2    
sphinxcontrib-htmlhelp        2.0.0    
sphinxcontrib-jsmath          1.0.1    
sphinxcontrib-qthelp          1.0.3    
sphinxcontrib-serializinghtml 1.1.5    
urllib3                       1.26.7 

(py38-sphinx) $ pip list | wc -l    //전부 28 line 이며 -2개를 하면 26 package 가지고 있음(계산하기 귀찮음) 
28

(py38-sphinx) $ pip list | wc      //newline:28  word:56  byte counts:1120
     28      56    1120


Python venv 기본사용법



1.1. sphinx 기본 테스트

  • Sphinx 기본사용 및 확인 

(py38-sphinx) $ mkdir docs
(py38-sphinx) $ cd docs

(py38-sphinx) $ sphinx-quickstart  // 실행하면, 현재 directory기준 
Sphinx 4.0.2 빠른 시작 유틸리티에 오신 것을 환영합니다.

다음 설정에 대한 값을 입력하십시오 (대괄호로 묶여 있는 기본값이 존재하고
이 값을 사용하려면 바로 Enter를 누릅니다).

선택한 루트 경로: .

Sphinx 출력을 위한 빌드 디렉토리를 배치하는 두 가지 옵션이 있습니다.
루트 경로 내에서 "_build" 디렉토리를 사용하거나, 루트 경로 내에서
"source"와 "build" 디렉토리로 분리합니다.
> 원본과 빌드 디렉토리 분리 (y/n) [n]:
> 프로젝트 이름: testSphinx
> 작성자 이름: Jeonghun Lee
> 프로젝트 릴리스 []: 1.0

문서를 영어 이외의 언어로 작성하려는 경우, 여기에서 해당 언어 코드로 언어를
선택할 수 있습니다. 그러면 Sphinx가 생성한 텍스트를 해당 언어로 번역합니다.

지원되는 코드 목록은
https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language
를 참조하십시오.
> 프로젝트 언어 [en]:
/home/jhlee/works/docs/conf.py 파일을 만드는 중입니다.
/home/jhlee/works/docs/index.rst 파일을 만드는 중입니다.
/home/jhlee/works/docs/Makefile 파일을 만드는 중입니다.
/home/jhlee/works/docs/make.bat 파일을 만드는 중입니다.

완료됨: 초기 디렉토리 구조가 생성되었습니다.

이제 마스터 파일 /home/jhlee/works/docs/index.rst을(를) 채우고 다른 원본 문서 파일을 만들어야 합니다. Makefile을 사용하여 다음과 같이 문서를 빌드하십시오:
   make builder
여기서 "builder"는 지원되는 빌더 중 하나(예: html, latex, linkcheck)입니다.

(py3-sphinx) $ ls      // 원본과 빌드 디렉토리 분리 [n] 일경우 구성 
Makefile  _build  _static  _templates  conf.py  index.rst  make.bat


(py38-sphinx) $ ls      // 원본과 빌드 디렉토리 분리 [y] 일경우 구성 
Makefile  build  make.bat  source 
(py3-sphinx) $ ls source
_static  _templates  conf.py  index.rst

(py3-sphinx) $ make html   //_build 안에 html 안에 html구성 index.html 확인

  • _build/html/index.html
상위내용 및 venv 기반의 sphinx 설정 
  https://www.docslikecode.com/learn/01-sphinx-python-rtd/

1.2. Sphinx의 theme 변경 

Sphinx에서 제공하는 Theme들을 찾아 설치 후 이를 설정하고 이 기반으로 변경해보자.
아래는 ReadTheDoc의 theme이며, 이외에도 많으므로 각 설정해보면서 바꾸어 보자.


(py38-sphinx) $ pip install sphinx_rtd_theme      //sphinx theme 설치 esp32는 별도로 변경해서 사용함
(py38-sphinx) $ pip list | wc                     //sphinx_rtd_theme 만 설치됨
     29      58    1160

(py38-sphinx) $ vi conf.py   //sphinx_rtd_theme 만 변경
#html_theme = 'alabaster'
html_theme = 'sphinx_rtd_theme'

(py3-sphinx) $ make html   //_build 안에 html 안에 html구성 index.html 확인

  • _build/html/index.html


Sphinx는 이외에도 다양한 Theme을 제공
아래사이트에서 본인이 원하는 Theme 찾고 설치진행 후 상위와 동일하게 설정 



1.3. Sphinx extension 설정 (conf.py)

  • sphinx에서 필요한 기능을 확장하여 설정
  1. extension 기능을 사용하기 위해서 아래와 같이 python 소스의 주석을 제거한 후 진행 
  2. 원하는 extension 기능을 아래와 같이 추가 
(py38-sphinx) $ vi conf.py   //각 관련부분 수정 
## 아래부분은 기본으로 주석으로 되어짐 
import os
import sys
sys.path.insert(0, os.path.abspath('.'))

## 확장기능으로 아래 링크참조 
extensions = [
        'sphinx.ext.autodoc',      # autodoc 안에 automodule 도 포함
        'sphinx.ext.autosummary',  # 현재미사용 
]
## 이전설정으로 다른 Theme으로 변경가능 
html_theme = 'sphinx_rtd_theme'

extension을 이용하여 다양하게 확장가능
상위에 각각의 링크확인가능 


1.4. Sphinx 의 index.rst 설정 


  • index.rst 파일설정 
index.rst 기본값 확인 후 toctree 설정진행 
(py38-sphinx) $ cat index.rst   //기본설정확인
Welcome to testSphinx's documentation!
======================================

.. toctree::
   :maxdepth: 2
   :caption: Contents:


Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

각 구성할 *.rst 파일과 함께 최종 index.rst 에 연결진행 

  • about.rst 구성 
(py38-sphinx) $ vi about.rst    //상위에서 source 와 build를 분리하지않음 (분리하면 source 안에)
about 
=====

about 에대한 파일이며 이것은 오직 테스트용으로 사용함 

.. math::
   
   (a + b)^2 = a^2 + 2ab + b^2

   (a - b)^2 = a^2 - 2ab + b^2




  • intro.rst 구성 
(py38-sphinx) $ vi intro.rst  //아래내용들은 toctree 예제참조
intro^^
=========

정말 이게 인트로인지 테스트 해보자 

.. note::

   This function is not suitable for sending spam e-mails.

.. versionadded:: 2.5
   The *spam* parameter.


.. deprecated:: 3.1
   Use :func:`spam` instead.


.. seealso::

   Module :py:mod:`zipfile`
      Documentation of the :py:mod:`zipfile` standard module.

   `GNU tar manual, Basic Tar Format ???
      Documentation for tar archive files, including GNU tar extensions.   




  • source.rst
(py38-sphinx) $ vi source.rst
Python source 
==============

.. automodule:: pysrc.testclass
    :members: 
    
(py38-sphinx) $ mkdir pysrc    
(py38-sphinx) $ vi pysrc/testclass.py  //아래사이트에서 얻은예제 추가 (상위 conf.py 확장) 
"""
    My Module
    ~~~~~~~~~
"""

class Test(object):
    """두 개의 int 값을 입력받아 다양한 연산을 할 수 있도록 하는 클래스.

    :param int a: a 값
    :param int b: b 값
    """

    def __init__(self, a, b):
        self._a = a
        self._b = b

    def is_same(self):
        """미리 입력받은 a와 b값이 같은지 확인하여 결과를 반환합니다.

        :return: boolean True or False에 대한 결과, a와 b가 값으면 True, 다르면 False

        예제:
            다음과 같이 사용하세요:

            >>> Test(1, 2).is_same()
            False

        """
        return self._a == self._b

    def plus(self):
        """미리 입력받은 a와 b값을 더한 결과를 반환합니다.

        :returns: int a + b에 대한 결과

        예제:
            다음과 같이 사용하세요:

            >>> Test(2, 1).plus()
            3


        """
        return self._a + self._b




  • index.rst 변경 
(py38-sphinx) $ vi index.rst   //상위에서 추가한 *rst 파일들 추가 혹은 directory 추가 
Welcome to my Sphinx TEST !!!!!!!!!!!!
======================================

This is the documentation for TEST 
is it ok???   
한글도 되는 지 테스트를 해보도록하자 ㅋㅋㅋㅋㅋ   
MarkDown 과 유사하지만 "toctree" 별도로 제어로사용??   

.. toctree::
   :maxdepth: 2
   :caption: Table of Contents
   :numbered:   

   about
   intro
   source

Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`


(py3-sphinx) $ make html   //_build 안에 html 안에 html구성 index.html 확인 

  • 결과확인 
상위설정 후 make html로 생성된 파일확인 






상위 sphinx quickstart 기본설명
  https://www.sphinx-doc.org/en/master/usage/quickstart.html

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 사이트에서 작성된 문서를 ReadTheDocImport  
  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 기반으로 작성 


기타 

5/16/2021

ESP-IDF Doxygen과 기존 Doxygen 비교

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 구성 분석 전 확인사항 
  1. Espressif에서 사용하는 Doxygen Style Guide(Code Convention) 
  2. 문서에 필요 Package (Doxygen 이외 UML or Diagram)
  3. Manual의 전체설명방법 및 구성
어떻게 보면 가장 중요한 곳은 Code convention이라고 생각할 수 있으며, 코드의 가독성과 협업을 위해서 
최소한으로 지켜야할 규칙이자 프로그래머의 기본매너로, 팀단위 혹은 여러사람과 협업하여 같이 일할 경우, 
특히 중요하다. 하지만, 국내회사들은 크게 신경쓰지 않으며, 규칙조차 없거나, 무시되는 경우가 태반이다.
솔직히 개인적으로 그런회사들은 별로 좋아하지 않는다. 


  • ESP-IDF의 Doxygen 구성에 필요한 Package들 

** 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 구성
  1. Python의 Sphinx Package가 가장 Main으로 구성되어 문서관리 작성 
  2. Sphinx의 Manaul은 RST or Markdown or HTML 방식으로 작성되어 관리 
  3. 이외 소스의 API는 Doxygen으로 연결되어짐 
  4. 아래 그림에는 없지만, 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 및 설정 
  1. *.rst 파일 (Markdown 형식으로 구성)
  2. conf.py

ESP-IDF의 Sphinx 기본구조 
각 구조를 보면, Sphinx 기반으로 ESP 내부에서 많이 고쳐서 사용하고 있음을 대충 알수 있다.


  • Sphinx/Breathe/Cmake/Doxygen 종합구성사용법 
  1. Sphinx의 부가적으로  Doxygen을 쉽게 사용하기위해서 사용하는 것으로 보임
  2. Breathe는 Sphinx의 확장기능으로 사용
  3. Cmake 와 Sphinx는 연결이 가능하여 이를 쉽게 Doxygen으로 연결해주는 것으로 보임
  4. 아래의 예제도 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 구조로 구성  

  • Sphinx의 index.rst 세부분석 
Sphinx는 RST파일이 거의 Main으로 관리되어지며, Markdown도 지원한다. 
index.rst 의 경우, 좌측 Menu구성은 index.rst의 toctree로 구성  


  • ESP32 Document 전구조 
  1. build_docs.py : doxygen 을 이용하여 document 생성
  2. 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의  실사용예제들 
Blockdiag의 ESP32내부에서 사용되어지는 실제 *diag 예제들이며, 구성을 잘해서 좋다. 

상위 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  (현재 추측)
  1. Github기반으로 Hosting 하는 것으로 생각되며, 직접 고치는 것도 허용하며 영어와 중국어만 지원가능 
  2. PDF 다운로드도 지원가능 
  3. docs/en/index.rst  가 Main로 연결 (여러개의 index 파일로 구성)


2.1 Github의 Host 지원기능 

  •  이전에 내가 Github 기반으로 Host 한 테스트 예제 
  1. Github에서 Host를 하기위해서는 docs 폴더가 별도구성
  2. Setting->Pages 에서 설정한 후 Theme 도 별도 설정

  • 일반적인 Github의 Theme 기반구성 
 index.md 기반으로  Main 구성후 별도_config.yml 설정 

index.md 기반으로  Main구성  _config.yml 설정  (Github의 Theme) 

  • 상위와 다른점은 직접 HTML기반으로 구성 
docs/index.html 기반으로  Main구성  (ESP32도 이런식으로 구성)

2/11/2017

Ubuntu 에서 Doxygen 사용해보기

1. Doxygen 이란  

doxygen은 오래전부터 존재하던 프로그램이며,  줄곧 사용해보고 싶은 프로그램이였다.
오래전에 다니던 회사가 이를 직접 이용하였고, 회사의 Code Convention 기반으로 소스의 API의 문서를 쉽게 구성하여 이를 배포하였다. 
더불어 소스의 API 문서 뿐만아니라 이와 관련된 문서화 프로그램에 대해서 관심을 가지게 되었다.

기본 사용방법은 사용되어지는 프로그래밍 언어에 문서화가 필요한 API or Function에 각 회사에 맞는 Code Convention 주석으로 
구현한 Function or API를 쉽게 문서화를 하는 것이다.

주석으로 문서화를 하기때문에 주석을 사용하는 방법만 알면 쉽게 적용하여, API 문서를 작성을 할 수 있다. 
매번 open source를 사용할 때에도 Open Source의 doxygen을 이용하여 몇번 봐왔기에 궁금하였고, 어떻게 주석을 관리를 해야하는지 궁금하였다.

그리고  LaTex 역시 궁금한 문서화였으며, 이를 좀 더 자세히 알기 위해 간단히 정리하고자 한다.

  • LaTex란 


  https://ko.wikipedia.org/wiki/LaTeX


  • Doxygen 사용방법 Link 
  https://www.slideshare.net/arload/doxygen-33932243
  http://onecellboy.tistory.com/342


상위 두사이트에 Code 와 주석을 어떻게 관리를 해야하는지 설명이 잘 되어있어, 본인도 한번 따라해보기 수준으로 관리를 해본다.


1.1 Ubuntu 에서 Doxygen 설치 

Ubuntu 14.04 LTS에서 다음과 같이 doxygen을 설치해보자.

  • 기본설치
 $ sudo apt-get install doxygen doxygen-gui 

  • 추가설치
 $ sudo apt-get install doxygen-latex doxygen-doc graphviz 


Doxygen Build 및 설치
  https://www.stack.nl/~dimitri/doxygen/download.html#srcbin
  https://www.stack.nl/~dimitri/doxygen/manual/install.html#install_bin_unix

Doxygen 설치 및 사용법
  http://janghw.tistory.com/entry/doxygen-%EC%82%AC%EC%9A%A9%EB%B2%95

  • doxygen 실행
 $ doxygen --help 


  • doxygen gui 실행
 $ doxywizard 


doxywizard의 세부사용법 
  https://www.slideshare.net/arload/doxygen-33932243


1.2 Doxygen의 기본구성 

  • Doxywizard : Front-end GUI program으로 Doxygen을 이용하여 문서화가 가능
  • Doxygen    : Doxygen program으로, GUI가 지원이 안된다면 이것으로 실행

위에서 설명 했듯이 doxygen 의 기능은 code 안에 있는 주석을 parsing해서 이를 함수와 같이 문서화 하는 것이며,
이는 쉽게 문서관리를 하는 것이다. 이를 더 나아가 Makefile도 가능하며 이 기능역시 opensource에서는 많이 지원을 하고 있다.

예를들면 autoconf 파일에서 ./configure xxx --with-doxygen or --enable-doxygen
설정은 다양할 것이다. 이는 Makefile에도 영향을 미칠 것이며, m4 script도 같이 봐야 할 것이다.




보통 Output으로 많이 사용되는 것이 HTML/XML의 *.chm 와 *.pdf 방식이며, 개인적으로는 *.chm 방식이 검색 및 보기가 편하다.

  • doxygen 기본구조
  https://www.stack.nl/~dimitri/doxygen/manual/starting.html


  • MarkDown 문법지원
쉽게 도식을 구성을 할 수 있으며, 요즘 Github에서 많이 사용되어진다.
  https://www.stack.nl/~dimitri/doxygen/manual/markdown.html

  • Doxywizard 의 기본사용법
  https://www.stack.nl/~dimitri/doxygen/manual/doxywizard_usage.html


  • 주석의 구성예제
주석구성방법이며, 회사 Code Convention에 맞게 하도록하자. 

/***********************************************************************************

* @fn      halJoystickIntConnect

*

* @brief   Connect isr for joystick move interrupt. The parameter event tells for

*          which joystick direction this isr should be called.

*

* @param   event - Joystick direction

*          func - Pointer to function to connect

*

* @return  none

*/


2. Doxygen의 Manual 및 Download

Doxygen을 사용할 경우, 알아야 할 기본 Manual과 Download하는 곳 과 이외 Tool들 

  • Doxygen Download
  http://www.stack.nl/~dimitri/doxygen/download.html#latestsrc

  • Diagram 와 UML
다이어그램 이나 그림을 쉽게 그릴수 있는 그래픽툴로 Graphviz 사용하지만, 오래되었다. 
이외에도 Mermaid가 있는데, 이것도 오래된 것이라 최근에는 무엇을 사용하는지 모름 
  http://www.graphviz.org/Download..php
  https://www.graphviz.org/
  https://www.graphviz.org/about/

  • Graphviz 문서
Node , Edge, Arrow 등을 설정하고 관련부분 사용Manual 
  http://www.graphviz.org/documentation/

  • Graphviz가 지원되는 Output Format
  http://www.graphviz.org/doc/info/output.html

  • Graphviz Google API
Google Chart->Graphviz API 제공 
  https://developers.google.com/chart/image/docs/gallery/graphviz

  • Doxygen 의 Markdown 지원 
기본 문서작성이 쉽게 가능하게 하며, 이를 이용하여 문서작성이 용이하다. 

HTML도 지원가능하므로, 이를 확장사용하자 

  • 수학공식문서 및 세부표현 
복잡한 수학공식들을 표현할때 아래를 참조