오픈소스를 열심히 만들어도 문서화가 안되면 사용자가 늘어날 수 없습니다. 말과 실습으로 소개하는 튜토리얼에는 스케일링의 한계가 있기 때문이지요. 지금도 지속되고 있는 Backend.AI 의 문서화 과정을 예제 삼아 오픈소스 문서 작성 방법과 자동화 경험을 나누어 볼 예정입니다. 찬조출연할 오픈소스 및 서비스로는 sphinx, readthedocs, jsdoc 등이 있습니다.
(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
”사용 매뉴얼 이 필요해요!” 적다 보니 130장 • 도구의 특성 백엔드 + 프레임웍 개발자들이 만질 경우가 훨씬 많음 코드의 난이도가 높음 ü 거의 모든 부분이 비동기 코드 ü 논리 따라 따라가기가 어렵다 • 위키 기반으로 프로젝트 초기엔 감당 가능했으나 불가능해짐. 이유는…
구성 • 다양성 기술 분야: 머신 러닝, 딥러닝, 클라우드, Docker, 컨테이너 가상화, GPU 프로그래밍 언어: Python, Go, C++, JavaScript • 버전업의 속도 6개월 단위의 버전업 12개월 단위의 LTS (2 년 지원) • CI / CD Travis CI GitHub Actions 자체 테스트베드
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++
주석을 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:
템플릿 생성 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에 추가
경우: make latexpdf • 팁 두 번 돌리세요. 그래야 첫 실행때 문서 생성 및 인덱스 후보를 추리고, 두 번째에 결과물이 제대로 나옵니다. 바꾼 것이 없는데 빌드가 갑자기 안 될 경우: _build/ 하위 디렉토리를 지우고 다시 빌드하면 됩니다. • 결과물 스태틱 HTML 문서 이걸 이제 공개할 방법이 필요합니다.
호스팅 지원 (Sphinx의 경우) 문서 자동 빌드 지원 여러 버전의 문서가 있는 경우, 언어 및 버전별 문서 호스팅 모두 지원 • 자동 빌드하기 문서가 있는 패키지의 GitHub에 이벤트 훅 추가 1. Read the docs에 로그인 2. Admin > Advanced settings로 이동 3. Build pull requests for this project 옵션 켜면 적용
코드 주석 기반의 API 문서 생성에 특화 • 왜 sphinx 를 쓰지 않았는가? Node.js 툴체인에 python을 끼워넣지 않기 위해 여러 언어 툴체인을 써도 상관 없는 경우, 또는 전역 도구로 sphinx를 설치한 경우엔 sphinx + Markdown 도 괜찮은 선택임
속성에 대한 주석을 기술 • 예 @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();
디렉토리로 이동 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
sat
ogaclejapan
ishikawa_satoru
drumnistnakano
tomoki10
asei
coosuke
xerial
fujisawaryohei
yuj1osm
naoki_0531
.png){kind=icon}
pharma_x_tech
kneath
paulrobertlloyd
notwaldorf
addyosmani
garrettdimon
62gerente
honnibal
mclloyd
brettharned
chriscoyier
ammeep
