백 마디 말보다 중요한 것: Backend.AI의 오픈소스 문서 작성과 자동화 경험

오픈소스를 열심히 만들어도 문서화가 안되면 사용자가 늘어날 수 없습니다. 말과 실습으로 소개하는 튜토리얼에는 스케일링의 한계가 있기 때문이지요. 지금도 지속되고 있는 Backend.AI 의 문서화 과정을 예제 삼아 오픈소스 문서 작성 방법과 자동화 경험을 나누어 볼 예정입니다. 찬조출연할 오픈소스 및 서비스로는 sphinx, readthedocs, jsdoc 등이 있습니다.

Transcript

1. ߔ ݃٣ ݈ࠁ׮ ઺ਃೠ Ѫ #BDLFOE"*੄ য়೑ࣗझ ޙࢲ ੘ࢿҗ ੗زച ҃೷ Backend.AI 신정규
2. 신정규 • Lablup Inc. : Make AI Accessible ­ Open-source machine learning cluster platform: Backend.AI ­ https://www.backend.ai • Google Developer Expert ­ ML / DL GDE (Context retrieval) ­ Sprint Master 2 / 69
3. Backend.AI Backend.AI 는 오픈소스 클라우드 리소스 관리 플랫폼입니다. GPU 분할 가상화를 제공하여, 과학자, 데브옵스, 기업 및 AI 애호가들이 효율적으로 규모를 확장 할 수 있게 돕습니다. https://www.backend.ai 22 / 81
4. Backend.AI: 개발 로드맵 2015.8 Project made public (PyCon KR) 2017.10 v1.0 Release ­ REPL stabilization ­ Developer manuals ­ VFolders ­ Available via PyPI 2019.3 v19.03 Release ­ Fractional GPU sharing (GA) ­ NVIDIA GPU Cloud (NGC) integration ­ Extensive admin features ­ Stabilization with heavy load tests Time Alpha Beta Production-ready 2019.9 v19.09 Release ­ Improved fGPU sharing with monitoring ­ Resource groups ­ Multi-hierarchical user scopes with ACL ­ SSO integration ­ High-availability setup ­ Enterprise-level admin features 36 / 39 2016.11 v0.9 Release ­ Initial code release on GitHub ­ LGPLv3 (server) ­ MIT Lincese (client) 2018.1~3 v1.1 ~ v1.3 Release ­ Code stabilization ­ Installer suport ­ Plug-in structure 2018.9 v1.4 Release ­ Fractional GPU sharing (beta) 2018.12 v18.12 Release ­ Calendar versioning (year.month) ­ Support custom Docker registries ­ Google TPU support (beta)
5. Backend.AI: 개발 로드맵 (2020~) 시간 Enterprise R2 (20.03/09) Enterprise R3 (21.03/09) 2020.6 v20.03 Release ­ Pipeline & module standards (beta) ­ Customizable session scheduler ­ Multi-storage support with LustreFS / GlusterFS (beta) ­ K8s cluster agent (beta) ­ DGX-A100 support (GA) ­ AMD ROCm support (beta) ­ DGX integration (beta) ­ GUI-on-container (beta) 2020.10 v20.09 Release ­ Multi-conatiner sessions (GA) ­ Data pipelines ­ Storage proxy with PureStorage acceleration (GA) ­ Private model serving ­ MLFlow integration ­ Callosum secure RPC layer (GA) ­ DGX clustering support (GA) ­ K8s cluster agent (GA) ­ Google TPU support (GA) ­ AMD ROCm support (GA) ­ CUDA MPX support (beta) ­ Data store (beta) ­ Model store (beta) 2021.3 v21.03 Release ­ Data store (GA) ­ Model store (GA) ­ Public model serving ­ Auto-scaling of served models ­ "World Console" for remote resource management via cloud (GA) ­ More to come! 37 / 39
6. 대략 5년
7. 문서화
8. 구슬이 서 말이라도 꿰어야 보배
9. 처음 문서화하기 • Markdown + docx 기반의 수동 작성 ­ ”사용 매뉴얼 이 필요해요!” ­ 적다 보니 130장 • 도구의 특성 ­ 백엔드 + 프레임웍 ­ 개발자들이 만질 경우가 훨씬 많음 ­ 코드의 난이도가 높음 ü 거의 모든 부분이 비동기 코드 ü 논리 따라 따라가기가 어렵다 • 위키 기반으로 ­ 프로젝트 초기엔 감당 가능했으나 ­ 불가능해짐. 이유는…
10. 자동화? • 규모 ­ https://github.com/lablup/backend.ai (메타 저장소) 및 19개 저장소로 구성 • 다양성 ­ 기술 분야: 머신 러닝, 딥러닝, 클라우드, Docker, 컨테이너 가상화, GPU ­ 프로그래밍 언어: Python, Go, C++, JavaScript • 버전업의 속도 ­ 6개월 단위의 버전업 ­ 12개월 단위의 LTS (2 년 지원) • CI / CD ­ Travis CI ­ GitHub Actions ­ 자체 테스트베드
11. IaaS / OS 하드웨어 인프라 Brand Guidelines TensorFlow is an end-to-end open-source platform for machine learning. It has a comprehensive, flexible ecosystem of tools, libraries and community resources that lets researchers push the state-of-the-art in ML and developers easily build and deploy ML powered applications. 관리형 앱 컨테이너 수준 GPU 가상화 원클릭으로 실행하는 다양한 개발·실행환경 모니터링·관제를 위한 웹 기반 GUI Backend.AI Manager IDE 통합 Backend.AI Client Backend.AI Agent [GUI] JavaScript / TypeScript [CLI] Python [Hub] Python [SDK] Python, Javascript Python C++ Python Go C++
13. 문서 생성 코드에 주석달기 수동으로 문서 쓰기 기본적인 설명 문서 인덱스 중요 단어 및 컨셉 함수 / 메소드 / 클래스 모듈 개요 도움말 프로그램용 (click, manpage) Sphinx (Python) jsDoc (JavaScript / TypeScript)
14. reStructuredText • 텍스트 마크업 문법 • 2002년 • Python의 docutils가 지원하는 문법 • 쉽다!
15. reStructuredText 포맷의 주석 적용하기 • 문서화할 class, method의 정의 아래에 주석을 reST 포맷으로 작성 • 호출 method의 주석을 바로 CLI의 도움말로 사용할 수 있음 ­ 다양한 도구들이 지원함 def app(session_name, app, protocol, bind, arg, env): """ Run a local proxy to a service provided by Backend.AI compute sessions. The type of proxy depends on the app definition: plain TCP or HTTP. \b SESSID: The compute session ID. APP: The name of service provided by the given session. """ bind_parts = bind.rsplit(':', maxsplit=1) ➜ ~ backend.ai app --help Usage: backend.ai app [OPTIONS] NAME APP Run a local proxy to a service provided by Backend.AI compute sessions. The type of proxy depends on the app definition: plain TCP or HTTP. SESSID: The compute session ID. APP: The name of service provided by the given session. Options:
16. Sphinx • 문서 자동 생성 도구 • 다양한 출력 ­ HTML, PDF, LaTeX, ePub, Text • 레퍼런스, 구조화, 자동 인덱스 생성 • 코드 분석 및 주석 생성 • 확장 기능
17. Sphinx: 설정 1. 패키지 디렉토리에 docs 생성 2. sphinx-quickstart로 초기 템플릿 생성 ­ Makefile 및 make.bat (컴파일 규칙), conf.py (설정), index.rst (초기 인덱스 파일) 생성됨 3. conf.py 편집 ­ 소스를 참조할 경로 추가 ­ extensions에 사용할 확장기능 추가 ü Intersphinx (여러 모듈을 참조할 경우), mathjax (수식이 있는 경우), autodoc (소스를 참조하는 경우), viewcode ­ project, copyright, author 수정 ­ 나머지는 필요에 따라 수정 ü autodoc_default_options 및 autodoc_member_order 수정 ü Intersphinx_mapping 수정 (여러 모듈이 상호참조하는 경우) 4. index.rst 수정 ­ 어떤 코드를 참조할 것인지의 경로를 toctree에 추가
18. Sphinx: 컴파일 • HTML 생성하기 ­ make html ­ PDF의 경우: make latexpdf • 팁 ­ 두 번 돌리세요. 그래야 첫 실행때 문서 생성 및 인덱스 후보를 추리고, 두 번째에 결과물이 제대로 나옵니다. ­ 바꾼 것이 없는데 빌드가 갑자기 안 될 경우: _build/ 하위 디렉토리를 지우고 다시 빌드하면 됩니다. • 결과물 ­ 스태틱 HTML 문서 ­ 이걸 이제 공개할 방법이 필요합니다.
19. Sphinx: readthedocs를 통한 배포 • Read the Docs ­ 문서 호스팅 지원 ­ (Sphinx의 경우) 문서 자동 빌드 지원 ­ 여러 버전의 문서가 있는 경우, 언어 및 버전별 문서 호스팅 모두 지원 • 자동 빌드하기 ­ 문서가 있는 패키지의 GitHub에 이벤트 훅 추가 1. Read the docs에 로그인 2. Admin > Advanced settings로 이동 3. Build pull requests for this project 옵션 켜면 적용
21. JSDoc • 자바스크립트를 위한 API 문서 생성기 ­ 일반 문서보다는 코드 주석 기반의 API 문서 생성에 특화 • 왜 sphinx 를 쓰지 않았는가? ­ Node.js 툴체인에 python을 끼워넣지 않기 위해 ­ 여러 언어 툴체인을 써도 상관 없는 경우, 또는 전역 도구로 sphinx를 설치한 경우엔 sphinx + Markdown 도 괜찮은 선택임
22. JSDoc: 설정 • jsdoc.json ­ JSON 타입의 설정 파일 • 수정할 부분 ­ source/include에 참조할 파일 명기 ü 또는 includePattern에 패턴 기록 ­ 제외할 디렉토리 추가 ü node_modules가 들어가지 않도록 주의해야 함 ü 엄청 커집니다. { "tags": { "allowUnknownTags": false }, "source": { "include": ["./backend.ai-client-node.js"] , "includePattern": ".js$", "exclude": ["./docs"], "excludePattern": "(node_modules/|docs)" }, "plugins": [ "plugins/markdown" ], "opts": { "encoding": "utf8", "destination": "./docs", "recurse": true, "verbose": true }, "templates": { "cleverLinks": false, "monospaceLinks": false, "default": { "outputSourceFiles": false } }, "docdash": { "static": false, "sort": false } }
23. JSDoc 포맷의 주석 적용하기 • 다양한 종류의 블럭 태그들로 특정 속성에 대한 주석을 기술 • 예 ­ @summary: 한 줄 짜리 요약 설명 ­ @param: 파라미터의 이름, 타입 및 설명 ­ @since: 추가된 시점 ­ 등등… 굉장히 많음 /** * Create a compute session if the session for the given sessionId does not exists. * It returns the information for the existing session otherwise, without error. * * @param {string} kernelType - the kernel type (usually language runtimes) * @param {string} sessionId - user-defined session ID * @param {object} resources - Per-session resource * @param {number} timeout - Timeout of request. Default : default fetch value. (5sec.) */ async createIfNotExists(kernelType, sessionId, resources = {}, timeout: number = 0) { if (typeof sessionId === 'undefined' || sessionId === null) sessionId = this.generateSessionId();
24. JSDoc으로 빌드하기 • 로컬 설치: ./node_modules/jsdoc/jsdoc.js -c jsdoc.json • 전역 도구의 경우: jsdoc –c jsdoc.json • 생성된 문서는 /docs 하위에 저장
25. 다국어화 • gettext / op 기반의 다국어화 준비 1. docs 디렉토리로 이동 2. 텍스트 리소스 추출 ü sphinx-build -b gettext . _build/gettext 3. 언어 번역을 위한 po 파일 업데이트 ü sphinx-intl update -p _build/gettext -l ko (언어 코드에 해당) 4. 번역 1. cd locales/ko/LC_MESSAGES/ 2. 원하는 편집기로 편집 • 번역 내용으로 빌드하기 ­ Language 옵션을 주어 특정 언어로 빌드할 수 있음 make -e SPHINXOPTS="-D language='ko'" html
26. 언어별 버전별 포맷별
27. 언어별 버전별 포맷별
28. 톺아보기 • 문서화가 왜 필요할까? • 문서화는 어떻게 시작할까? • 문서화 자동화는 언제부터 필요할까? • Python 기반 프로젝트의 문서 자동화 • JavaScript 기반 프로젝트의 문서 자동화 • 다국어 문서 지원 방법
29. 문서화 참고 • CLI/Python SDK (소스) https://github.com/lablup/backend.ai-client-py/tree/master/docs • SDK/API (결과물) https://docs.backend.ai/en/latest/ • CLI/Python SDK (결과물) https://client-py.docs.backend.ai/en/latest/ • JavaScript SDK (소스) https://github.com/lablup/backend.ai-client-js/tree/main • Backend.AI GUI (소스) https://github.com/lablup/backend.ai-docs-console • Backend.AI GUI (결과물) https://console.docs.backend.ai/en/latest/
30. 끝! :D 재미있으셨나요? For more information, Lablup Inc. Backend.AI Backend.AI GitHub Backend.AI Cloud https://www.lablup.com https://www.backend.ai https://github.com/lablup/backend.ai https://cloud.backend.ai inureyes@gmail.com inureyes inureyes jeongkyu.shin