Continuous deployment

Continuous deployment is a way to deploy (publish) software automatically and in short cycles. Typically, the process is build the software, test the software, deploy. If any of these steps fails, the process is interrupted.

Sphinx, like other static website generators, is really easy to use and can be used along GitHub and Travis.

Prerequisites

In this tutorial we assume that you have some prerequisite knowledge about:

• GitHub (how to use it on a basic level, what is a branch, what is a pull request…)

• Sphinx (how to install it, how to build the output, what are extensions…)

Final setup

The result of the tutorial is the following setup:

1. A central Git repository that contains the documentation sources.

2. Every time a pull request is sent to the master repository:

   1. Build the documentation using the source files of the branch.

   2. Run tests on the documentation:

      1. Check the links

      2. Check the spelling

      3. Check the English quality

   3. If all the tests pass, merge the pull request into Master.

3. On every merge into Master:

   1. Build the docs.

   2. Run the tests (same tests as on the pull request).

   3. If the tests are passing, publish the output to GitHub Pages.

This kind of setup saves a lot of time to any technical writer and is fairly simple to create.

The other advantage is that it allows contributions from any member of your company, as long as they have access to GitHub and a basic understanding of it.

Let’s get started.

Tutorial

• 1. Configuring the repository
• 2. Creating a development environment
• 3. Linking GitHub and Travis
• 4. Setting up tests
  • 4.1. Defining styles
  • 4.2. Running Vale
• 5. Publishing the docs with Travis
  • 5.1. Generating a Travis token
  • 5.2. Creating the Travis config file
• 6. Using Docker
  • 6.1. Creating a Dockerfile
    • 6.1.1. Choosing the base image
    • 6.1.2. Installing the dependencies
    • 6.1.3. Setting the work directory
    • 6.1.4. Copying files
    • 6.1.5. Installing the dependencies
  • 6.2. Building the image
  • 6.3. Using the image
  • 6.4. Next steps