Automated Documentation Publishing Pipeline with VSTS, Azure, Docker, and GitHub Sync

Many developers write technical documents in Markdown or reStructuredText and host them on GitHub, but the reading experience can be poor and they may want only HTML output.

ReadTheDocs provides nice responsive documentation but suffers from slow access due to overseas servers; self‑hosting ReadTheDocs in an Azure data center improves speed but the build process is unstable because of many dependencies.

Therefore the author built a custom automated documentation pipeline that triggers on source commit, compiles reST/Markdown to HTML, uploads via FTP to an Azure website, and stores a zipped backup in VSTS.

Steps to configure the pipeline:

1. Create a Git repository in VSTS, add the documentation source, and write a build script sphinx-build -b html ./docs/ ./_build/ .

2. Create an Azure Website and obtain FTP credentials.

3. Define a VSTS build definition that runs the script, uploads the HTML via FTP, and publishes the zip as an artifact.

4. Add a GitHub sync definition that pulls the repo and pushes changes back to GitHub using commands such as git pull https://github.com/lean-soft/$(Build.Repository.Name).git master and git push https://$(github-token)@github.com/lean-soft/$(Build.Repository.Name).git head:master .

The pipeline consists of four stages: execute build.sh , FTP upload, publish zip artifact, and GitHub synchronization.

Later improvements include running Sphinx inside a Docker container with docker run -it -v $(Build.Repository.LocalPath):/documents/ --name docs-build-container -w /documents/ --rm docker-sphinx:1 bash ./build.sh , and switching to Microsoft’s hosted Linux build agents.

All generated documentation is available at http://docs.devopshub.cn/ and the source can be found at https://github.com/lean-soft .