Upgrade to Pro — share decks privately, control downloads, hide ads and more …

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

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

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

Jeongkyu Shin

November 07, 2020
Tweet

More Decks by Jeongkyu Shin

Other Decks in Technology

Transcript

  1. ߔ ݃٣ ݈ࠁ׮ ઺ਃೠ Ѫ
    #BDLFOE"*੄ য়೑ࣗझ ޙࢲ ੘ࢿҗ
    ੗زച ҃೷
    Backend.AI 신정규

    View full-size slide

  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

    View full-size slide

  3. Backend.AI
    Backend.AI 는 오픈소스
    클라우드 리소스 관리 플랫폼입니다.
    GPU 분할 가상화를 제공하여,
    과학자, 데브옵스, 기업 및 AI 애호가들이
    효율적으로 규모를 확장
    할 수 있게 돕습니다.
    https://www.backend.ai
    22 / 81

    View full-size slide

  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)

    View full-size slide

  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

    View full-size slide

  6. 구슬이
    서 말이라도
    꿰어야 보배

    View full-size slide

  7. 처음 문서화하기
    • Markdown + docx 기반의 수동 작성
    ­ ”사용 매뉴얼 이 필요해요!”
    ­ 적다 보니 130장
    • 도구의 특성
    ­ 백엔드 + 프레임웍
    ­ 개발자들이 만질 경우가 훨씬 많음
    ­ 코드의 난이도가 높음
    ü 거의 모든 부분이 비동기 코드
    ü 논리 따라 따라가기가 어렵다
    • 위키 기반으로
    ­ 프로젝트 초기엔 감당 가능했으나
    ­ 불가능해짐. 이유는…

    View full-size slide

  8. 자동화?
    • 규모
    ­ https://github.com/lablup/backend.ai (메타 저장소) 및 19개 저장소로 구성
    • 다양성
    ­ 기술 분야: 머신 러닝, 딥러닝, 클라우드, Docker, 컨테이너 가상화, GPU
    ­ 프로그래밍 언어: Python, Go, C++, JavaScript
    • 버전업의 속도
    ­ 6개월 단위의 버전업
    ­ 12개월 단위의 LTS (2 년 지원)
    • CI / CD
    ­ Travis CI
    ­ GitHub Actions
    ­ 자체 테스트베드

    View full-size slide

  9. 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++

    View full-size slide

  10. 문서 생성
    코드에
    주석달기
    수동으로
    문서 쓰기
    기본적인 설명
    문서 인덱스
    중요 단어 및 컨셉
    함수 / 메소드 / 클래스
    모듈 개요
    도움말 프로그램용 (click, manpage)
    Sphinx (Python)
    jsDoc (JavaScript / TypeScript)

    View full-size slide

  11. reStructuredText
    • 텍스트 마크업 문법
    • 2002년
    • Python의 docutils가 지원하는 문법
    • 쉽다!

    View full-size slide

  12. 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:

    View full-size slide

  13. Sphinx
    • 문서 자동 생성 도구
    • 다양한 출력
    ­ HTML, PDF, LaTeX, ePub, Text
    • 레퍼런스, 구조화, 자동 인덱스 생성
    • 코드 분석 및 주석 생성
    • 확장 기능

    View full-size slide

  14. 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에 추가

    View full-size slide

  15. Sphinx: 컴파일
    • HTML 생성하기
    ­ make html
    ­ PDF의 경우: make latexpdf
    • 팁
    ­ 두 번 돌리세요. 그래야 첫 실행때 문서 생성 및 인덱스 후보를 추리고, 두 번째에
    결과물이 제대로 나옵니다.
    ­ 바꾼 것이 없는데 빌드가 갑자기 안 될 경우: _build/ 하위 디렉토리를 지우고
    다시 빌드하면 됩니다.
    • 결과물
    ­ 스태틱 HTML 문서
    ­ 이걸 이제 공개할 방법이 필요합니다.

    View full-size slide

  16. Sphinx: readthedocs를 통한 배포
    • Read the Docs
    ­ 문서 호스팅 지원
    ­ (Sphinx의 경우) 문서 자동 빌드 지원
    ­ 여러 버전의 문서가 있는 경우, 언어 및 버전별 문서 호스팅 모두 지원
    • 자동 빌드하기
    ­ 문서가 있는 패키지의 GitHub에 이벤트 훅 추가
    1. Read the docs에 로그인
    2. Admin > Advanced settings로 이동
    3. Build pull requests for this project 옵션 켜면 적용

    View full-size slide

  17. JSDoc
    • 자바스크립트를 위한 API 문서 생성기
    ­ 일반 문서보다는 코드 주석 기반의 API 문서 생성에 특화
    • 왜 sphinx 를 쓰지 않았는가?
    ­ Node.js 툴체인에 python을 끼워넣지 않기 위해
    ­ 여러 언어 툴체인을 써도 상관 없는 경우, 또는 전역 도구로 sphinx를 설치한 경우엔 sphinx +
    Markdown 도 괜찮은 선택임

    View full-size slide

  18. 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
    }
    }

    View full-size slide

  19. 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();

    View full-size slide

  20. JSDoc으로 빌드하기
    • 로컬 설치: ./node_modules/jsdoc/jsdoc.js -c jsdoc.json
    • 전역 도구의 경우: jsdoc –c jsdoc.json
    • 생성된 문서는 /docs 하위에 저장

    View full-size slide

  21. 다국어화
    • 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

    View full-size slide

  22. 언어별
    버전별
    포맷별

    View full-size slide

  23. 언어별
    버전별
    포맷별

    View full-size slide

  24. 톺아보기
    • 문서화가 왜 필요할까?
    • 문서화는 어떻게 시작할까?
    • 문서화 자동화는 언제부터 필요할까?
    • Python 기반 프로젝트의 문서 자동화
    • JavaScript 기반 프로젝트의 문서 자동화
    • 다국어 문서 지원 방법

    View full-size slide

  25. 문서화 참고
    • 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/

    View full-size slide

  26. 끝! :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
    [email protected]
    inureyes inureyes
    jeongkyu.shin

    View full-size slide