오픈소스를 열심히 만들어도 문서화가 안되면 사용자가 늘어날 수 없습니다. 말과 실습으로 소개하는 튜토리얼에는 스케일링의 한계가 있기 때문이지요. 지금도 지속되고 있는 Backend.AI 의 문서화 과정을 예제 삼아 오픈소스 문서 작성 방법과 자동화 경험을 나누어 볼 예정입니다. 찬조출연할 오픈소스 및 서비스로는 sphinx, readthedocs, jsdoc 등이 있습니다.
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
처음 문서화하기 • Markdown + docx 기반의 수동 작성 ”사용 매뉴얼 이 필요해요!” 적다 보니 130장 • 도구의 특성 백엔드 + 프레임웍 개발자들이 만질 경우가 훨씬 많음 코드의 난이도가 높음 ü 거의 모든 부분이 비동기 코드 ü 논리 따라 따라가기가 어렵다 • 위키 기반으로 프로젝트 초기엔 감당 가능했으나 불가능해짐. 이유는…
자동화? • 규모 https://github.com/lablup/backend.ai (메타 저장소) 및 19개 저장소로 구성 • 다양성 기술 분야: 머신 러닝, 딥러닝, 클라우드, Docker, 컨테이너 가상화, GPU 프로그래밍 언어: Python, Go, C++, JavaScript • 버전업의 속도 6개월 단위의 버전업 12개월 단위의 LTS (2 년 지원) • CI / CD Travis CI GitHub Actions 자체 테스트베드
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++
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:
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에 추가
Sphinx: 컴파일 • HTML 생성하기 make html PDF의 경우: make latexpdf • 팁 두 번 돌리세요. 그래야 첫 실행때 문서 생성 및 인덱스 후보를 추리고, 두 번째에 결과물이 제대로 나옵니다. 바꾼 것이 없는데 빌드가 갑자기 안 될 경우: _build/ 하위 디렉토리를 지우고 다시 빌드하면 됩니다. • 결과물 스태틱 HTML 문서 이걸 이제 공개할 방법이 필요합니다.
Sphinx: readthedocs를 통한 배포 • Read the Docs 문서 호스팅 지원 (Sphinx의 경우) 문서 자동 빌드 지원 여러 버전의 문서가 있는 경우, 언어 및 버전별 문서 호스팅 모두 지원 • 자동 빌드하기 문서가 있는 패키지의 GitHub에 이벤트 훅 추가 1. Read the docs에 로그인 2. Admin > Advanced settings로 이동 3. Build pull requests for this project 옵션 켜면 적용
JSDoc • 자바스크립트를 위한 API 문서 생성기 일반 문서보다는 코드 주석 기반의 API 문서 생성에 특화 • 왜 sphinx 를 쓰지 않았는가? Node.js 툴체인에 python을 끼워넣지 않기 위해 여러 언어 툴체인을 써도 상관 없는 경우, 또는 전역 도구로 sphinx를 설치한 경우엔 sphinx + Markdown 도 괜찮은 선택임
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();
다국어화 • 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
inureyes
bonjiri_niwa
hirokiigeta
masatokitahara
oracle4engineer
minorun365
robots
nenonaninu
soracom
chiroruxx
tamaiyutaro
takahashikazutaro
nicolasgrekas
vanstee
addyosmani
morganepeng
gr2m
thoeni
geoffreycrofte
bkeepers
kastner
colly
iamctodd
chrisshort
brianwarren