Upload Sphinx Html to Readthedocs From Travis

travis-sphinx

A standalone script for automated edifice and deploying of sphinx docs via travis-ci

What does it do?

travis-sphinx aims to take the hassle out of edifice and pushing docs to your gh-pages. deploying to your github page can exist tedious specially when you're making many small changes overtime or fifty-fifty simply making a minor revision you lot'd like to come across live; travis-sphinx will automate your build and deploy process with the help of travis-ci!

• Installation
• Getting Started
  • Obtaining a personal access token
  • Calling travis-sphinx
  • Custom repository deployment
• Example
• Assist

Check out cadquery for a live case of travis-sphinx in action!

Installation

              pip install --user travis-sphinx export PATH=$Abode/.local/bin:$PATH                          

Getting Started

If you lot aren't already familiar with travis-ci, take a look at their getting-started guide. Otherwise the steps beneath volition outline how to get travis-sphinx running in your repository

The first step y'all'll need to practise is simply make sure you have a gh-pages branch that exists, if information technology doesn't:

              git checkout -b gh-pages git rm -rf . git push --fix-upstream origin gh-pages                          

Obtaining a Personal Access Token

travis-sphinx requires a personal access token to be able to push changes to gh-pages, so you'll need to generate a token to use. Head over to your github account settings:

To generate a token: go to personal admission tokens and click generate new token. Make sure to copy this to your clipboard for the next pace!

The easiest way to prepare this token is to caput over to https://travis-ci.org/ and click on settings for the repository you'll be using travis-sphinx with. You can add the token past specifying it in the enviroment variable under the proper noun GH_TOKEN. You tin besides follow this tutorial on giving travis permissions, but the first options is much more simple

Now travis-sphinx can push to your gh-pages, all washed! The side by side step is calling travis-sphinx within your .travis.yml

Calling travis-sphinx

Once your personal access token is setup, y'all can begin using travis-sphinx within your configuration file. The two calls that should exist used are:

              script:     - travis-sphinx build      after_success:     - travis-sphinx deploy                          

build volition generate the actual documentation files while deploy will move those files to gh-pages. If you don't have your documentation in the standard docs/source path, you tin can specify where they are with --source. This tool also assumes that you would like to build and deploy the principal branch and whatever tags pushed. If you would similar to point the tool elsewhere, this tin be solved using --branches , east.g. travis-sphinx --branches=test,production volition build and deploy on merely the exam and production branches.

              script:     - travis-sphinx build --source=other/dir/doctor      after_success:     - travis-sphinx deploy                          

Specifying a Custom Deploy Repository

Per #38, you can at present specify a custom deployment repository if yous're using a fork for working on documentation. To do so, under your travis surround variables, using the following constant:

              GH_REPO_SLUG = 'syntaf/fork-of-my-repo'                          

Instance Configuration

note: See this repositories .travis.yml for a simpler configuration script. The below script is for conda environments which have a number of dependencies that as well need to be installed.

              language: python - "2.7"  # before_install will simply setup a conda enviroment for installing python packages, if yous # take project dependencies information technology's commonly recommended to become this route before_install:     - wget http://repo.continuum.io/miniconda/Miniconda-latest-Linux-x86_64.sh -O miniconda.sh     - chmod +x miniconda.sh     - "./miniconda.sh -b"     - export PATH=/home/travis/miniconda2/bin:$PATH     - conda update --yes conda     - sudo rm -rf /dev/shm     - sudo ln -s /run/shm /dev/shm  install:     - conda install --yeah python="ii.7" sphinx     - pip install --user travis-sphinx  script:     - travis-sphinx build  after_success:     - travis-sphinx deploy                          

Too see a working example at the dnppy repository

Assist

              Usage: travis-sphinx [OPTIONS] Control [ARGS]...  Options:   --version               Bear witness the version and leave.   -v, --verbose   -o, --outdir DIRECTORY  Directory to put html docs, default is target                           [default: doc/build]   --help                  Evidence this message and exit.  Commands:   build   Build sphinx documentation.   deploy  Deploy sphinx docs to gh_pages branch by...   Usage: travis-sphinx build [OPTIONS]    Build sphinx documentation.  Options:   -s, --source DIRECTORY  Source directory of sphinx docs  [default:                           dr./source]   -n, --nowarn BOOLEAN    Do not mistake on warnings   --assistance                  Evidence this bulletin and exit.   Usage: travis-sphinx deploy [OPTIONS]    Deploy sphinx docs to gh_pages co-operative past pulling from output dir.  Options:   -b, --branches TEXT     Comma separated listing of branches to build on                           [default: main]   -c, --cname TEXT        Write a CNAME file with the given CNAME.   -thousand, --message TEXT      The commit message to use on the target co-operative.                           [default: Update documentation]   -ten, --deploy-host TEXT  Specify a custom domain for GitHub, useful for                           enterprise domains.  [default: github.com]   --help                  Show this bulletin and exit.                          

parrywalonly.blogspot.com

Source: https://github.com/Syntaf/travis-sphinx

Share this post