P0 - Documentation ready for Beta Release

[scarlett2018]

Checklist for public release

We plan to separate the docs into 4 parts:

• Manual for data scientists: This manual is for data scientists to learn how to submit job, debug job, manage data, use Marketplace, VSCode / Jupyter extension and CLI support on OpenPAI.
• Manual for cluster administrators: This manual is for cluster administrators to learn the installation and uninstallation of OpenPAI, some basic management operations, storage management, troubleshootiong, etc.
• Manual for PAI developers: This manual is for potential PAI developers to quickly go through the achitecture of OpenPAI and learn how to leverage the SDK and develop new plugins.
• Design documentation (Reference): PAI design documentation and API reference for different PAI components.

I have created a branch user_manual for creating these 3 manuals, the link to the manual is https://github.com/microsoft/pai/tree/user_manual/manual . The planned contents of these manuals are as follows:

Contents for data scientists manual

• Quick Start
  • Submit a hello world job
  • Browse stdout, stderr, full logs, metrics
• Work with docker image
  • Introduction to pre-built docker images
• How to Manage Data (need help) @Binyang2014
  • Team-wise storage - NFS
  • Team-wise storage - AzureFile
  • Team-wise storage - AzureBlob (create an issue for the current known problem)
  • Current doc: https://github.com/microsoft/pai/blob/master/docs/setup-persistent-volumes-on-pai.md
• How to Debug Job
  • How to use SSH plugin
  • How to use TensorBoard plugin
• Advanced Jobs
  • Retry policy and job exit spec (need help) @yqwang-ms
  • Job example with multiple task roles
    • tensorflow_cifar10
    • horovod_pytorch
  • Port reservation , environmental variables, parameters, and secrets
  • InfiniBand job (need help) @abuccts
  • Reference link to job protocol
• Use Marketplace
  • Brief usage introduction (need help) @debuggy
• Use VSCode extension
  • Brief usage introduction
  • Reference link to VSCode extension
• Use Jupyter notebook extension
  • Jupyter notebook extension

Contents for cluster administrator manual

• Installation Guide (Quick Start)
  • From scratch
• Major breaking changes comparing with previous version
  • From previous deployment
• Installation FAQ (need help) @abuccts
  • Questions about Installation
  • Installation troubleshooting
• Basic Management Operations
  • Mangement on Webportal @hzy46
    • Hardware utilization page
    • Services page
    • User management
    • Abnormal jobs
    • How to access k8s dashboard
  • PAI service management and paictl
    • Brief introduction to PAI services
    • Use paictl to customize config, and restart PAI services
• How to Manage Users and Groups
  • users and groups in basic authentication mode (need help) @debuggy
    • how to access rest-server
    • how to use rest-server to configure user and groups in baisc auth mode
  • users and groups in AAD mode
    • How to Setup AAD
• How to Setup Team-wise Storage (need help) @Binyang2014
  • NFS server (storage manager)
  • Samba
  • AzureFile
  • Azureblob
• How to Setup Virtual Clusters
  • Introduction to hivedscheduler and how to configure it
  • Example: single-type GPUs in different VCs
  • Example: multi-type GPUs in different VCs
  • How to grant VC to user groups (both AAD mode and auth mode)
• How to Add / Remove Node (need help) @ydye
  • Guide to add / remove nodes (add link to "How to Setup Virtual Clusters" because hivedscheduler config needs change, too)
  • Example: setup multi-type GPUs and split them into multiple Virtual Clusters
• How to use CPU Nodes
  • How to add CPU nodes and setup CPU-only VC
  • How to submit CPU-only job
• How to customize cluster by plugins
  • how to enable (install) a webportal plugin
• Troubleshooting (need help)
  • What if GPU is not detected
  • What if some node is lost
  • What if some PAI service is not working
• How to Uninstall OpenPAI
• Upgrade Guide (needed in future)

Contents for PAI developer Manual

• OpenPAI Basic Design and Architecture
  • OpenPAI and Kubernetes (e.g. Framework Controller)
    • How OpenPAI uses Kubernetes
    • Lifetime Management of OpenPAI Jobs (need help) @yifan
  • OpenPAI optimization for deep learning jobs (need help)
    • How OpenPAI uses Nvidia-docker
• Developer interface
  • [Docs] OpenAPI docs for RESTful API [Docs] OpenAPI docs for RESTful API #3996
  • Use SDK
    • Brief Usage introduction
    • Reference link to SDK
• How OpenPAI Manages Storage
• Network Management of Mixed Cloud Environment (need help) @fanyangCS
• How to Develop a Runtime Plugin (need help) @yqwang-ms
• [How to Develop a Webportal Plugin] @Binyang2014 (https://github.com/microsoft/pai/blob/d659ffd97dedfc23ce1b06eebc2911b9c6592ac7/docs/webportal/PLUGINS.md#provide-plugin-configurations)
• How to Configure Framework Controller (need help) @yqwang-ms
• How to Customize Job Protocol (need help) @abuccts
• How to Develop a Scheduler (need help) @yqwang-ms

Contents for design documentation (to be updated @hzy46 )

• OpenPAI overview
• OpenPAI architecture and component introduction

[fanyangCS]

related #2130 and #1763