1. Mkdocs
이전에 Sphinx 와 Mkdocs 기반으로 환경을 구축하여 간단하게 테스트를 한적이 있는데,
Mkdocs만으로 쉽게 Github의 Markdown 문서를 관리하는 법을 간단히 소개한다.
이유는 Mkdocs는 Markdown 으로만 사용하기 때문에 Github와 더 잘 어울린다.
다만 아쉬운것은 Sphinx에 비해 Plugin이 좀 떨어질 뿐이다.
- ReadTheDoc (Mkdocs/Sphinx 둘 다 지원)
- Mermaid.JS 사용예제
Github에서는 이미 Markdown에 mermaid를 제공하지만, 아래와 같이 Mermaid.js로 해도됨
- 기본설치 및 테스트 진행
$ 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 - Convertingalignment(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 설명서를 구성하기 위해서 예전에 많이 사용했다.
doxygen 기반의 API
A compiled help(.chm)
- 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)에러문제
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 부터 변경해서 차근차근사용하면 될꺼 같다.
댓글 없음 :
댓글 쓰기