diff --git a/docs/docs/publish-azure-devops.md b/docs/docs/publish-azure-devops.md new file mode 100644 index 00000000000..c34beabd4c6 --- /dev/null +++ b/docs/docs/publish-azure-devops.md @@ -0,0 +1,100 @@ +# Deploy to GitHub Pages from Azure DevOps + + +### 1. **Create a GitHub Personal Access Token (PAT)** +You will need a GitHub PAT with repo permissions to allow Azure DevOps to push to the GitHub Pages branch. + +- Go to your GitHub account > **Settings** > **Developer settings** > **Personal Access Tokens**. +- Click on **Generate new token** and select the required repo permissions. +- Save the token somewhere secure as it will be used in the Azure DevOps pipeline. + +### 2. **Create Azure DevOps Pipeline** + +#### a. **Setup DocFX** +Ensure that you have a `docfx.json` configuration file in your repository. This will define how DocFX generates your documentation. + +- Install DocFX locally on your development machine and create the configuration: + + ```bash + docfx init -q + ``` + +This will generate the `docfx.json` file, which you can configure to specify input and output directories, build settings, etc. + +#### b. **Azure Pipelines YAML File** + +Create an Azure DevOps pipeline YAML file (e.g., `azure-pipelines.yml`) in the root of your project to automate the build and deployment. + +Here is a sample pipeline YAML configuration for DocFX: + +```yaml +trigger: + branches: + include: + - main # Trigger on main branch + +pool: + vmImage: 'ubuntu-latest' # Use the latest Ubuntu VM + +variables: + - group: GitHubPAT + +steps: + # Step 1: Install DocFX + - task: UseDotNet@2 + inputs: + packageType: 'sdk' + version: '8.x' # Ensure you have .NET SDK installed + installationPath: $(Agent.ToolsDirectory)/dotnet + + - script: | + dotnet tool install -g docfx + displayName: 'Install DocFX' + + # Step 2: Build the Documentation using DocFX + - script: | + docfx build + displayName: 'Build Documentation' + + # Step 3: Deploy to GitHub Pages + - task: Bash@3 + displayName: 'Deploy to GitHub Pages' + inputs: + targetType: 'inline' + script: | + git config --global user.email "your-email@example.com" + git config --global user.name "Your Name" + git clone --branch gh-pages https://$GITHUB_PAT@github.com/$GITHUB_REPO.git out + rm -rf out/* + cp -r _site/* out/ + cd out + git add --all + git commit -m "Update documentation" + git push origin gh-pages + env: + GITHUB_PAT: $(GITHUB_PAT) # The GitHub Personal Access Token + GITHUB_REPO: your-github-username/your-repo-name # Update with your repo details +``` + +#### c. **Setup Azure Pipeline Variables** + +- Go to **Azure DevOps** > **Pipelines** > **Library**. +- Create a new pipeline variable group called GitHubPAT. +- Add a new variable named GITHUB_PAT and set the value to the GitHub Personal Access Token you created earlier. Mark this variable as secret. + +### 3. **Configure GitHub Pages** + +- Go to your GitHub repository. +- Under **Settings** > **Pages**, set the source branch to gh-pages. + +### 4. **Run the Pipeline** + +- Commit the azure-pipelines.yml file to your repository and trigger the pipeline. +- Azure DevOps will now: + 1. Install DocFX. + 2. Build the documentation. + 3. Deploy the documentation to the gh-pages branch in GitHub. + +### 5. **Access the Documentation** + +After the pipeline finishes, your documentation will be available in the github-pages deployments. \ No newline at end of file diff --git a/docs/docs/toc.yml b/docs/docs/toc.yml index 711c69513ac..7f1b3a150c9 100644 --- a/docs/docs/toc.yml +++ b/docs/docs/toc.yml @@ -14,6 +14,7 @@ - name: Advanced - href: additional-languages.md +- href: ./publish-azure-devops.md - name: Reference - href: ../reference/docfx-json-reference.md