5. Publishing the docs with Travis

We need to tell Travis to:

1. Install everything required by our project.

2. Build the docs.

3. Run some tests via Vale. See the previous step.

4. Publish the docs on GitHub pages.

5.1. Generating a Travis token

You need to create a Travis token to allow it to use your GitHub account account.

1. Log in to your GitHub account and go into Settings > Developer settings > Personal access tokens

2. Click Generate new token, add a description, such as Travis token and tick the repo checkbox then click Generate token.

3. Copy the token.

4. From the Travis settings page of your repository, add a new encrypted environment variable called token:

   

5.2. Creating the Travis config file

To automate the publishing of the documentation, Travis looks for a .travis.yml file to know what to do. Let’s define it:

1. Create .travis.yml at the root of your repository.

2. Dump the following content into the file:

   dist: xenial # needed to use python 3.7
   language: python
   branches:
     only:
       - master
   python:
     - 3.7
   install:
     - pip install -U pip
     - pip install pipenv
     - pipenv install # set up the environment
     - curl -sfL https://install.goreleaser.com/github.com/ValeLint/vale.sh | sh -s v2.1.0 # install vale
     - export PATH="./bin:$PATH"
   script:
     - skip # Travis requires a `script` property, but we do not need it
   stages:
     - build and test
     - deploy
   jobs:
     include:
       - stage: build and test # This stage builds and lints in parallel
         name: Build
         script: pipenv run make html # build the docs
       - script: vale --minAlertLevel error source # run vale
         name: Test
       - stage: deploy
         name: Deploy to GitHub Pages
         if: (NOT type IN (pull_request)) AND (branch = master) # only deploy if merging on master
         script: pipenv run make html
         deploy:
           provider: pages # deploy on github pages
           skip_cleanup: true
           github_token: "$token" # defined via the Travis interface
           local_dir: build/html
   

   This file tells to Travis to apply the following steps:

   1. Set up a system that runs Python 3.8.2.

   2. Install pip and install all the Python modules contained in the requirements.txt or Pipfile file.

   3. Define 2 stages: build and test and deploy. Stages are run sequentially but run the jobs they contain in parallel. A failed stage cancels the following stages.

      build and test does the following:

      1. Run make html to build the docs.

      2. Run Vale to check for style issues.

      Deploy deploys the docs to GitHub pages if the building and tests are successful.

3. Commit and push your file to your master branch.

From now on, every time you push to the master branch, Travis builds the latest version of the docs and publishes the output on github pages just like this current website published on GitHub Pages.

You can bend this setup as needed, for example you can call your own publishing script. You can use that script to publish your output files on Amazon S3, or copy the output files to your Apache server… Whatever works for you!

If you managed to do all this by yourself, you should be able to befriend a developer to complete the project.