Shulou(Shulou.com)06/01 Report--

This article to share with you is about how to use Github Actions to automatically update docfx documents, Xiaobian feel quite practical, so share with you to learn, I hope you can gain something after reading this article, not much to say, follow Xiaobian to see it.

Automatically update docfx documents with Github Actions Intro

docfx is a. NET API documentation framework produced by Microsoft. There is an idea that code is documentation. API documentation will be generated automatically according to project code. Even if no comments are written, API documentation will be generated. There are also some default themes that can be configured or customized. For details, please refer to the official introduction https://dotnet.github.io/docfx/

At present, there are many projects using docfx to generate documents, such as the Reserver-Proxy project introduced some time ago, but also saw the reservse-proxy project configured with a Github Actions to automatically update documents, so in my own project also added a similar configuration, in addition to Microsoft projects there are many community open source projects in use, if you are also doing some. NET class library open source projects, you can try

docfx how to use can refer to the official documentation, this article mainly describes how to use Github Actions to automatically update documents

document example

More information can be found at https://weihanli.github.io/WeihanLi.Npoi/index.html

Automatic document update process Check out the branch code to be used to generate documents Install docfx command line tool, recommend choco installation, because Chocolatey is already installed on the agent executing build Use docfx to generate documents Check out gh-pages branch, branch for hosting documents Delete files before gh-pages (The.git directory contains git information and cannot be deleted) Copy the document generated in step 3 to the gh-pages branch commit && push, submit the code and push the update online document Github Actions example configuration

Actions example, source link: https://github.com/WeihanLi/WeihanLi.Npoi/blob/dev/.github/workflows/docfx.yml

name: docfx buildon: push: branches: - devjobs: build: name: Build runs-on: windows-latest steps: # Check out the branch that triggered this workflow to the 'source' subdirectory - name: Checkout Code uses: actions/checkout@v2 with: ref: dev path: source - name: install DocFX run: "& choco install docfx -y" # Run a build - name: Build docs run: "& docfx ./ docfx.json" working-directory: ./ source # Check out gh-pages branch to the 'docs' subdirectory - name: Checkout docs uses: actions/checkout@v2 with: ref: gh-pages path: docs # Sync the site - name: Clear docs repo run: Get-ChildItem -Force -Exclude .git | ForEach-Object { Remove-Item -Recurse -Verbose -Force $_ } working-directory: ./ docs - name: Sync new content run: Copy-Item -Recurse -Verbose -Force "$env:GITHUB_WORKSPACE/source/_site/*"> working-directory: ./ docs # update docs - name: Commit to gh-pages and push run: | $ErrorActionPreference = "Continue" git add -A git diff HEAD --exit-code if ($LASTEXITCODE -eq 0) { Write-Host "No changes to commit! " } else { git config --global user.name "github-actions-docfx[bot]" git config --global user.email "weihanli@outlook.com" git commit -m "Updated docs from commit $env:GITHUB_SHA on $env:GITHUB_REF" git remote set-url origin https://x-access-token:${{ secrets.GITHUB_TOKEN }}@github.com/${{ github.repository }} git push origin gh-pages } working-directory: ./ docs I'm here as long as the dev branch is updated, you can also update it when the master branch is updated as needed, modify the branch name

Now using version 2.x, version 3.x has not yet been released, version 3.x can be directly installed through dotnet tool more convenient and extensible, currently 2.x using choco to install command-line tools, need to rely on Chocolatey, if dotnet tool dotnet environment can be, you can be a lot more convenient

Not only does docfx generate documentation, you can also extend other similar requirements, using Github Actions to achieve automatic synchronization and updates.

The above is how to use Github Actions to automatically update docfx documents. Xiaobian believes that some knowledge points may be seen or used in our daily work. I hope you can learn more from this article. For more details, please follow the industry information channel.

Welcome to subscribe "Shulou Technology Information " to get latest news, interesting things and hot topics in the IT industry, and controls the hottest and latest Internet news, technology news and IT industry trends.