Running Sphinx in VSTS Hosted Pipeline

This method requires you to commit Sphinx and it’s dependencies to your source repository. While this may seem heavy, it’s required because of the limited nature of hosted pipelines in Visual Studio Team Services.

First, make sure you use the “Hosted” agent, not “Hosted VS2017”, since “Hosted” comes with Python 2.7 installed (2.7.3 at the time of this writing).

This guide assumes your documentation is based on sphinx-quickstart with a make.bat file.

Prepare Your Repository

Install needed packages into your repository by running the following commands in your source directory:

pip install setuptools -t site-packages
pip install sphinx -t site-packages

These commands installs the dependencies in a folder called site-packages.

Configure make.bat

In order for Python to find your packages at runtime, add the following to your make.bat file:

set PYTHONPATH=site-packages

Configure Sphinx to Ignore site-packages Folder

Your site-packages folder will contain sphinx documentation for the projects within it. In order for your build to ignore these files, exclude_patterns variable in conf.py and add site-packages to the array:

exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', 'site-packages']

Configure Build Task

All you need now is a build task that runs the make.bat file. For example, for building html, your task could look like this: