Generate docs for sdk with `sphinx`

Overview

This doc shows how to generate docs like azure-sdk site

Prerequisites

• python 3.7+

Steps

Assuming you have a project that the structure is like:

Project
|__azure
|  |_...
|__setup.py

(1) create virtual environment, please refer to venv

(2) step into Project, download docs.zip and decompress it in your Project.

(3) install your Project locally

(venv) PS C:\dev\azure-sdk-for-python\sdk\apicenter\azure-mgmt-apicenter> pip install -e .

(3) setp into docs and install dependency:

(venv) PS C:\dev\azure-sdk-for-python\sdk\apicenter\azure-mgmt-apicenter\docs> pip install -r requirements.txt

(4) set environment variable:

(venv) PS C:\dev\azure-sdk-for-python\sdk\apicenter\azure-mgmt-apicenter\docs> $env:SPHINX_APIDOC_OPTIONS="members,undoc-members,inherited-members"

(5) build doc api:

(venv) PS C:\dev\azure-sdk-for-python\sdk\apicenter\azure-mgmt-apicenter\docs> sphinx-apidoc -f -o . ..\azure

(6) generate html doc

(venv) PS C:\dev\azure-sdk-for-python\sdk\apicenter\azure-mgmt-apicenter\docs>  sphinx-build -b html . _build

Then you can find there will be index.html in folder _build. Every time when you update your sdk code, just repeat (5) and (6) to update the doc